Cross-domain single sign-on

For organizations relying on AM’s session and policy services with SSO, consider cross-Domain Single Sign-On (CDSSO) as an alternative to SSO through OpenID Connect.

This example sets up ForgeRock Identity Cloud as an SSO authentication server for requests processed by Identity Gateway. For more information about about Identity Gateway and CDSSO, refer to Authenticate with CDSSO.

Before you start, prepare Identity Cloud, IG, and the sample application as described in Example installation for this guide.

Set up Identity Cloud:

Log in to the Identity Cloud admin UI as an administrator.
Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
Go to Identities > Manage > Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t
Register an IG agent with the following values, as described in Register an IG agent in Identity Cloud:
- ID: ig_agent
- Password: password
- Redirect URLs: https://ig.ext.com:8443/home/cdsso/redirect

(Optional) Authenticate the agent to Identity Cloud as described in Authenticate an IG agent to Identity Cloud.

IG agents are automatically authenticated to Identity Cloud by a deprecated authentication module in Identity Cloud. This step is currently optional, but will be required when authentication chains and modules are removed in a future release of Identity Cloud.

Add a Validation Service:
1. In Identity Cloud, select Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Services, and add a validation service with the following Valid goto URL Resources:
  - https://ig.ext.com:8443/*
  - https://ig.ext.com:8443/*?*

Set up Identity Gateway:

Set up IG for HTTPS, as described in Configure IG for HTTPS (server-side).
Add the following session configuration to admin.json, to ensure that the browser passes the session cookie in the form-POST to the redirect endpoint (step 6 of Information flow during CDSSO):
```
{
  "connectors": […],
  "session": {
    "cookie": {
      "sameSite": "none",
      "secure": true
    }
  },
  "heap": […]
}
```
This step is required for the following reasons:
- When sameSite is strict or lax, the browser does not send the session cookie, which contains the nonce used in validation. If IG doesn’t find the nonce, it assumes that the authentication failed.
- When secure is false, the browser is likely to reject the session cookie.
  
  For more information, refer to admin.json.
Set an environment variable for the IG agent password, and then restart IG:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to IG, to serve .css and other static resources for the sample application:

Linux
Windows

$HOME/.openig/config/routes/static-resources.json

appdata\OpenIG\config\routes\static-resources.json

{
  "name" : "sampleapp-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css')}",
  "handler": "ReverseProxyHandler"
}

Add the following route to Identity Gateway, and correct the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/cdsso-idc.json

appdata\OpenIG\config\routes\cdsso-idc.json

{
  "name": "cdsso-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/cdsso')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "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": "&{amInstanceUrl}/oauth2/realms/alpha/connect/jwk_uri"
              }
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Notice the following features of the route compared to cdsso.json in CDSSO for IG in standalone mode, where Access Management is running locally:

The AmService URL points to Access Management in the Identity Cloud.

The AmService realm points to the realm where you configure your IG agent.

For the security of your deployment, always configure verificationSecretId in CrossDomainSingleSignOnFilter.
When verificationSecretId is not configured, IG does not verify the signature of AM session tokens, increasing the risk of CDSSO token tampering.

Restart IG.

Test the setup:
1. Go to https://ig.ext.com:8443/home/cdsso.
  
  If you see warnings that the site is not secure, respond to the warnings to access the site.
  
  The Identity Cloud login page is displayed.
2. Log in to Identity Cloud as user demo, password Ch4ng3!t.
  
  Access Management calls /home/cdsso/redirect, and includes the CDSSO token. The CrossDomainSingleSignOnFilter passes the request to sample app.

IG 2023.6

Cross-domain single sign-on