SamlFederationHandler

A handler to play the role of SAML 2.0 Service Provider (SP).

Consider the following requirements for this handler:

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 a SequenceHandler where the postcondition depends on the response.
Requests to the SamlFederationHandler must not be rebased, because the request URI must match the endpoint in the SAML metadata.

Usage

{
    "name": string,
    "type": "SamlFederationHandler",
    "config": {
        "assertionMapping": object,
        "redirectURI": runtime expression<uri string>,
        "secretsProvider": SecretsProvider reference,
        "assertionConsumerEndpoint": runtime expression<uri string>,
        "authnContext": runtime expression<string>,
        "authnContextDelimiter": runtime expression<string>,
        "logoutURI": runtime expression<uri string>,
        "sessionIndexMapping": runtime expression<string>,
        "singleLogoutEndpoint": runtime expression<uri string>,
        "singleLogoutEndpointSoap": runtime expression<uri string>,
        "SPinitiatedSLOEndpoint": runtime expression<uri string>,
        "SPinitiatedSSOEndpoint": runtime expression<uri string>,
        "useOriginalUri": runtime expression<boolean>,
        "subjectMapping": runtime expression<string>
    }
}

Properties

"assertionMapping": object, required

The transformation of attributes from the incoming assertion to attribute value pairs in IG.

Each entry in this object has the form localName:incomingName, where:

localName is the attribute name set in the session
incomingName is 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": runtime expression<uri string>, required

Set this to 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": runtime expression<string>, optional

Default: fedletapplication (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"authnContext": runtime 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 sets session.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": runtime expression<string>, optional

The authentication context delimiter used when there are multiple authentication contexts in the assertion.

Default: |

"logoutURI": runtime 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": runtime 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.

As an example, if you set "sessionIndexMapping": "mySessionIndex", then IG sets session.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": runtime expression<string>, optional

Default: fedletSLORedirect (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"singleLogoutEndpointSoap": runtime expression<string>, optional

Default: fedletSloSoap (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"SPinitiatedSLOEndpoint": runtime expression<string>, optional

Default: SPInitiatedSLO

If you modify this attribute, change the metadata to match.

"SPinitiatedSSOEndpoint": runtime expression<string>, optional

Default: SPInitiatedSSO

If you modify this attribute, change the metadata to match.

"useOriginalUri": runtime 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 a baseUri decorator is used in the route or in config.json.

Default: false

"subjectMapping": runtime 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.

As an example, if you set "subjectMapping": "mySubjectName", then IG sets session.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 Act As a SAML 2.0 Service Provider.

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"
    }
}

More Information

org.forgerock.openig.handler.saml.SamlFederationHandler

IG 7.1.2

SamlFederationHandler

Usage

Properties

Example

More Information