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).
The default configuration of the <ApplicationDefaults>
element and most of its subelements will work for most circumstances with a few modifications.
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.entityID
setting in the <SSO>
element to match the value in that IdP's metadata.entityID
setting in the <SSO>
element, and set the discoveryProtocol
and discoveryURL
settings appropriately.<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.<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.
The default configuration of the <ApplicationDefaults>
element and most of its subelements will work for most circumstances with a few modifications.
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.<SessionInitiator>
handler as designated by the isDefault="true"
attribute. The choice of which example in shibboleth2.xml
to use as a default depends on how you'll be using the software.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.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.DS
example supports the more modern 2.0 SAML IdP discovery protocol. The URL
attribute should again be changed to match the appropriate location.<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.<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.
id
(string)entityID
(URI) (required for <ApplicationDefaults>
, optional for <ApplicationOverride>
)policyId
(string) (optional on 2.4+, else required for <ApplicationDefaults>
, optional for <ApplicationOverride>
)<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)homeURL
(URL)REMOTE_USER
(space-delimited list of strings)unsetHeaders
(space-delimited list of strings)attributePrefix
(string)metadataAttributePrefix
(string)The following supported attributes are grouped because they can be overridden per-partner using a <RelyingParty>
element:
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>
)<Errors>
(optional)<RelyingParty>
(zero or more)<Notify>
(zero or more)<MetadataProvider>
(zero or more on 2.4+, else required for <ApplicationDefaults>
, optional for <ApplicationOverride>
)<TrustEngine>
(zero or more on 2.4+, else required for <ApplicationDefaults>
, optional for <ApplicationOverride>
)<AttributeExtractor>
(zero or more on 2.4+, else zero or one)<AttributeResolver>
(zero or more on 2.4+, else zero or one)<AttributeFilter>
(zero or more on 2.4+, else zero or one)<CredentialResolver>
(zero or more on 2.4+, else zero or one)<ApplicationOverride>
(zero or more)<ApplicationOverride>
elements.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> [...] |