Date: Thu, 28 Mar 2024 21:09:39 +0000 (UTC) Message-ID: <631375622.5.1711660179864@d0fce641403c> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4_840325099.1711660179863" ------=_Part_4_840325099.1711660179863 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The <Sessions>
element broadly spea=
king controls how the SSO process is managed by the SP. It typically contai=
ns a number of child elements called "handlers" that act together to provid=
e the core SAML functionality of the software. It also contains settings th=
at govern how long SSO sessions last and how they're protected from certain=
kinds of attacks.
Each <ApplicationOverride> =
;inherits the default settings and endpoints defined at the top level, and =
can contain its own <Sessions>
element, if nee=
ded, to add additional endpoints. Note that if you supply a <=
Sessions>
element in an override, virtually none of its indi=
vidual XML attribute properties will be inherited from the default element.=
You must supply almost all of them that you want to have non-defaulted val=
ues. In contrast, the elements from the parent <Sessions><=
/code> element do get inherited/used if you don't override them. It's =
not terribly intuitive, an artifact of the code. See Inheritance Rules for more d=
etails.
Please take note of the redirectLimit
setting and your curr=
ent posture. For compatibility reasons, the underlying default for this set=
ting remains =E2=80=9Cnone=E2=80=9D, which allows the SP to be manipulated =
into serving as an open redirector.
The project=E2=80=99s position is that this is not a security issue, jus= t a suboptimal default that will be changed in a future major update to the= software. As of several releases ago, the shipping default explicitly sets= this to =E2=80=9Cexact=E2=80=9D instead (which will be the underlying defa= ult in the future), and we encourage deployers to ensure that the setting m= atches their intended posture.
Name |
Type |
Default |
Description |
---|---|---|---|
handlerURL |
URL |
/Shibboleth.sso |
The base location on the server that dispatches requests to the handlers= configured inside the <Sessions> element. |
handlerSSL |
boolean |
true |
When true, only web requests over SSL/TLS will be processed by handlers.= Other requests may be blocked, or possibly ignored (and usually result in = a 404 error) depending on the web server, but will never be processed. This= is useful for sites that want to protect SAML protocol traffic but leave a= ctual content unencrypted. |
lifetime |
seconds |
28800 (8 hours) |
Maximum duration in seconds that a session maintained by the S= P will be valid. The actual time may be less than this value (if an IdP ind= icates it should be shorter) but will never be longer. Note that this will = not influence sessions maintained by an application. |
timeout |
seconds |
3600 (1 hour) |
Maximum inactivity allowed between requests in a session maintained by t= he SP. This inactivity applies only to requests to this SP and is not aware= of activity between the browser and other web sites (or even other applications on this system). A value of 0 disables timeout checking, but the expiration of the sessio= n may be otherwise bounded by the cacheAllowance setting on the SessionCache. |
maxTimeSinceAuthn |
seconds |
|
If set, the SP rejects assertions that indicate the user's actual time o= f authentication to the IdP is older than the difference between the curren= t time and this value. Essentially this limits the amount of time between t= he act of authentication and the attempt to access the SP. This can be usef= ul to ensure that the SAML 2.0 ForceAuthn flag was honored. = td> |
checkAddress |
boolean |
true |
The IdP will place the IP address of the user agent it authenticated int= o the assertions it issues. When true, the SP will check this address again= st the address of the client presenting an assertion before creating a sess= ion. While useful for security, NAT and proxy usage (as well as IPv6 suppor= t on only either the webserver hosting the IdP or the SP) often make this s= etting a source of errors. |
consistentAddress |
boolean |
true |
When true, the SP will remember the IP address used when creating a sess= ion and ensure that all subsequent access associated with this session come= from the same address. This can help protect against cookie theft and is l= ess likely than the checkAddress setting to block legitimate acce= ss. |
cookieName |
string |
|
Rarely needed, this can be used to override part of the names used for c= ookies maintained by the SP. The name is used in combination with other val= ues that are part of the SP implementation and not documented. It is not me= ant to allow full control over the name but can be useful in some scenarios= in which virtual server domains overlap |
cookieProps |
string |
"; path=3D/; HttpOnly" |
If set to a custom string, the string is appended to the cookie values m=
aintained by the SP. Used to attach custom meta-properties like path&n=
bsp;or the secure and HttpOnly flags to the cookies. This property can also be set to a pair of built-in values, "http"&= nbsp;and "https", which expand to the default and SSL-only properties = respectively. Do not include a SameSite attribute, as this is either automa= tic for most cross-site cases or can be controlled with the sameSiteSe= ssion property below. |
sameSiteSession 3.1 |
"None", "Lax", "Strict" |
|
Allows session and session recovery cookies to be assigned a SameSite at= tribute. Omitting this setting results in behavior that will depend on the = browser. Note that "Strict" is provided for completeness but will generally= be non-functional because of when these cookies are set. |
sameSiteFallback 3.1 |
boolean |
false |
This enables a workaround for a Safari bug<= /a> and causes a second cookie to be set in any case that a cookie is being= set with a SameSite=3DNone attribute. It should be removed once support fo= r out of date versions is no longer required. |
idpHistory |
boolean |
false |
When true, the SP will maintain a SAML "discovery" cookie in the browser= by adding any identity provider successfully used to the cookie. |
idpHistoryDays |
days |
Determines how long the history cookie will persist. If not set, the coo= kie will expire when the browser closes. |
|
exportLocation |
URL (relative/absolute) |
|
This is the handler location supporting local lookup of raw SAML asserti= ons cached with a session (see this topic). W= hen absolute, you can override the usual insertion of the hostname and forc= e the use of "localhost". When relative, it expands much like any handler's= Location attribute. Note that using an absolute hostname like "l= ocalhost" results in an application-specific location that can't be inherit= ed by ApplicationOverride elements. You'll need to supply a custo= m <Sessions> element with its own value for this attribute = as well as all the other usual settings. |
exportACL |
space-delimited |
127.0.0.1 |
The set of requesters allowed to query the SP for assertions using the m= echanism described in the Assertion Export <= /a>topic. This should almost always be left as "127.0.0.1" (or "::1" for IP= v6) to prevent third parties from viewing sensitive data about users. No ot= her security mechanism is currently supported. IPv6 addresses must be provi= ded in the non-dotted format with lower case letters and without padding '0= 's. E.g. "2001:620:0:40:c62c:3ff:abc:123" |
cookieLifetime |
seconds |
|
If set, cookies used for session management will be created with the des= ignated lifetime. When omitted, which is the default, such cookies are in-m= emory only and do not persist across browser restarts (assuming various ses= sion restore features aren't in use). Note that this will not affect "trans= itory" cookies used for maintaining state across redirects. |
|
string |
|
Allows for the preservation of form POST data (with Content-Type applica= tion/x-www-form-urlencoded) across SSO on supported platforms and identifie= s the mechanism for preserving that data. Currently this MUST tak= e the form "ss:<id>" where <id> is the ID of a configured = StorageService plugin. |
postTemplate |
path to file |
|
Path to an HTML template with the markup necessary to carry replayed for= m POST data and if possible prevent accidental replay if the back button is= hit. Refer to the default pos= tTemplate.html file as a guide. |
postLimit |
number of bytes |
1024 * 1024 |
A maximum number of bytes to allow when saving off POST data. Over this = limit, a warning in the log will appear, but the data will not be saved. |
postExpire |
boolean |
true |
If set, causes the HTTP response containing to-be-replayed form POST dat= a to be expired and non-cacheable by the server using the usual mix of resp= onse headers. Can be adjusted to accommodate varying strategies for back-bu= tton/replay prevention. |
relayState |
string |
|
Controls how information associated with requests for authentication, pr= imarily the original resource accessed, is preserved for the completion of = the authentication process. If not specified, the resource URL is passed by= value to the IdP, when possible. A value of "cookie" causes the URL to be = saved in a cookie, to protect the user's privacy. A third option, which is = recommended, is to use the SP's persistent storage by specifying a value of= the form "ss:id", where id references a <Stor= ageService> element, typically "ss:mem". The "cookie" option ca= n include a ":n" suffix, where n specifies the number of cookies to permit = before purging old ones, defaulting to 25. |
redirectLimit |
V3.2+: Earlier: |
"none" Recent (3.1+) default configurations as shipped set this to "exact" expl= icitly |
Prevents the injection of redirect locations after login or logout that = don't meet specific criteria, to prevent misusing the SP to carry out phish= ing attacks. "none" is the default and does no limiting ( Consider carefully before usin= g this option as it can allow malicious use of your SP as an open redirect)= . "exact" requires that the destination match the exact scheme, hostname, = and port of the handler performing the redirect. "host" requires that the destination match the hostname of the handler p= erforming the redirect. "allow" / "whitelist" requires that the destination's "scheme://hostname= [:port]/" matches an allowed list of whitespace-delimited URL prefixes. All= ows explicit permission to send the client off-host to external systems. Th= e list of URL prefixes are set via the redirectAllow (formerly redirec= tWhitelist) setting. "exact+allow" / "exact+whitelist" combines the "exact" and "allow" polic= ies above, without requiring explicit enumeration of the handler's vhost.= p> "host+allow" / "host+whitelist" combines the "host" and "allow" policies= above, without requiring explicit enumeration of the handler's host. = td> |
redirectAllow (V3.2+) redirectWhitelist (Older) |
whitespace-delimited URL prefixes |
|
One or more whitespace-delimited URL prefixes of the form "scheme://host= name[:port]/". Used with subset of redirectLimit values above. Don't f= orget the trailing slash because e.g. specifying "https://example.com" also= allows example.com.evil.com etc. |
idpHistoryProps |
string |
"; path=3D/;" |
May be used to override the standard cookieProps setting for t= he SAML "discovery" cookie enabled by the idpHistory flag. Primar= ily this is useful if there's a need for the discovery cookie to be accessi= ble to client side scripts (while leaving the HttpOnly property e= nabled for other cookies). |
Virtually all configurations should stick to the simplified syntax for a= uto-configuring protocol-related handlers in terms of "services" and "proto= cols". The currently supported services are:
A service is enabled by including the corresponding child element(s). Ea= ch service element contains a set of properties to configure the service, a= nd the element's value is a list of protocol names that the SP supports. Ea= ch supported service element can appear only once, as this is a simplified = approach that is meant to capture all of that function's behavior in a sing= le element. More advanced cases may require reverting to older syntaxes, bu= t this isn't usually necessary and you may want to ask on the support list = before reverting to that.
These services and names are used to locate detailed information about t=
he handlers to install based on a <
ProtocolProvider>
plugin. The implementation su=
pplied with the SP relies on a separate configuration file to spell out the=
detailed information that used to appear within the <Session=
s>
element.
You can still plugin all of the older information by hand if you need un= usual settings or more control over the internals but that will create a mu= ch higher burden on future maintainers of your configuration so should usua= lly be avoided. If you absolutely have to do it, it's best to replace the n= ew elements entirely to avoid unforeseen overlaps and interactions.
The usual content of the <Sessions>
element will=
be one or more "service" elements, along with an optional set of custom&nb=
sp;<Handler> elements for more general features=
.
Name |
Cardinality |
Description |
---|---|---|
<SSO> |
0 or more |
Enables support for one or more Single Sign-On / Authentication protocol= s |
0 or more |
Enables support for one or more Logout protocols. |
|
0 or more |
Enables support for one or more NameID Management protocols. Rarely used= . |
|
<Handler> |
0 or more |
Generic endpoint for non-specific functionality implemented by the SP or= an extension library. |
The above three elements are shorthand configuration for a more complex = mechanism as described below using explicit handlers.
Handlers perform the work of the SP apart from the general request filte= ring work it performs for all requests. While handlers are essentially just= mini-applications that could be built as CGI scripts, they're implemented = inside the SP to avoid scripting language dependencies and to provide them = with full access to the SP library API.
The SP uses a model in which handlers are dispatched based on "path info= " that is appended to a base location that acts as a kind of virtual resour= ce that the web server knows about and asks the SP software to implement. S= ometimes this is referred to by the web server as a script mapping or handl= er.
Because the SP's handlers have to know which application is receiving a request, each application has to be assigned a unique "base location=
", which is called a handlerURL
. By convention, this base=
location is "/Shibboleth.sso".
Often, each application spans a =
particular virtual host, and the base location is simply "/Shibb=
oleth.sso"
on that vhost. In more advanced cases, an application might live inside a subset of a v=
irtual host's document tree. In that case, the base location has to be insi=
de that document tree (e.g., "/path/Shibboleth.sso"
). Thi=
s is strongly discouraged, as it is very hard to configure.
Each handler element has a Location
XML attribute=
that, when appended to the base location, provides the full path to the ha=
ndler. Combining that path with the virtual host's scheme, hostname, and po=
rt, you have the full URL of the handler:
http(s)= :// + hostname + [:port] + handlerURL + Location
If you require to access the handler URL from your code (for example to = trigger a login), the "Shib-Handler" attribute is availble set to the full = path above (minus the Location) for a programatic way to access the path se= t in the configuration.
In turn, these endpoint locations are usually supplied to partner sites = in Metadata. When they don't match the metadata, = various errors will result.
The advanced child elements listed below have variants for each protocol= type and are documented as such. However deployers are liable to care abou= t a particular protocol.
There is also support for Local-only logout= a>.
The usual content of the <Sessions>
element=
will be one or more "service" elements, along with an optional set of cust=
om <Handler> elements.
Name |
Cardinality |
Description |
---|---|---|
0 or more |
Initiates sessions by creating an a request for authentication specific =
to a particular SSO protocol, or invoking some kind of IdP discovery mechanism. |
|
0 or more |
Terminates a session by invoking some kind of logout process, which may =
be local to the SP or global to the SSO environment. |
|
0 or more |
Incoming entry point for messages carrying SAML SSO assertions to initia=
te a user session. The terminology is borrowed from the SAML spec (as is th=
e actual element). |
|
<md:ArtifactResolutionService><= /p> |
0 or more |
Incoming SOAP endpoint for the resolution of SAML 2.0 artifacts into pro=
tocol messages. This is used when transmitting outbound messages =
as artifacts by the SP, which is borderline unheard of. (Artifacts issued b=
y an IdP are processed by other endpoints.) The terminology is borrowed fro=
m the SAML spec (as is the actual element). |
0 or more |
Incoming entry point for single logout protocol messages from an IdP (ac=
ting in its role as a session authority). The terminology is borrowed from =
the SAML spec (as is the actual element). |
|
0 or more |
Incoming entry point for NameID management messages from an IdP. The ter=
minology is borrowed from the SAML spec (as is the actual element). |