--- title: SingleSignOnFilter description: Tests for the presence and validity of an SSO token in the cookie header of a request: component: pinggateway version: 7.2 page_id: pinggateway:reference:SingleSignOnFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/SingleSignOnFilter.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-02T16:30:54Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/SingleSignOnFilter.html section_ids: websocket_notifications_for_sessions: WebSocket notifications for sessions SingleSignOnFilter-usage: Usage SingleSignOnFilter-properties: Properties SingleSignOnFilter-moreinfo: More information --- # SingleSignOnFilter Tests for the presence and validity of an SSO token in the cookie header of a request: * If an SSO token is present, the filter calls AM to validate the SSO token. If the SSO token is valid, the request continues along the chain. The token value and additional information are stored in the `ssoToken` context. For information, see [SsoTokenContext](RequestsResponsesContexts.html#SsoTokenContext). * If the SSO token is not present, or is empty or invalid, IG checks the `goto` query parameter for the presence of the redirection marker: * If the redirection marker parameter is present (for example, `_ig=true`), IG fails the request because the cookie domain is incorrectly configured. * If the redirection marker is not present, IG redirects the user-agent to the AM login page or another provided login page. For information about enabling, disabling, and naming the redirection marker, see the `redirectionMarker` property on this page. For more information about SSO, see [Single sign-on and cross-domain single sign-on](../gateway-guide/sso.html). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To prevent issues with performance when accessing large resources, such as .jpg and .js files, consider using the SingleSignOnFilter with the following options:- The `sessionCache`, so that IG can reuse session token information without repeatedly asking AM to verify the session token. - A ConditionalFilter, so that requests to access large resources skip the SingleSignOnFilter. For an example configuration, see the example in [ConditionalFilter](Filters.html#ConditionalFilter). | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When AM is using CTS-based sessions, it does not monitor idle time for client-side sessions, and so refresh requests are ignored.When the SingleSignOnFilter is used for authentication with AM, after a time AM can view the session as idle even though the user continues to interact with IG. The user session can eventually time out.*(From AM 6.5.3.)* When AM is using CTS-based sessions, use the `sessionIdleRefresh` property of AmService to refresh idle sessions, and prevent unwanted timeouts. | ## 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, see [WebSocket notifications](../maintenance-guide/tuning.html#amservice-websocket). ## Usage ```json { "name": string, "type": "SingleSignOnFilter", "config": { "amService": AmService reference, "authenticationService": configuration expression, "redirectionMarker": object, "realm": configuration expression, "defaultLogoutLandingPage": configuration expression, "loginEndpoint": runtime expression, "logoutExpression": runtime expression, "logoutEndpoint": pattern //deprecated } } ``` ## Properties * `"amService"`: *AmService [reference](preface.html#definition-reference), required* An AmService object to use for the following properties: * `agent`, the credentials of the IG agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint. * `realm`: Realm of the IG agent in AM. * `url`, the URL of an AM service to use for session token validation and authentication when `loginEndpoint` is not specified. * `ssoTokenHeader`, the name of the cookie that contains the session token created by AM. * `amHandler`, the handler to use when communicating with AM to validate the token in the incoming request. * `sessionCache`, the configuration of a cache for session information from AM. * `version`: The version of the AM server. The AM version is derived as follows, in order of precedence: * Discovered value: AmService discovers the AM version. If `version` is configured with a different value, AmService ignores the value of `version` and issues a warning. * Value in `version`: AmService cannot discover the AM version, and `version` is configured. * Default value of AM 6: AmService cannot discover the AM version, and `version` is not configured. - `redirectionMarker`: *[object](preface.html#definition-object), optional* ```json "redirectionMarker": { "enabled": configuration expression, "name": configuration expression } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* When `true`, use a redirection marker to limit the number of authentication redirects. When there is no SSO session due to, for example, SSO cookie name misconfiguration, an authentication request fails and is redirected back to IG. The scenario can result in infinite authentication redirects. Consider enabling the redirection marker during development, then disabling it to prevent it being captured in bookmarks. \+ 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` - `"authenticationService"`: *configuration expression<[string](preface.html#definition-string)>,optional* The name of an AM authentication tree or authentication chain to use for authentication. Default: AM's default authentication service. For an example that uses `authenticationService`, see [Authenticate with SSO through an AM authentication tree](../gateway-guide/sso.html#proc-sso-authservice). For more information about authentication trees and chains, see [Authentication nodes and trees](https://docs.pingidentity.com/pingam/7.2/authentication-guide/about-authentication-trees.html) and [Authentication modules and chains](https://docs.pingidentity.com/pingam/7.2/authentication-guide/about-authentication-modules-and-chains.html) in AM's *Authentication and SSO* guide. - `"realm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The AM realm where the user is authenticated. Default: The realm declared for `amService`. * `"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. * `"loginEndpoint"`: *runtime expression<[url](preface.html#definition-url)>, optional* The URL of a service instance for the following tasks: * Manage authentication and the location to which the request is redirected after authentication. * Process policy advices after an AM policy decision denies a request with supported advices. The PolicyEnforcementFilter redirects the request to this URL, with information about how to meet the conditions in the advices. For examples of different advice types, and the conditions that cause AM to return advices, see AM's [Authorization guide](https://docs.pingidentity.com/pingam/7.2/authorization-guide/). For information about supported advice types in IG, see [Using Advices From Policy Decisions](Filters.html#pef-advices). Default: The value of `url` in `amService` Authentication can be performed in the following ways: * Directly through AM, with optional authentication parameters in the query string, such as `service`, `module`, and `realm`. For a list of authentication parameters that you can include in the query string, see [Authenticating (browser)](https://docs.pingidentity.com/pingam/7.2/authentication-guide/authn-from-browser.html) in AM's *Authentication and SSO* guide. The value must include a redirect with a `goto` parameter. The following example uses AM as the authentication service, and includes the `service` authentication parameter: ```json "loginEndpoint": "https://am.example.com/openam?service=TwoFactor&goto=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}" ``` * Through the URL of another application, with optional authentication parameters in the query string, such as `service`, `module`, and `realm`. The application must create a session with an AM instance to set an SSO token and return the request to the redirect location. The value can optionally include a redirect with a `goto` parameter or different parameter name. The following example uses an authentication service that is not AM, and includes a redirect parameter: ```json "loginEndpoint": "https://authservice.example.com/auth?redirect=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}" ``` When using this option, review the cookie domains to make sure that cookies set by the authentication server are properly conveyed to the IG instance. - `"logoutExpression"`: *runtime expression<[boolean](preface.html#definition-boolean)>, optional* A flag to indicate that a logout condition is met. The condition is based on the request: * `true`: The AM session token for the end user is revoked. If a `defaultLogoutLandingPage` is specified, the request is redirected to that page. * `false`: The request continues to be processed. The following example expressions can be used to trigger revocation of the end user token: * The request URI contains `/logout`: ```none ${find(request.uri, '/logout')} ``` * The request path starts with `/logout`: ```none ${find(request.uri.path, '^/logout')} ``` * The request query includes the `logOff=true` query parameter: ```none ${find(request.uri.query, 'logOff=true')} ``` Default: `${false}` - `"logoutEndpoint"`: *pattern, optional* | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `logoutExpression` instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | A string denoting a regular expression pattern for a URL. When a request matches the pattern, IG performs the logout process and the AM authentication token for the end user is revoked. If a defaultLogoutLandingPage is specified, the request is redirected to that page. Otherwise, the request continues to be processed. Default: Logout is not managed by this filter. ## More information [org.forgerock.openig.openam.SingleSignOnFilter](../_attachments/apidocs/org/forgerock/openig/openam/SingleSignOnFilter.html) [org.forgerock.openig.openam.SsoTokenContext](../_attachments/apidocs/org/forgerock/openig/openam/SsoTokenContext.html) [SsoTokenContext](RequestsResponsesContexts.html#SsoTokenContext)