--- title: CrossDomainSingleSignOnFilter description: When IG and AM are running in the same domain, the SingleSignOnFilter can be used for SSO. When IG and AM are running in different domains, AM cookies aren't visible to IG because of the same-origin policy. The CrossDomainSingleSignOnFilter provides a mechanism to push tokens issued by AM to IG running in a different domain. component: pinggateway version: 2023.11 page_id: pinggateway:reference:CrossDomainSingleSignOnFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CrossDomainSingleSignOnFilter.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-03T11:21:31Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/CrossDomainSingleSignOnFilter.html section_ids: websocket_notifications_for_sessions: WebSocket notifications for sessions CrossDomainSingleSignOnFilter-desc-usage: Usage CrossDomainSingleSignOnFilter-properties: Properties CrossDomainSingleSignOnFilter-example: Example CrossDomainSingleSignOnFilter-moreinfo: More information --- # CrossDomainSingleSignOnFilter When IG and AM are running in the same domain, the [SingleSignOnFilter](SingleSignOnFilter.html) can be used for SSO. When IG and AM are running in different domains, AM cookies aren't visible to IG because of the same-origin policy. The CrossDomainSingleSignOnFilter provides a mechanism to push tokens issued by AM to IG running in a different domain. When this filter processes a request, it injects the CDSSO token, the session user ID, and the full claims set into the [CdSsoContext](Contexts.html#CdSsoContext). If an error occurs during authentication, information is captured in the [CdSsoFailureContext](Contexts.html#CdSsoFailureContext). For an example of how to configure CDSSO and information about the CDSSO data flow, refer to [Cross-domain single sign-on](../gateway-guide/sso-cdsso.html#cdsso). ## WebSocket notifications for sessions When WebSocket notifications are set up for sessions, IG receives a notification from AM when a user logs out of AM, or when the AM session is modified, closed, or times out. IG then evicts entries that are related to the event from the `sessionCache`. For information about setting up WebSocket notifications, using them to clear the session cache, and including them in the server logs, refer to [WebSocket notifications](../maintenance-guide/tuning.html#amservice-websocket). ## Usage ```json { "name": string, "type": "CrossDomainSingleSignOnFilter", "config": { "amService": AmService reference, "redirectEndpoint": configuration expression, "authenticationService": configuration expression, "authCookie": object, "redirectionMarker": object, "defaultLogoutLandingPage": configuration expression, "logoutExpression": runtime expression, "failureHandler": Handler reference, "verificationSecretId": configuration expression, "secretsProvider": SecretsProvider reference } } ``` ## Properties * `"amService"`: *AmService [reference](preface.html#definition-reference), required* The AmService heap object to use. See [AmService](MiscellaneousConfigurationObjects.html#AmService). * `"redirectEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, required* The URI to which AM redirects the browser with the authentication token or an authentication error. The filter checks that the authentication was initiated by IG. Configure this URI to be the same as that in AM. To make sure the redirect is routed back to the CrossDomainSingleSignOnFilter, include the endpoint in the route condition in one of the following ways: * As a sub-path of the condition path. For example, use the following route condition with the following endpoint: ```json "condition": "${find(request.uri.path, '^/home/cdsso')}" ``` ```json "redirectEndpoint": "/home/cdsso/callback" ``` * To match the route condition. For example, use the following route condition with the following endpoint: ```json "condition": "${find(request.uri.path, '^/home/cdsso')}" ``` ```json "redirectEndpoint": "/home/cdsso" ``` With this route condition, all POST requests on the condition path are treated as AM CDSSO callbacks. Any POST requests that aren't the result of an AM CDSSO callback will fail. * As a specific path that is not related to the condition path. To make sure the redirect is routed back to this filter, include the redirectEndpoint as a path in the filter condition. For example, use the following route condition with the following endpoint: ```json "condition": "${find(request.uri.path, '^/home/cdsso/redirect') || find(request.uri.path, '^/ig/cdssoRedirectUri')}" ``` ```json "redirectEndpoint": "/ig/cdssoRedirectUri" ``` - `"authenticationService"`: *configuration expression<[string](preface.html#definition-string)>,optional* The name of an AM authentication tree or authentication chain to use for authentication. | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | Use only authentication trees with ForgeRock Identity Cloud. Authentication modules and chains are not supported. | Default: AM's default authentication tree. For more information about authentication trees and chains, refer to [Authentication nodes and trees](https://docs.pingidentity.com/pingam/7.4/am-authentication/about-authentication-trees.html) and [Authentication modules and chains](https://docs.pingidentity.com/pingam/7.4/am-authentication/about-authentication-modules-and-chains.html) in AM's *Authentication and SSO* guide. * `"authCookie"`: *[object](preface.html#definition-object), optional* The configuration of the cookie used to store the authentication. ```json { "name": configuration expression, "domain": configuration expression, "httpOnly": configuration expression, "path": configuration expression, "sameSite": configuration expression, "secure": configuration expression } ``` * `"name"`: *configuration expression<[string](preface.html#definition-string)>, optional* Name of the cookie containing the authentication token from AM. For security, change the default name of cookies. Default: `ig-token-cookie` * `"domain"`: *configuration expression<[string](preface.html#definition-string)>, optional* Domain to which the cookie applies. Set a domain only if the user agent is able to re-emit cookies on that domain on its next hop. For example, to re-emit a cookie on the domain `example.com`, the user agent must be able to access that domain on its next hop. Default: The fully qualified hostname of the user agent's next hop. * `"httpOnly"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to mitigate the risk of client-side scripts accessing protected cookies. Default: `true` * `"path"`: *configuration expression<[string](preface.html#definition-string)>, optional* Path protected by this authentication. Set a path only if the user agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path `/home/cdsso`, the user agent must be able to access that path on its next hop. Default: The path of the request that got the `Set-Cookie` in its response. * `"sameSite"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Options to manage the circumstances in which a cookie is sent to the server. Use one of the following values to reduce the risk of CSRF attacks: * `STRICT`: Send the cookie only if the request was initiated from the cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. * `LAX`: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. * `NONE`: Send the cookie whenever a request is made to the cookie domain. Not case-sensitive. With this setting, consider setting `secure` to `true` to prevent browsers from rejecting the cookie. For more information, refer to [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite). Default: `LAX` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For CDSSO, set `"sameSite":"none"` and `"secure":"true"`. For security reasons, many browsers require the connection used by the browser to be secure (HTTPS) for `"sameSite":"none"`. Therefore, if the connection used by the browser is not secure (HTTP), the browser might not supply cookies with `"sameSite":"none"`. For more information, refer to [Authenticate with CDSSO](../gateway-guide/sso-cdsso.html#cdsso-auth). | * `"secure"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to limit the scope of the cookie to secure channels. Set this flag only if the user agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the `secure` flag, the user agent must be connected to its next hop by HTTPS. Default: `false` * `"redirectionMarker"`: *configuration expression<[object](preface.html#definition-object)>, optional* A redirect marker for the CDSSO flow. If the marker is present in the CDSSO 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 CDSSO flow. The cookie can be absent from the flow if it doesn't include IG's domain. ```json "redirectionMarker": { "enabled": configuration expression, "name": configuration expression } ``` * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* * `true`: When the session is empty or invalid, IG checks the request `goto` query parameter for the presence of the redirection marker: * If the redirection marker is present, IG fails the request. * If the redirection marker isn't present, IG redirects the user agent for login. * false: IG 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` - `"defaultLogoutLandingPage"`: *configuration expression<[url](preface.html#definition-url)>, optional* The URL to which a request is redirected if `logoutExpression` is evaluated as true. If this property is not an absolute URL, the request is redirected to the IG domain name. This parameter is effective only when `logoutExpression` is specified. Default: None, processing continues. * `"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 does not initiate logout processing: * If a valid AM session is found, the request is forwarded to the protected application. * If a valid AM session is not found, the request triggers login. * `true`: The request initiates logout processing: * If a valid AM session is found, the session is revoked and the request is forwarded as follows: * If `defaultLogoutLandingPage` is defined, the request is forwarded to the specified logout page. * If `defaultLogoutLandingPage` 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 `defaultLogoutLandingPage`. * If you don't define a `defaultLogoutLandingPage`, specify `logoutExpression` to resolve to `true` **only** for requests that target dedicated logout pages of the protected application.Consider the following examples when a `defaultLogoutLandingPage` is not configured:* This expression resolves to `true` **only** for requests with `/app/logout` in their path: ```json "logoutExpression": ${startsWith(request.uri.rawPath, '/app/logout')} ``` When a request matches the expression, the AM 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: ```json "logoutExpression": ${find(request.uri.query, 'logOff=true')} ``` When a request matches the expression, the AM session is revoked and the request is forwarded to the protected application without any other validation. In this example, an attacker can bypass IG's security mechanisms by simply adding `?logOff=true` to a request. | Default: `${false}` - `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* Handler to treat the request if an error occurs during authentication. If an error occurs during authentication, a [CdSsoFailureContext](Contexts.html#CdSsoFailureContext) is populated with details of the error and any associated `Throwable`. This is available to the failure handler so that it can respond appropriately. Be aware that the failure handler does not itself play a role in user authentication. It is only invoked if there is a problem that prevents user authentication from taking place. A number of circumstances may cause the failure handler to be invoked, including: * The redirect endpoint is invalid. * The redirect endpoint is invoked without a valid CDSSO token. * The redirect endpoint is invoked inappropriately. * An error was reported by AM during authentication. If no failure handler is configured, the default failure handler is used. See also [Handlers](Handlers.html). Default: HTTP 200 OK. The response entity contains details of the error. - `"verificationSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID for the secret to verify the signature of AM session tokens. `verificationSecretId` must point to a [CryptoKey](../security-guide/keys.html#secret-types). Default: IG discovers and uses the AM JWK set to verify the signature of AM session tokens. If the JWK set isn't available, IG does not verify the tokens. For information about how IG verifies signatures, refer to [Validate the signature of signed tokens](../security-guide/keys.html#secret-valid-signature). For information about how secret stores resolve named secrets, refer to [Secrets](secrets.html). - `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The [SecretsProvider](secrets.html#SecretsProvider) to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap or specify a SecretsProvider object inline. ## Example For an example that uses the CrossDomainSingleSignOnFilter, refer to [Cross-domain single sign-on (CDSSO)](../gateway-guide/sso-cdsso.html#cdsso). ## More information [org.forgerock.openig.openam.SingleSignOnFilter](../_attachments/apidocs/org/forgerock/openig/openam/SingleSignOnFilter.html) [CdSsoContext](Contexts.html#CdSsoContext) [CdSsoFailureContext](Contexts.html#CdSsoFailureContext) [SsoTokenContext](Contexts.html#SsoTokenContext)