PingGateway 2024.9

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": object,
    "secretsProvider": SecretsProvider reference,
    "spEntityId": configuration expression<string>,
    "idpEntityId": configuration expression<string>,
    "failureHandler": Handler reference
  }
}

Properties

"redirectURI": configuration expression<url>, required

The URI to use if there is no RelayState value.

"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 are mapped 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, 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.

"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 PingGateway 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": "vtO…​zuL".

Default: map to session.subjectName

"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 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": 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 PingGateway 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": configuration expression<string>, optional

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

Default: |

"assertionConsumerEndpoint": configuration expression<string>, optional

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

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

Default: fedletapplication

"SPinitiatedSSOEndpoint": configuration expression<string>, optional

Part of the URI that designates the SP initiated SSO endpoint.

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

Default: SPInitiatedSSO

"SPinitiatedSLOEndpoint": configuration expression<string>, optional

Part of the URI that designates the SP initiated SLO endpoint.

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

Default: SPInitiatedSLO

"singleLogoutEndpoint": configuration expression<string>, optional

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

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

Default: fedletSLORedirect (same as the Fedlet)

"singleLogoutEndpointSoap": configuration expression<string>, optional

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

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

Default: fedletSloSoap (same as the Fedlet)

"useOriginalUri": configuration expression<boolean>, optional

When true, use the original URI instead of a rebased URI to validate RelayState and Assertion Consumer Location URLs. Use this property if a baseUri decorator is used in the route or in config.json.

Default: true

"logoutExpression": runtime expression<boolean>, optional

A flag to indicate whether a request initiates logout processing before reaching the protected application.

  • false: The request does not initiate logout processing:

    • If a valid SAML session is found, the request is forwarded to the protected application.

    • If a valid SAML session is not found, the request triggers the SAML login flow.

  • true: The request initiates logout processing:

    • If a valid SAML session is found, the request triggers the SAML logout flow:

      • If there is a RelayState URL parameter, the request is forwarded to that URL. RelayState provides backwards compatibility for SamlFederationHandler.

      • If there is no RelayState URL parameter and logoutURI is defined, the request is forwarded to the logout page.

      • If there is no RelayState URL parameter and logoutURI is not defined, the request is forwarded to the protected application without any other validation.

    • If a valid session is not found, the request is forwarded to the protected application without any other validation.

To prevent unwanted access to the protected application, use logoutExpression with extreme caution as follows:

  • Define a logoutURI.

  • If you don’t define a logoutURI, specify logoutExpression to resolve to true only for requests that target dedicated logout pages of the protected application.

Consider the following examples when a logoutURI is not defined:

  • This expression resolves to true only for requests with /app/logout in their path:

    "logoutExpression": "${startsWith(request.uri.rawPath, '/app/logout')}"

    When a request matches the expression, the SAML session is revoked and the request is forwarded to the /app/logout page.

  • This expression resolves to true for all requests that contain logOff=true in their query parameters:

    "logoutExpression": "${find(request.uri.query, 'logOff=true')}"

    When a request matches the expression, the SAML session is revoked and the request is forwarded to the protected application without any other validation. In this example, an attacker can bypass PingGateway’s security mechanisms by simply adding ?logOff=true to a request.

Default: ${false}

"logoutURI": configuration expression<string>, optional

The URL to which a request is redirected if logoutExpression is evaluated as true or when the protected application uses the single logout feature of the Identity Provider.

Default: None, processing continues.

"redirectionMarker": configuration expression<object>, optional

A redirect marker for the SAML flow. If the marker is present in the flow, the request isn’t redirected for authentication.

This feature is on by default to prevent redirect loops when the session cookie isn’t present in the SAML flow. The cookie can be absent from the flow if it doesn’t include PingGateway’s domain.

"redirectionMarker": {
  "enabled": configuration expression<boolean>,
  "name": configuration expression<string>
}
"enabled": configuration expression<boolean>, optional

  • true: When the session is empty or invalid, PingGateway checks the request goto query parameter for the presence of the redirection marker:

    • If the redirection marker is present, PingGateway fails the request.

    • If the redirection marker isn’t present, PingGateway redirects the user agent for login.

  • false: PingGateway never checks the request goto query parameter for the presence of a redirection marker.

Default: true

"name": configuration expression<string>, optional

The name of the redirection marker query parameter to use when enabled is true.

Default: _ig

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for keys when AM provides signed or encrypted SAML assertions.

When this property isn’t set, the keys are provided by direct keystore look-ups based on entries in the SP extended metadata file, sp-extended.xml.

"spEntityId": configuration expression<string>, optional

The entity ID that this SP represents. Configure this property when more than one SP is defined in the metadata.

Default:

  • When no SPs are defined in the metadata an error is generated.

  • When there one SP defined in the metadata the filter uses that SP.

  • When there is more than one SP defined in the metadata the filter uses the first SP in the list of discovered metadata and logs a warning. Because ordering is not deterministic, the discovered SP can be the wrong SP.

"idpEntityId": configuration expression<string>, optional

The entity ID that this IDP represents. Configure this property when more than one IDP is defined in the metadata.

Default:

  • When no IDPs are defined in the metadata an error is generated.

  • When one IDP is defined in the metadata the filter uses that IDP.

  • When there is more than one IDP defined in the metadata the filter uses the first IDP in the list of discovered metadata and logs a warning. Because ordering is not deterministic, the discovered IDP can be the wrong IDP.

"failureHandler": Handler reference, optional

Handler to invoke when SAML processing fails.

Provide an inline handler configuration object or the name of a handler object declared in the heap. See also Handlers.

Default: Return an error response containing a SAML processing error.