Overview

The <ApplicationDefaults> element (and any nested <ApplicationOverride> elements) define most of the runtime behavior of the software when it processes SAML assertions and protocol messages. The usual pattern is to define most of this information once, in the outer element, and then supply a limited set of overridden information for each application you define that needs exceptional behavior.

Every request to the web server is associated with 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.

These application boundaries may or may not align with the notion of an application as understood in other contexts, but usually do. A very common strategy is for each virtual host on a server to map to its own application.

The majority of the SP's more advanced functionality is defined on a per-application basis. Supported protocol endpoints and handlers, security policies, credentials for signing, encryption, and TLS, attribute extraction/resolution/filtering, and the entityID to use are just some of the options handled here.

When a resource protected by the SP needs distinct behavior in these kinds of areas, a new application needs to be defined here and referenced by the request mapper using the applicationId property.

The <ApplicationDefaults> element both specifies default behavior and acts as a container for any other <ApplicationOverride> elements. <ApplicationOverride> elements inherit all the settings of the <ApplicationDefaults> element but can override them (see NativeSPApplicationOverride for details on how this works).

Basic Configuration (Version 2.4 and Above)

The default configuration of the <ApplicationDefaults> element and most of its subelements will work for most circumstances with a few modifications.

The entityID attribute on the <ApplicationDefaults> element needs to be changed to the SAML entityID you'd like to use for your deployment. This must be the value your federations and partners are expecting.

Configure SSO to an IdP or with a Discovery Service
- To use a specific IdP, change the entityID setting in the <SSO> element to match the value in that IdP's metadata.
- To use a discovery service, remove the entityID setting in the <SSO> element, and set the discoveryProtocol and discoveryURL settings appropriately.

The <CredentialResolver> element's content must point to the key and certificate to use for signing, decryption, and authenticating the SP to other systems. By default it matches the filenames used for the keypair generated by the installation process.

Typically, each federation, or IdP partner if you're dealing with sites directly, will supply you with a metadata file describing itself. One <MetadataProvider> element needs to be added for every metadata file you'd like to point to, or you can combine them in one file yourself.

REMOTE_USER is a special server or CGI variable used to pass the primary identifier of a browser user. An attribute ID or alias defined in the attribute-map.xml file can be designated as the source for REMOTE_USER. Multiple attributes may be listed in order of precedence.

If specialized behavior for another application needs to be defined, use an <ApplicationOverride> child element.

Basic Configuration (Older Versions)

The default configuration of the <ApplicationDefaults> element and most of its subelements will work for most circumstances with a few modifications.

The entityID attribute on the <ApplicationDefaults> element needs to be changed to the SAML entityID you'd like to use for your deployment. This must be the value your federations and partners are expecting.

homeURL is where the SP redirects the client to when there is nothing else that can be done with a request and can be set to a standard home page or index page.

You'll need to configure a default <SessionInitiator> handler as designated by the isDefault="true" attribute. The choice of which example in shibboleth2.xmlto use as a default depends on how you'll be using the software.
- The Intranet example demonstrates how to send users directly to a particular IdP to authenticate. Change the entityID to match the value in that IdP's metadata.
- The WAYF example allows for Shibboleth 1.x-style IdP selection. If your deployment or federation supplies only a legacy WAYF service, this example can be made the default. Change the URL attribute to match the WAYF service's location.
- The DS example supports the more modern 2.0 SAML IdP discovery protocol. The URL attribute should again be changed to match the appropriate location.

The <CredentialResolver> element's content must point to the key and certificate to use for signing, decryption, and authenticating the SP to other systems. By default it matches the filenames used for the keypair generated by the installation process.

Typically, each federation, or IdP partner if you're dealing with sites directly, will supply you with a metadata file describing itself. One <MetadataProvider> element needs to be added for every metadata file you'd like to point to. Each one lives inside the outer-most "Chaining" plugin.

REMOTE_USER is a special server or CGI variable used to pass the primary identifier of a browser user. An attribute ID or alias defined in the attribute-map.xml file can be designated as the source for REMOTE_USER. Multiple attributes may be listed in order of precedence.

If specialized behavior for another application needs to be defined, use an <ApplicationOverride> child element at the end of the outer element's set of children.

Attributes

id(string)
- Identifies the application using a unique key. On the outer-most element, the value MUST be "default" (or omitted on 2.4+).

entityID (URI) (required for <ApplicationDefaults>, optional for <ApplicationOverride>)
- An entityID is the SAML identifier that uniquely names an SP. Identity providers do not know about the internal application boundaries of an SP deployment. Any external distinctions must be noted by assigning a different entityID.

policyId (string) (optional on 2.4+, else required for <ApplicationDefaults>, optional for <ApplicationOverride>)
- References a policy defined in the <SecurityPolicies> element. When omitted on Version 2.4 and above, the default policy is assumed.

requireAuthenticatedEncryption (boolean) (defaults to false) (Version 2.5 and Above)
- 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 local state information can be found). As of Version 2.2.1, this can be omitted and it will calculate the root of the site. In prior versions, leaving this out usually results in errors, but was defaulted to the literal value of "/".

REMOTE_USER(space-delimited list of strings)
- Specifies a list of attribute IDs/aliases to look for in a session's cache of attributes. The first one found with a value is set as REMOTE_USER (or in the case of IIS, HTTP_REMOTE_USER).

unsetHeaders(space-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 and aliases of any attributes stored in user sessions. Used for special situations such as passing environment variables across the AJP connector protocol.

metadataAttributePrefix(string)
- If set, attributes extracted from metadata have their IDs and aliases prefixed with this value. Allows applications to distinguish between attributes about the user and attributes about the user's identity provider.

Relying Party Attributes

The following supported attributes are grouped because they can be overridden per-partner using a <RelyingParty> element:

authType (string) (defaults to "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:
  - TLS
    - client certificate TLS/SSL authentication
  - basic
    - HTTP Basic-Auth (cleartext name/password)
  - digest
    - HTTP Digest-Auth
  - ntlm
    - Microsoft's NTLM authentication
  - gss
    - GSS-API (SPNEGO)

authUsername (string)
- Required for non-TLS and GSS authType values, this is the username to use.

authPassword (string)
- Required for non-TLS and GSS authType values, this is the password to use.

signing (see NativeSPSigningEncryption)
- Controls outbound signing of XML messages.

signingAlg (URI) (defaults to the specifier for RSA-SHA1)
- An XML Signature signature algorithm specifier for signatures produced by the SP.

digestAlg (URI) (defaults to the specifier for SHA1)
- An XML Signature digest algorithm specifier for signatures produced by the SP.

encryption (see NativeSPSigningEncryption)
- Controls outbound encryption of XML messages and content.

encryptionAlg (URI) (defaults to the 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.

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 NativeSPMultipleCredentials topic.

artifactEndpointIndex (string)
- Identifies which <ArtifactResolutionService> handler at the SP is used when sending artifact-bound messages to the relying party. Endpoints typically include an index attribute to copy here.

chunkedEncoding (boolean) (defaults to 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) (defaults to 10)
- Specifies the timeout for connecting to remote servers during back-channel SOAP communication.

timeout (time in seconds) (defaults to 20)
- Specifies the total time to allow for completing back-channel SOAP communication.

requireConfidentiality (boolean) (defaults to 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) (defaults to 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) (defaults to true, but see NativeSPSigningEncryption)
- When true, the SP will require back-channel SOAP communication to be authenticated at the transport layer (TLS/SSL server authentication). Prior to V2.6, must be set to false to permit the relying party to authenticate using only message signatures. See the NativeSPSigningEncryption topic for some additional semantics added in V2.6.

Version 2.5 and Above

sessionHook (absolute or relative 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, target and return. The target parameter contains the resource URL that will eventually be the client's destination, in case the hook cares. The return parameter is the location to redirect the client back to upon completion of the hook. The hook MUST either redirect back or take complete ownership of the client with no further processing by the SP.

artifactByFilesystem (boolean) (defaults to false)
- Enables the artifact-based "back-door" external authentication mechanism described in NativeSPBackDoor.

Version 2.6 and Above

cipherSuites (OpenSSL cipher expression) (defaults to "ALL:!aNULL:!LOW:!EXPORT:!RC4:!SSLv2")
- Directly configures the TLS ciphers to support when making SOAP connections. The default value is historical and has been in place for a few releases, and has been left alone to prevent upgrades from affecting interoperability. A stronger value is now used in the default files distributed with the software, which was derived from Mozilla's tool.
authnContextClassRef (space-delimited list of URIs)
- Supplies values for the SAML 2.0 <AuthnContextClassRef> element in requests to applicable IdPs, or for the wauth parameter in WS-Federation requests. Ignored for other protocols.
authnContextComparison ("exact", "minimum", "maximum", "better")
- Supplies values for the <RequestedAuthenticationContext> comparison operator in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.
NameIDFormat (URI)
- Supplies a value for the <NameIDPolicy> element's Format attribute in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.
SPNameQualifier (URI)
- Supplies a value for the <NameIDPolicy> element's SPNameQualifier attribute in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.

Child Elements

On Version 2.4 and above, all but the first two elements may appear in any order. On older versions, the order MUST be as listed.

Also on Version 2.4 and above, elements that could not appear more than once unless explicitly "chained" may now appear multiple times and will be chained automatically. This includes <MetadataProvider>, <TrustEngine>, <AttributeExtractor>, <AttributeResolver>, and <AttributeFilter>.

<Sessions> (required for <ApplicationDefaults>, optional for <ApplicationOverride>)
- Configures the session handling behavior for the application, as well as all of the supported processing handlers and their locations.

<Errors>(optional)
- Configures error-handling behavior and a few logout-related responses.

<RelyingParty>(zero or more)
- Overrides some communication-related settings for specific identity providers or groups of providers.

<Notify>(zero or more)
- Configures application notification of logout or name identifier management messages.

<MetadataProvider> (zero or more on 2.4+, else required for <ApplicationDefaults>, optional for <ApplicationOverride>)
- Supplies metadata about identity providers.

<TrustEngine> (zero or more on 2.4+, else required for <ApplicationDefaults>, optional for <ApplicationOverride>)
- 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. In later versions, the default configuration used when none are specified is to chain the ExplicitKey and PKIX engines together.

<AttributeExtractor>(zero or more on 2.4+, else zero or one)
- Controls how SAML attributes are decoded and exposed to applications.

<AttributeResolver>(zero or more on 2.4+, else zero or one)
- 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.

<AttributeFilter>(zero or more on 2.4+, else zero or one)
- Applies rules that filter out unacceptable attribute information.

<CredentialResolver>(zero or more on 2.4+, else zero or one)
- Configures the private keys and certificates used by the SP to identify itself to identity providers. This is NOT related to the normal SSL/TLS server support provided by web servers.

<ApplicationOverride>(zero or more)
- Overrides default behavior by nesting exceptional configuration elements. Cannot themselves appear inside other <ApplicationOverride> elements.

Examples

The following shibboleth2.xml excerpt contains an example in which a second application with its own entityID is created on a second virtual host. This is one of the most common cases.

[...]

<!-- To customize behavior, map hostnames and path components to applicationId and other settings. -->
    <RequestMapper type="Native">
        <RequestMap applicationId="default">

            <Host name="service.university.org" authType="shibboleth" requireSession="true"/>
            <Host name="other.university.org" applicationId="other-app" authType="shibboleth" requireSession="true"/>

        </RequestMap>
    </RequestMapper>


[...]

<ApplicationDefaults id="default" policyId="default"
        entityID="https://service.university.org/shibboleth"
        homeURL="https://service.university.org/welcome/"
        REMOTE_USER="eppn persistent-id targeted-id"
        >

       [...]

        <!-- Overrides for other-app -->
        <ApplicationOverride id="other-app" entityID="https://other.university.org/shibboleth"/>
</ApplicationDefaults>

[...]

This excerpt is an example where the additional application is on the same virtual host. Notice the overriden handlerURL that also has to map to the overridden applicationId.

[...]

<!-- To customize behavior, map hostnames and path components to applicationId and other settings. -->
    <RequestMapper type="Native">
        <RequestMap applicationId="default">

            <Host name="service.university.org" authType="shibboleth" requireSession="true">
                <Path name="other-app" applicationId="other-app"/>
            </Host>

        </RequestMap>
    </RequestMapper>


[...]

<ApplicationDefaults id="default" policyId="default"
        entityID="https://service.university.org/shibboleth"
        homeURL="https://service.university.org/welcome/"
        REMOTE_USER="eppn persistent-id targeted-id"
        >

       [...]

        <!-- Overrides for other-app -->
         <ApplicationOverride id="other-app" entityID="https://other.university.org/shibboleth">
             <Sessions lifetime="28800" timeout="3600" checkAddress="false"
                handlerURL="/otherapp/Shibboleth.sso" handlerSSL="false">
        </ApplicationOverride>
   </ApplicationDefaults>

[...]