--- title: SamlFederationFilter description: 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: component: pinggateway version: 2026 page_id: pinggateway:reference:SamlFederationFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/SamlFederationFilter.html revdate: 2025-12-16 section_ids: saml_in_deployments_with_multiple_instances_of_pinggateway: SAML in deployments with multiple instances of PingGateway SamlFederationFilter-usage: Usage SamlFederationFilter-properties: Properties SamlFederationFilter-redirectURI: redirectURI SamlFederationFilter-assertionMapping: assertionMapping SamlFederationFilter-subjectMapping: subjectMapping SamlFederationFilter-sessionIndexMapping: sessionIndexMapping SamlFederationFilter-authnContext: authnContext SamlFederationFilter-authnContextDelimiter: authnContextDelimiter SamlFederationFilter-assertionConsumerEndpoint: assertionConsumerEndpoint SamlFederationFilter-SPinitiatedSSOEndpoint: SPinitiatedSSOEndpoint SamlFederationFilter-SPinitiatedSLOEndpoint: SPinitiatedSLOEndpoint SamlFederationFilter-singleLogoutEndpoint: singleLogoutEndpoint SamlFederationFilter-singleLogoutEndpointSoap: singleLogoutEndpointSoap SamlFederationFilter-useOriginalUri: useOriginalUri SamlFederationFilter-logoutExpression: logoutExpression SamlFederationFilter-logoutURI: logoutURI SamlFederationFilter-redirectionMarker: redirectionMarker SamlFederationFilter-secretsProvider: secretsProvider SamlFederationFilter-spEntityId: spEntityId SamlFederationFilter-idpEntityId: idpEntityId SamlFederationFilter-failureHandler: failureHandler --- # 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. Learn more in the AM documentation on [Session state considerations](https://docs.pingidentity.com/pingam/8.1/am-saml2/saml2-configuration.html#saml2-and-session-state). ## Usage ```none { "name": string, "type": "SamlFederationFilter", "config": { "redirectURI": configuration expression, "assertionMapping": map or configuration expression, "subjectMapping": configuration expression, "sessionIndexMapping": configuration expression, "authnContext": configuration expression, "authnContextDelimiter": configuration expression, "assertionConsumerEndpoint": configuration expression, "SPinitiatedSSOEndpoint": configuration expression, "SPinitiatedSLOEndpoint": configuration expression, "singleLogoutEndpoint": configuration expression, "singleLogoutEndpointSoap": configuration expression, "useOriginalUri": configuration expression, "logoutExpression": runtime expression, "logoutURI": configuration expression, "redirectionMarker": { "enabled": configuration expression, "name": configuration expression }, "secretsProvider": SecretsProvider reference, "spEntityId": configuration expression, "idpEntityId": configuration expression, "failureHandler": Handler reference } } ``` ## Properties ### redirectURI `"redirectURI"`: *configuration expression<[url](preface.html#definition-url)>, required* The URI to use if there is no RelayState value. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------- | | | This endpoint must remain unique to this filter and route. Don't reuse it in other routes or filters or in protected applications. | ### assertionMapping `"assertionMapping"`: *[map](preface.html#definition-map) or configuration expression\, required* A map with the format `Map`, where: * Key: Session name, localName * Value: SAML assertion name, incomingName, or a configuration expression that evaluates to the name The following formats are allowed: ```json { "assertionMapping": { "string": "configuration expression", ... } } ``` ```json { "assertionMapping": "configuration expression" } ``` In the following example, the session names `username` and `password` map to SAML assertion names `mail` and `mailPassword`: ```json { "assertionMapping": { "username": "mail", "password": "mailPassword" } } ``` If an incoming SAML assertion contains the following statement: ```none mail = demo@example.com mailPassword = demopassword ``` Then the following values are set in the session: ```none username[0] = demo@example.com password[0] = demopassword ``` For this to work, edit the `` 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](preface.html#definition-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](preface.html#definition-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. 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 `"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](preface.html#definition-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. 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 `"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](preface.html#definition-string)>, optional* The authentication context delimiter used when there are multiple authentication contexts in the assertion. Default: `|` ### assertionConsumerEndpoint `"assertionConsumerEndpoint"`: *configuration expression<[string](preface.html#definition-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 `"SPinitiatedSSOEndpoint"`: *configuration expression<[string](preface.html#definition-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 `"SPinitiatedSLOEndpoint"`: *configuration expression<[string](preface.html#definition-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 `"singleLogoutEndpoint"`: *configuration expression<[string](preface.html#definition-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 `"singleLogoutEndpointSoap"`: *configuration expression<[string](preface.html#definition-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 `"useOriginalUri"`: *configuration expression<[boolean](preface.html#definition-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 `"logoutExpression"`: *runtime expression<[boolean](preface.html#definition-boolean)>, optional* A flag to indicate whether a request initiates logout processing before reaching the protected application. * `false`: The request doesn't 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. * 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: ```none "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: ```none "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 adding `?logOff=true` to a request. | Default: `${false}` ### logoutURI * `"logoutURI"`: *configuration expression<[string](preface.html#definition-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 `"redirectionMarker"`: *configuration expression<[object](preface.html#definition-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. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-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](preface.html#definition-string)>, optional* The name of the redirection marker query parameter to use when `enabled` is `true`. Default: `_ig` ### secretsProvider `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The [SecretsProvider](SecretsProvider.html) 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 lookups based on entries in the SP extended metadata file, `sp-extended.xml`. ### spEntityId `"spEntityId"`: *configuration expression<[string](preface.html#definition-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 one SP is 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 `"idpEntityId"`: *configuration expression<[string](preface.html#definition-string)>, optional* The entity ID 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 `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* [Handler](Handlers.html) to invoke when SAML processing fails. Provide an inline handler configuration object or the name of a handler object declared in the heap. Default: Return an error response containing a SAML processing error.