SamlFederationHandler
A handler to play the role of SAML 2.0 Service Provider (SP).
Consider the following requirements for SamlFederationHandler:
-
This handler does not support filtering; do not use it as the handler for a chain, which can include filters.
-
Do not use this handler when its use depends on something in the response. The response can be handled independently of IG, and can be
null
when control returns to IG. For example, do not use this handler in aSequenceHandler
where thepostcondition
depends on the response. -
Requests to the SamlFederationHandler must not be rebased, because the request URI must match the endpoint in the SAML metadata.
SAML in Deployments With Multiple Instances of IG
IG uses a Java fedlet to implement SAML. When IG acts as a SAML service provider, the session information is stored in the fedlet, not the session cookie. In deployments that use multiple instances of IG as a SAML service provider, it is therefore necessary to set up sticky sessions so that requests always hit the instance where the SAML interaction was started.
For information, see Session state considerations in AM’s SAML v2.0 guide.
For more information, see About session stickiness and session replication for Tomcat and About session stickiness and session replication for Jetty
Usage
{
"name": string,
"type": "SamlFederationHandler",
"config": {
"assertionMapping": map,
"redirectURI": configuration expression<url>,
"secretsProvider": SecretsProvider reference,
"assertionConsumerEndpoint": configuration expression<url>,
"authnContext": configuration expression<string>,
"authnContextDelimiter": configuration expression<string>,
"logoutURI": configuration expression<url>,
"sessionIndexMapping": configuration expression<string>,
"singleLogoutEndpoint": configuration expression<url>,
"singleLogoutEndpointSoap": configuration expression<url>,
"SPinitiatedSLOEndpoint": configuration expression<url>,
"SPinitiatedSSOEndpoint": configuration expression<url>,
"useOriginalUri": configuration expression<boolean>,
"subjectMapping": configuration expression<string>
}
}
Properties
"assertionMapping"
: map, required-
A name-value map of
localName:incomingName
, where:-
localName
is a string for the attribute name set in the session -
incomingName
is a configuration expression<string> for the attribute name set in the incoming assertion
The following example is an
assertionMapping
object:{ "username": "mail", "password": "mailPassword" }
If the incoming assertion contains the statement:
mail = demo@example.com mailPassword = demopassword
Then the following values are set in the session:
username = demo@example.com password = demopassword
For this to work, edit the
<Attribute name="attributeMap">
element in the SP extended metadata file,$HOME/.openig/SAML/sp-extended.xml
, so that it matches the assertion mapping configured in the SAML 2.0 Identity Provider (IDP) metadata.Because the dot character (
.
) serves as a query separator in expressions, do not use dot characters in the localName.To prevent different handlers from overwriting each others' data, use unique localName settings when protecting multiple service providers.
-
"redirectURI"
: configuration expression<url>, required-
The page that the filter used to HTTP POST a login form recognizes as the login page for the protected application.
This is how IG and the Federation component work together to provide SSO. When IG detects the login page of the protected application, it redirects to the Federation component. Once the Federation handler validates the SAML exchanges with the IDP, and sets the required session attributes, it redirects back to the login page of the protected application. This allows the filter used to HTTP POST a login form to finish the job by creating a login form to post to the application based on the credentials retrieved from the session attributes.
"secretsProvider"
: SecretsProvider reference, optional-
The SecretsProvider object to query for keys when AM provides signed or encrypted SAML assertions.
When this property is not set, the keys are provided by direct keystore look-ups based on entries in the SP extended metadata file,
sp-extended.xml
.For more information, see SecretsProvider.
Default: Empty.
"assertionConsumerEndpoint"
: configuration expression<string>, optional-
Default:
fedletapplication
(same as the Fedlet)If you modify this attribute, change the metadata to match.
"authnContext"
: configuration expression<string>, optional-
Name of the session field to hold the value of the authentication context. Because the dot character (
.
) serves as a query separator in expressions, do not use dot characters in the field name.Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of
session
. Otherwise different handlers can overwrite each others' data.As an example, if you set
"authnContext": "myAuthnContext"
, then IG setssession.myAuthnContext
to the authentication context specified in the assertion. When the authentication context is password over protected transport, then this results in the session containing"myAuthnContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
.Default: map to
session.authnContext
"authnContextDelimiter"
: configuration expression<string>, optional-
The authentication context delimiter used when there are multiple authentication contexts in the assertion.
Default:
|
"logoutURI"
: configuration expression<string>, optional-
Set this to the URI to visit after the user is logged out of the protected application.
You only need to set this if the application uses the single logout feature of the Identity Provider.
"sessionIndexMapping"
: configuration expression<string>, optional-
Name of the session field to hold the value of the session index. Because the dot character (
.
) serves as a query separator in expressions, do not use dot characters in the field name.Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of
session
. Otherwise different handlers can overwrite each others' data.As an example, if you set
"sessionIndexMapping": "mySessionIndex"
, then IG setssession.mySessionIndex
to the session index specified in the assertion. This results in the session containing something like"mySessionIndex": "s24ccbbffe2bfd761c32d42e1b7a9f60ea618f9801"
.Default: map to
session.sessionIndex
"singleLogoutEndpoint"
: configuration expression<string>, optional-
Default:
fedletSLORedirect
(same as the Fedlet)If you modify this attribute, change the metadata to match.
"singleLogoutEndpointSoap"
: configuration expression<string>, optional-
Default:
fedletSloSoap
(same as the Fedlet)If you modify this attribute, change the metadata to match.
"SPinitiatedSLOEndpoint"
: configuration expression<string>, optional-
Default:
SPInitiatedSLO
If you modify this attribute, change the metadata to match.
"SPinitiatedSSOEndpoint"
: configuration expression<string>, optional-
Default:
SPInitiatedSSO
If you modify this attribute, change the metadata to match.
"useOriginalUri"
: configuration expression<boolean>, optional-
When
true
, use the original URI instead of a rebased URI when validating RelayState and Assertion Consumer Location URLs. Use this property if abaseUri
decorator is used in the route or inconfig.json
.Default:
false
"subjectMapping"
: configuration expression<string>, optional-
Name of the session field to hold the value of the subject name. Because the dot character (
.
) serves as a query separator in expressions, do not use dot characters in the field name.Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of
session
. Otherwise different handlers can overwrite each others' data.As an example, if you set
"subjectMapping": "mySubjectName"
, then IG setssession.mySubjectName
to the subject name specified in the assertion. If the subject name is an opaque identifier, then this results in the session containing something like"mySubjectName": "vtOk+APj1s9Rr4yCka6V9pGUuzuL"
.Default: map to
session.subjectName
Example
For an example of how to set up IG as a SAML service provider, see SAML 2.0 single sign-on and federation.
In the following example, IG receives a SAML 2.0 assertion from the IDP, and then logs the user in to the protected application using the username and password from the assertion:
{
"name": "SamlFederationHandler",
"type": "SamlFederationHandler",
"config": {
"assertionMapping": {
"username": "mail",
"password": "mailPassword"
},
"redirectURI": "/login",
"logoutURI": "/logout"
}
}