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

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.

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.

Usage

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

Properties

"amService": AmService 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, optional

"redirectionMarker": {
   "enabled": configuration expression<boolean>,
   "name": configuration expression<string>
}

enabled: configuration expression<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>, 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.

Default: AM’s default authentication service.

For an example that uses authenticationService, see Authenticate with SSO through an AM authentication tree.

For more information about authentication trees and chains, see Authentication nodes and trees and Authentication modules and chains in AM’s Authentication and SSO guide.
"realm": configuration expression<string>, optional: The AM realm where the user is authenticated.

Default: The realm declared for amService.

"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 IG 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 IG, see Using Advices From Policy Decisions.

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 that cookies set by the authentication server are properly conveyed to the IG instance.

"logoutExpression": runtime expression<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:
```
${find(request.uri, '/logout')}
```
The request path starts with /logout:
```
${find(request.uri.path, '^/logout')}
```
The request query includes the logOff=true query parameter:
```
${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.

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

org.forgerock.openig.openam.SsoTokenContext

SsoTokenContext