SingleSignOnFilter

When this filter processes a request, it injects the SSO token, the session user ID, and the full claims set into the SsoTokenContext.

For an example of how to configure SSO and information about the SSO data flow, refer to Single sign-on (SSO).

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 PingGateway 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.

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 PingGateway. The user session can eventually time out.

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, PingGateway receives a notification from AM when a user logs out of AM, or when the AM session is modified, closed, or times out. PingGateway 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.

Usage

{
  "name": string,
  "type": "SingleSignOnFilter",
    "config": {
      "amService": AmService reference,
      "authenticationService": configuration expression<string>,
      "redirectionMarker": object,
      "defaultLogoutLandingPage": configuration expression<url>,
      "loginEndpoint": runtime expression<url>,
      "logoutExpression": runtime expression<boolean>
  }
}

Properties

"amService": AmService reference, required

An AmService object to use for the following properties:

agent, the credentials of the PingGateway 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 PingGateway 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, optional

A redirect marker for the SSO flow. If the marker is present in the SSO 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 SSO 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

"authenticationService": configuration expression<string>,optional

The name of an AM authentication tree or authentication chain to use for authentication.

Use only authentication trees with PingOne Advanced Identity Cloud. Authentication modules and chains aren’t supported.

Default: AM’s default authentication tree.

For more information about authentication trees and chains, refer to Authentication nodes and trees and Authentication modules and chains in AM’s Authentication and SSO guide.

"defaultLogoutLandingPage": configuration expression<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 PingGateway domain name.

This parameter is effective only when logoutExpression is specified.

Default: None, processing continues.

"loginEndpoint": runtime expression<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. For information about supported advice types in PingGateway, refer to PolicyEnforcementFilter.

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) 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:
```
"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:
```
"loginEndpoint": "https://authservice.example.com/auth?redirect=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}"
```
When using this option, review the cookie domains to make sure cookies set by the authentication server are properly conveyed to the PingGateway instance.

"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 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:
```
"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:
```
"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 PingGateway’s security mechanisms by simply adding ?logOff=true to a request.

Default: ${false}

More information

org.forgerock.openig.openam.SingleSignOnFilter

org.forgerock.openig.openam.SsoTokenContext

SsoTokenContext