SamlFederationFilter

Initiates the login or logout of a SAML 2.0 Service Provider (SP) with a SAML 2.0 Identity Provider (IDP). Login is initiated for requests that don’t:

Trigger a logout expression
Match a SAML endpoint
Include a valid session

Requests with a valid session are passed along the chain.

SAML in deployments with multiple instances of PingGateway

When PingGateway acts as a SAML service provider, session information is stored in the fedlet not the session cookie. In deployments with multiple instances of PingGateway as a SAML service provider, it is necessary to set up sticky sessions so that requests always hit the instance where the SAML interaction was started.

For information, refer to Session state considerations in AM’s SAML v2.0 guide.

Usage

{
  "name": string,
  "type": "SamlFederationFilter",
  "config": {
    "redirectURI": configuration expression<url>,
    "assertionMapping": map or configuration expression<map>,
    "subjectMapping": configuration expression<string>,
    "sessionIndexMapping": configuration expression<string>,
    "authnContext": configuration expression<string>,
    "authnContextDelimiter": configuration expression<string>,
    "assertionConsumerEndpoint": configuration expression<url>,
    "SPinitiatedSSOEndpoint": configuration expression<url>,
    "SPinitiatedSLOEndpoint": configuration expression<url>,
    "singleLogoutEndpoint": configuration expression<url>,
    "singleLogoutEndpointSoap": configuration expression<url>,
    "useOriginalUri": configuration expression<boolean>,
    "logoutExpression": runtime expression<boolean>,
    "logoutURI": configuration expression<url>,
    "redirectionMarker": {
      "enabled": configuration expression<boolean>,
      "name": configuration expression<string>
    },
    "secretsProvider": SecretsProvider reference,
    "spEntityId": configuration expression<string>,
    "idpEntityId": configuration expression<string>,
    "failureHandler": Handler reference
  }
}

Properties

redirectURI

"redirectURI": configuration expression<url>, required

The URI to use if there is no RelayState value.

assertionMapping

"assertionMapping": map or configuration expression<map>, required

A map with the format Map<String, String>, where:

Key: Session name, localName
Value: SAML assertion name, incomingName, or a configuration expression that evaluates to the name

The following formats are allowed:

{
  "assertionMapping": {
    "string": "configuration expression<string>",
    ...
  }
}

{
  "assertionMapping": "configuration expression<map>"
}

In the following example, the session names username and password map to SAML assertion names mail and mailPassword:

{
  "assertionMapping": {
    "username": "mail",
    "password": "mailPassword"
  }
}

If an incoming SAML assertion contains the following statement:

mail = demo@example.com
mailPassword = demopassword

Then the following values are set in the session:

username[0] = demo@example.com
password[0] = 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, don’t use dot characters in the localName.

To prevent different handlers from overwriting each other’s data, use unique localName settings when protecting multiple service providers.

subjectMapping

"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, don’t 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 other’s data.

As an example, if you set "subjectMapping": "mySubjectName", PingGateway sets session.mySubjectName to the subject name specified in the assertion. If the subject name is an opaque identifier, this results in the session containing something like "mySubjectName": "vtO…zuL".

Default: Map to session.subjectName

sessionIndexMapping

"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, don’t use dot characters in the field name.

As an example, if you set "sessionIndexMapping": "mySessionIndex", PingGateway sets session.mySessionIndex to the session index specified in the assertion. This results in the session containing something like "mySessionIndex": "s24c…801".

Default: Map to session.sessionIndex

authnContext

"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, don’t use dot characters in the field name.

As an example, if you set "authnContext": "myAuthnContext", PingGateway sets session.myAuthnContext to the authentication context specified in the assertion. When the authentication context is password over protected transport, this results in the session containing "myAuthnContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport".

Default: Map to session.authnContext

authnContextDelimiter

"authnContextDelimiter": configuration expression<string>, optional

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

Default: |

assertionConsumerEndpoint

"assertionConsumerEndpoint": configuration expression<string>, optional

Part of the URI that designates the consumer endpoint as defined in the SP metadata shared with the IDP.