CrossDomainSingleSignOnFilter

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 are not 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". Should an error occur during authentication, the error details are captured in a "CdSsoFailureContext".

For an example of how to configure CDSSO in AM and IG, and information about the flow of data between AM, IG, and a protected application, see "Authenticating With CDSSO".

Supported with AM 5.5 and later versions.

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": "CrossDomainSingleSignOnFilter",
  "config": {
    "amService": AmService reference,
    "redirectEndpoint": runtime expression<uri string>,
    "authenticationService": configuration expression<string>,
    "authCookie": object,
    "defaultLogoutLandingPage": configuration expression<url>,
    "logoutExpression": runtime expression<boolean>,
    "failureHandler": Handler reference,
    "verificationSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference
  }
}

Properties

"amService": AmService reference, required

The AmService heap 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.

  • url, the URL of an AM service to use for session token validation and authentication.

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

  • realm: Realm of the IG agent in AM.

  • version: The version of the AM server.

See also, "AmService".

"redirectEndpoint": runtime expression<uri string>, required

The URI to the endpoint for CDSSO. This URI must also be configured in AM exactly as it is configured here.

To make sure that the redirect is routed back to this filter, where the authentication can be validated, 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: 

    "condition": "${matches(request.uri.path, '^/home/cdsso')}"

    "redirectEndpoint": "/home/cdsso/callback"

  • To match the route condition.

    For example, use the following route condition with the following endpoint: 

    "condition": "${matches(request.uri.path, '^/home/cdsso')}"

    "redirectEndpoint": "/home/cdsso"

    Note

    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 that 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: 

    "condition": "${matches(request.uri.path, '^/home/cdsso/redirect') || matches(request.uri.path, '^/ig/cdssoRedirectUri')}"

    "redirectEndpoint": "/ig/cdssoRedirectUri"

"authenticationService": configuration expression<uri 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 Single Sign-On Guide.

"authCookie": object, optional

The configuration of the cookie used to store the authentication. 

{
  "cookie": {
    "name": configuration expression<string>,
    "domain": configuration expression<string>,
    "httpOnly": configuration expression<boolean>,
    "path": configuration expression<string>,
    "sameSite": configuration expression<enumeration>,
    "secure": configuration expression<boolean>
  }
}
"name": configuration expression<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>, 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>, optional

Flag to mitigate the risk of client-side scripts accessing protected cookies.

Default: true

"path": configuration expression<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>, optional

Manage the circumstances in which a cookie is sent to the server. Use one of the following options to reduce the risk of cross-site request forgery (CSRF) attacks:

  • STRICT: Send the cookie only if the request was initiated from the cookie domain.

  • LAX: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain.

The value is not case-sensitive.

Default: Null; send the cookie whenever a request is made to the cookie domain.

"secure": configuration expression<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

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

"logoutExpression" runtime expression<boolean>, optional

An expression to define a condition for logout, based on the request. If the expression evaluates to true, the AM session 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.

The following example expressions can be used to trigger revocation of the end user token:

  • The request URI contains /logout: 

    ${matches(request.uri, '/logout')}

  • The request path starts with /logout: 

    ${matches(request.uri.path, '^/logout')}

  • The request query includes the logOff=true query parameter: 

    ${matches(request.uri.query, 'logOff=true')}

Default: Logout is not managed by this filter.

"failureHandler": Handler reference, optional

Handler to treat the request if an error occurs during authentication.

If an error occurs during authentication, a "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.

Default: HTTP 200 OK. The response entity contains details of the error.

"verificationSecretId": configuration expression<secret-id>, required to verify the signature of signed tokens

The secret ID for the secret to verify the signature of signed tokens.

If configured, the token must be signed. If not configured, IG does not verify the signature.

For information about how signatures are validated, see "Validating the Signature of Signed Tokens". For information about how each type of secret store resolves named secrets, see Secret Stores.

"secretsProvider": SecretsProvider reference, required to verify the signature of signed JWTs

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

In the following example from Single Sign-On and Cross-Domain Single Sign-On, IG uses authentication from AM on a different domain to process a request: 

{
  "name": "cdsso",
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/cdsso')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "http://openam.example.com:8088/openam",
        "realm": "/",
        "version": "7",
        "agent": {
          "username": "ig_agent_cdsso",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/home/cdsso/redirect",
            "authCookie": {
              "path": "/home",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1",
            "verificationSecretId": "verify",
            "secretsProvider": {
              "type": "JwkSetSecretStore",
              "config": {
                "jwkUrl": "http://openam.example.com:8088/openam/oauth2/connect/jwk_uri"
              }
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}
Read a different version of :