| Table of Contents |
|---|
Overview
The <ApplicationDefaults> element defines most of the runtime behavior of the software when it comes to SAML behavior and application session policy. In rare cases, this can be further broken down more granularly by nesting <ApplicationOverride> elements to override behavior for different virtual hosts, or in very ill-advised cases, different paths.
| Tip |
|---|
The usual pattern is to define most of this information once, in the outer element. Most of the things you might want to override can be handled more elegantly without explicit use of the <ApplicationOverride> feature. You should not use overrides to segregate traffic from different IdPs; that's an anti-pattern. The set of IdPs you trust should be a global consideration and you should authorize individual access based on the attributes in the user's session. |
Every request to the web server is associated with what the SP denotes an "application" by the request mapper component. An application represents distinct collections of resources within the server's document tree that share the same general configuration requirements, although access control can be enforced on a finer-grained basis.
Repeating: in most cases, all requests should be left to map to the "default" application represented by this outer element, but the majority of the SP's more advanced functionality can, if needs must, be defined on a per-application basis. Supported protocol endpoints and handlers, security policies, credentials for signing, encryption, and TLS, attribute extraction/resolution/filtering are just some of the options handled here. When a resource protected by the SP absolutely needs distinct behavior in these kinds of areas, a new application needs to be defined and referenced by the request mapper using the applicationId property.
Basic Configuration
The default configuration of the <ApplicationDefaults> element and most of its subelements will work in most circumstances with a few modifications:
The
entityIDattribute on the<ApplicationDefaults>element needs to be changed to the SAML entityID you'd like to use for your SP deployment. This must be the value your federations and partners are expecting and should be carefully chosen to be a permanent and representative URL denoting your service. It does not necessarily equate to the hostname(s) at which your service runs, particularly in cases where you may have a multiitude of virtual hosts for different customers. Do not create an entityID for each customer; that's an anti-pattern in general and also tends to work very poorly with a lot of federations that make common use of Shibboleth.
Configure SSO to an IdP or with a Discovery Service
To use a specific IdP, change the
entityIDsetting in the <SSO> element to match the value in that IdP's metadata.To use a discovery service (e.g. our EDS), remove the
entityIDsetting in the <SSO> element, and set thediscoveryProtocolanddiscoveryURLsettings appropriately.While you can determine the IdP based on some property of the resource URL, this is generally a bad idea because even if your application is siloed to one organization at a time, that organization may choose to operate more than one IdP, and you should accomodate that by using a discovery mechanism of some kind.
The <CredentialResolver> element's content must point to the key and certificate pair(s) to use for decryption and signing (authenticating the SP to other systems). By default it matches the filenames used for the keypairs generated by the installation process.
Typically, each federation, or IdP partner if you're dealing with sites directly, will supply you with metadata describing itself. One <MetadataProvider> element needs to be added for every metadata source you'd like to point to, or you can combine them in one file yourself. Directly relying on remote sources of metadata from individual IdPs tends to be a risky and ill-advised idea and Shibboleth is geared around the use of a third party trust model whereby metadata for many IdPs is acquired at one time from a trusted source.
REMOTE_USERis a special server variable used to pass the primary identifier of a browser user. An attribute ID defined in theattribute-map.xmlfile can be designated as the source forREMOTE_USER. Multiple attributes may be listed in order of precedence.
Reference
| Anchor | ||||
|---|---|---|---|---|
|
Most of these are optional, with the exception of the entityID setting.
Name | Type | Default | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
id | string | default | If present, this must be set to the actual string "default" | ||||||
entityID | URI | Required, this is the SP's entityID, the SAML identifier that uniquely names an SP. IdPs do not have visibility into any internal application boundaries of an SP deployment. Any external distinctions must be noted by assigning a different entityID, which can be done on a content-specific basis via the | |||||||
policyId | string | References a policy defined via a <SecurityPolicies> element. When omitted, the default policy is assumed. | |||||||
requireAuthenticatedEncryption | boolean | false | When true, the SP will refuse to decrypt assertions that are unprotected by a signature or an authenticated transport (e.g., back-channel TLS) unless the data is encrypted with a special type of algorithm that includes built-in integrity protection to prevent chosen ciphertext attacks. At the present time, this will generally block use of encryption unless signed responses are enabled by an IdP. | ||||||
homeURL | URL | "/" | A location to send the browser to when a resource URL is required but cannot be determined (for example, following SSO when no location to use can be recovered). If this is omitted the SP will use the root of the applicable virtual host. | ||||||
| whitespace-delimited list of strings | Specifies a list of attribute IDs to pull from in a session's cached attributes; the first one found with a value is set as REMOTE_USER | |||||||
unsetHeaders | whitespace-delimited list of strings | Normally, the set of possible headers that might be used to carry attributes is determined by querying the configured attribute extractor(s). This allows the list to be overridden. Not typically used. | |||||||
attributePrefix | string | Applies a fixed prefix to the IDs of any attributes stored in user sessions. Used for special situations such as passing environment variables across Tomcat's AJP connector protocol. Do NOT set this to "HTTP_", as this causes IIS to treat server variables with this prefix as actual request headers, but without the necessary header smuggling prevention code enabled. This is vulnerable to security impersonation attacks. | |||||||
metadataAttributePrefix | string | If set, attributes extracted from metadata have their IDs prefixed with this value. Allows applications to distinguish between attributes about the user and attributes about the user's identity provider in the odd case that they might overlap. | |||||||
Relying Party Attributes | The following supported attributes are grouped because they can be overridden per-partner using a <RelyingParty> element: | ||||||||
authType | string | TLS | Specifies the transport-layer authentication mechanism that is used for back-channel SOAP messages to an IdP. The values permitted are implementation dependent, but may include:
| ||||||
authUsername | string | Required for non-TLS and GSS | |||||||
authPassword | string | Required for non-TLS and GSS | |||||||
signing | Controls outbound signing of XML messages. See the Signing and Encryption topic. | ||||||||
signingAlg | URI | specifier for RSA-SHA256 | An XML Signature signature algorithm specifier for signatures produced by the SP | ||||||
digestAlg | URI | specifier for SHA256 | An XML Signature digest algorithm specifier for signatures produced by the SP | ||||||
encryption | Controls outbound encryption of XML messages and content. See the Signing and Encryption topic. | ||||||||
encryptionAlg | URI | specifier for RSA-OAEP-SHA1 | An XML Encryption key wrap/transport algorithm specifier for encryption performed by the SP. The actual symmetric encryption algorithm will be derived from it. | ||||||
cipherSuites | see description | Directly configures the TLS ciphers to support when making SOAP connections. The default value ( | |||||||
keyName | string | Specifies a particular credential to use for signing or TLS authentication by attaching a name to the lookup criteria passed to the credential resolver in use. Typically the credential resolver will be able to attach names or aliases to credentials in some fashion. For more on using this feature, see the Multiple Credentials topic. | |||||||
artifactEndpointIndex | string | Identifies which | |||||||
chunkedEncoding | boolean | false | Controls the use of chunked encoding during back-channel SOAP communication. HTTP clients sending data must either compute and send a Content-Length header to the server (requiring that all data be buffered ahead of time), or use chunked encoding. A lot of servers mis-handle this option, so it is disabled by default. | ||||||
connectTimeout | time in seconds | 10 | Specifies the timeout for connecting to remote servers during back-channel SOAP communication. | ||||||
requireConfidentiality | boolean | true | When true, the SP will require the use of TLS/SSL for all back-channel SOAP communication. This prevents an unsafe exchange of data before an unencrypted channel might be used, since XML encryption depends on the peer's willingness to use it. | ||||||
requireSignedAssertions | boolean | false | When true, assertions MUST be digitally signed, regardless of any other signatures used to authenticate them. Typically needed only for advanced auditing or assertion forwarding use cases. | ||||||
requireTransportAuth | boolean | varies | When true, the SP will require back-channel SOAP communication to be authenticated at the transport layer (TLS/SSL server authentication). See the the Signing and Encryption topic for additional semantics and how this works by default | ||||||
sessionHook | URL | Specifies a location to send the client after a session has been created (i.e., after login), but before transferring the client to the eventual final resource. This is normally a relative path to ensure that the session will be visible to the hook script, but doesn't have to be. A hook can be used to validate something about the session to check its "fitness for purpose" before delivering the client to an application that may not offer sufficient error handling capability to do the job itself. A common example is checking for required attributes. The hook redirect will include two parameters, The hook MUST either redirect back or take complete ownership of the client with no further processing by the SP. | |||||||
artifactByFilesystem | boolean | false | Enables the artifact-based "back-door" external authentication mechanism described in the BackDoor topic | ||||||
authnContextClassRef | whitespace-delimited URIs | Supplies values for the SAML 2.0 | |||||||
authnContextComparison | "exact", "minimum", "maximum", "better" | Supplies values for the | |||||||
NameIDFormat | URI | Supplies a value for the | |||||||
SPNameQualifier | URI | Supplies a value for the | |||||||
| Anchor | ||||
|---|---|---|---|---|
|
If they appear, the first two elements (<Sessions> and <Errors>) MUST be in the order listed. All other elements may be in any order.
Name | Cardinality | Description | |
|---|---|---|---|
Application | Application | ||
<Sessions> | 1 | 0 or 1 | Configures the session handling behavior for the application, as well as all of the supported processing handlers and their locations. |
<Errors> | 0 or 1 | Configures error-handling behavior and a few logout-related responses | |
0 or more | Overrides low-level communication settings for specific IdPs or groups of IdPs | ||
<Notify> | 0 or more | Configures application notification of logout or name identifier management messages. | |
1 or more | 0 or more | Details how to load metadata about identity providers. | |
0 or more | Controls how trust processing is performed to determine whether authentication of messages from identity providers succeeds or fails, including XML and simple signing, and SSL/TLS. The default configuration used when nothing is specified is to use the ExplicitKey engine. | ||
0 or more | Controls how SAML attributes are decoded and exposed to applications. | ||
0 or more | Controls access to other data sources for attribute information. Primary use is for support of SAML queries to an identity provider for attributes if none are received in the initial assertion. When absent, the SP will not query for attributes. | ||
0 or more | Applies rules that filter out unacceptable attribute information. | ||
0 or more | Configures the private keys and certificates used by the SP. This is NOT related to the normal SSL/TLS server support provided by web servers. | ||
0 or more | 0 | Overrides default behavior by nesting exceptional configuration elements. | |
0 or more | 0 | Overrides default behavior through external XML fragments in one or more search paths | |