SAMLAuthnConfiguration

Current File(s): conf/authn/saml-authn-config.xml (V4.0), conf/authn/authn.properties (V4.1+), conf/relying-party.xml
Format: Native Spring, Properties (V4.1+)

1 Overview
2 General Configuration
- 2.1 A Note About Azure
3 Post-Processing
- 3.1 Authentication Time
- 3.2 Attribute Extraction and Filtering
- 3.3 Subject Population
- 3.4 Subject Canonicalization
- 3.5 Attribute Resolution
4 Advanced Behavior
5 Reference
6 More Examples

Overview

The authn/SAML login flow supports the use of a separate SAML 2.0 Identity Provider to authenticate the subject, with the IdP acting as a SAML proxy. This can be accomplished using additional glue via the External login flow, but this flow provides native SAML support with additional features and flexibility without the need to deploy a separate SAML Service Provider implementation.

The majority of this flow's behavior is actually derived from pre-existing configuration sources, in particular the use of SAML metadata (but for the IdP rather than the more usual SP metadata), and, if required, the use of RelyingPartyConfiguration to override behavior for specific IdPs.

The rest of the configuration needed is generally for the decoding and mapping/propagation of Attribute data from SAML, into the IdP, and usually on to SPs, which is common to most proxy authentication scenarios.

Please be aware that the issues raised by SameSite are fatal to this feature. If you have not yet deployed the filter provided as a workaround (possibly including accomodations for older Apple browsers), you will experience sporadic failures with this feature during the SAML POST back to the proxying Shibboleth IdP.

General Configuration

There are only two core requirements for this flow to operate:

The entityID of the Identity Provider to use must be known somehow.
SAML metadata for that Identity Provider must be available via the usual MetadataConfiguration.

The entityID to use can be established either via static configuration, a lookup function, or prior to this flow running by providing some form of IdP Discovery service and toggling the flow's discoveryRequired property (as discussed more generally in the AuthenticationConfiguration topic).

If some form of user interface is required to perform discovery, this must be achieved by implementing that in form of a compliant Discovery service (the standard protocol is based on simple redirects, so is readily implementable).

For simpler cases, a bean named shibboleth.authn.SAML.discoveryFunction can be defined in authn/saml-authn-config.xml to produce the entityID of the IdP to use.

For simpler cases, the idp.authn.SAML.proxyEntityID property can be set, to directly specify an IdP to use, or a bean named shibboleth.authn.SAML.discoveryFunction can be defined (using global.xml is fine) to produce the entityID of the IdP to use.

The same SAML metadata that would drive any typical Shibboleth SP is supported, and (apart from testing) should of course be refreshably-sourced from a trusted third-party with appropriate constraints on validity window, signature validation, and so forth applied.

Metadata representing the SP "half" of the Shibboleth IdP using this feature is of course also standard:

The IdP's entityID is presumed to be the same one applying to normal outbound use, but can be overridden if required.
The <AssertionConsumerService> for the IdP-acting-as-SP supports only the HTTP-POST binding and is located at the path "/idp/profile/Authn/SAML2/POST/SSO".
Encryption is fully supported; you may not have bothered doing anything with the existing encryption key generated at install time but it will be used by default to decrypt incoming SAML and its certificate would need to be published in the metadata you give to the proxied IdP. Of course you are free not to do this and accept plaintext assertions.
If you wish to sign requests, you would also need to include the IdP’s usual signing certificate. Note that the primary use case for this is logout, but the proxying support doesn't include any logout integration at present. If logout is making fire, logout and proxying together is quantum physics.

A Note About Azure

Apparently Azure enforces the underlying schema rule in SAML that the <RequesterID> element contains an actual URI. The IdP will populate this element with the identity of the downstream SP for which it is proxying authentication, and if it doesn’t happen to match Microsoft’s almost-certainly inexact determination about what constitutes a value, they reject it. If you’re proxying to Azure, you may need to set the SSO ignoreScoping profile configuration property to skip the creation of the entire <Scoping> element in the request.

It is notable that Azure happily allows the actual entityID of the SPs it connects to to contain any string value, despite that being unsafe, insecure, and of much greater consequence than the <RequesterID> element.

Post-Processing

The bulk of the configuration of this flow is actually not core to the flow's operation but the post-processing of the SAML Assertions that are returned in a successful response.

Authentication Time

By default, the AuthenticationResult created will be stamped with the AuthnInstant attribute supplied by the proxied IdP, which has implications on the policy you set for lifetime and timeout of these results. If you prefer to ignore that value and use the current time instead, you can set the SAML2.SSO profile bean’s isProxiedAuthnInstant setting to "false".

Attribute Extraction and Filtering

There are two sources of IdPAttribute extraction possible:

The AttributeRegistryConfiguration
An optional function bean named shibboleth.authn.SAML.attributeExtractionStrategy

The first is a largely automated process to decode SAML Attributes based on standard rules, possibly supplemented by custom rules.

The second is an extension point for implementing any custom requirements you have, primarily for extracting data from the surrounding SAML Assertion or Response into information to operate on. The function is of Java type Function<ProfileRequestContext,Collection<IdPAttribute>> and may be defined in conf/global.xml (V4.1+) or in the legacy conf/authn/saml-authn-config.xml file in older versions.

Once the results have been produced, the AttributeFilterConfiguration is applied to the results. This is a reversal of the usual filtering process of outbound data and operates with the proxying IdP itself as the "requester" and the proxied IdP as the "issuer", applying the Requester- and Issuer-based rules, respectively. It is also often desirable to apply "scope filtering" based on metadata when defining acceptance rules for scoped attributes.

If discriminating based on the issuer isn't sufficient, "Inbound" and "Outbound" policy rules are now provided for limiting policies based on the direction of the transaction.

No matter how you ultimately want to write these rules, it’s a good idea after testing to review your existing filtering policies to ensure you’re not allowing anything inbound you may not be intending to.

Example

An IdP proxying for a dedicated system with some discrete attributes might have a filter policy such as the following:

Example inbound filter policy

<AttributeFilterPolicy id="proxy">
	<PolicyRequirementRule xsi:type="Issuer" value="https://proxy.example.org" />
        
	<AttributeRule attributeID="givenName" permitAny="true" />
	<AttributeRule attributeID="sn" permitAny="true" />
	<AttributeRule attributeID="mail" permitAny="true" />
	<AttributeRule attributeID="eduPersonPrincipalName">
		<PermitValueRule xsi:type="ScopeMatchesShibMDScope" />
	</AttributeRule>
</AttributeFilterPolicy>

Subject Population

As with any other login flow, the product will be an AuthenticationResult containing a Java Subject with some number of Principal objects. Unlike many of the flows, the source of the Principals is somewhat more complex and flexible, and does not generally lend itself to a trivial determination of a principal name during subject canonicalization.

The content of the Subject produced consists of the following:

If the incoming Assertion(s) contained a <saml2:NameID> element, then a NameIDPrincipal is included that wraps that data.
The incoming <saml2:AuthnContext> element is used to construct one or more Principal objects that represent the quality of the authentication peformed. This is discussed further below.
A ProxyAuthenticationPrincipal is included that will contain the chain of proxied authorities used, beginning with the immediate assertion issuer and including any additional authorities identities in the <saml2:AuthnStatement>, if any.
Any IdPAttribute objects resulting from the initial extraction and filtering stage are wrapped in IdPAttributePrincipals.

Most of that is