SingleSignOnFilter

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

You can find an example of how to configure SSO and information about the SSO data flow in 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 doesn’t 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": {
      "enabled": configuration expression<boolean>,
      "name": configuration expression<string>
    },
    "defaultLogoutLandingPage": configuration expression<url>,
    "loginEndpoint": runtime expression<url>,
    "logoutExpression": runtime expression<boolean>
  }
}

Properties

amService

"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, PingGateway can use the token to get the user’s profile, make policy evaluations, and connect 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 isn’t 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: The AmService discovers the AM version. If version is configured with a different value, the AmService ignores the value of version and logs a warning.
- Value in version: The AmService cannot discover the AM version and version is configured.
- Default value of AM 6: AmService cannot discover the AM version and version isn’t configured.

authenticationService

"authenticationService": configuration expression<string>,optional

The name of an AM authentication tree to use for authentication. Learn more in the AM documentation on Authentication nodes and trees.

Default: AM’s default authentication tree.

redirectionMarker

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.

"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

defaultLogoutLandingPage

"defaultLogoutLandingPage": configuration expression<url>, optional

The URL to which a request is redirected if logoutExpression is evaluated as true.

If this property isn’t 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

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

PingGateway can perform authentication in the following ways:

Directly through AM, with optional authentication parameters in the query string, such as service, module, and realm. Learn more about authentication query parameters in the AM documentation on authenticating browsers.

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, optional authentication parameters in the query string, such as service, module, and realm. The application must create a session with AM 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 isn’t 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.

Learn more in PolicyEnforcementFilter and the AM authorization documentation.

Default: The value of url in amService

logoutExpression

"logoutExpression": runtime expression<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 AM session is found, the request is forwarded to the protected application.
- If a valid AM session isn’t 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 isn’t defined, the request is forwarded to the protected application without any other validation.
- If a valid session isn’t 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 isn’t 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 adding ?logOff=true to a request.

Default: ${false}

More information

org.forgerock.openig.openam.SingleSignOnFilter

org.forgerock.openig.openam.SsoTokenContext

SsoTokenContext