Untitled :: ForgeRock Identity Gateway

Identity Cloud guide

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

This guide is for ForgeRock Identity Cloud evaluators, administrators, and architects. It provides examples of how to integrate your business application and APIs with Identity Cloud for Single Sign-On and API Security, with ForgeRock Identity Gateway.

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

Identity Gateway installed on http://ig.example.com:8080, as described in Download and start IG.
Sample application installed on http://app.example.com:8081, as described in Using the sample application.
The ForgeRock Identity Cloud, with the default configuration, as described in the ForgeRock Identity Cloud Docs.

When you are using the ForgeRock Identity Cloud, you need to know the value of the following properties:

The root URL of your ForgeRock Identity Cloud. For example, https://myTenant.forgeblocks.com.

The URL of the Access Management component of the ForgeRock Identity Cloud is the root URL of your Identity Cloud followed by /am. For example, https://myTenant.forgeblocks.com/am.
The realm where you work. The examples in this document use alpha.

Prefix each realm in the hierarchy with the realms keyword. For example, /realms/root/realms/alpha.

If you use a different configuration, substitute in the procedures accordingly.

Set up an IG agent in Identity Cloud

This procedure sets up an agent that acts on behalf of IG. After the agent is authenticated, the token can be used to get the user profile, evaluate policies, and connect to the AM notification endpoint.

Log in to the Identity Cloud admin UI as an administrator.
Click Gateways & Agents > New Gateway/Agent > Identity Gateway > Next, and add an agent profile:
- ID: agent-name
- Password: agent-password
  
  Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.
Click Save Profile > Done. The agent profile page is displayed.
To add a redirect URL for CDSSO, go to the agent profile page and add the URL.
To change the introspection scope, click Native Consoles > Access Management, and update the agent in the AM admin UI. By default, the agent can introspect OAuth 2.0 tokens issued to any client, in the realm and subrealm where it is created.

Set up a demo user in Identity Cloud

This procedure sets up a demo user in the alpha realm.

Log in to the Identity Cloud admin UI as an administrator.
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

About Identity Gateway and the ForgeRock Identity Cloud

ForgeRock Identity Cloud simplifies the consumption of ForgeRock as an Identity Platform. However, many organizations have business web applications and APIs deployed across multiple clouds, or on-premise.

Identity Gateway facilitates non-intrusive integration of your web applications and APIs with the Identity Cloud, for SSO and API Security. The following image illustrates how Identity Gateway bridges your business to the ForgeRock Identity Cloud:

Identity Gateway bridges business applications and APIs to the ForgeRock Identity Cloud.

For information about the ForgeRock Identity Cloud, refer to the ForgeRock Identity Cloud Docs.

API security with OAuth 2.0 and the ForgeRock Identity Cloud

This example sets up OAuth 2.0, using the standard introspection endpoint, where ForgeRock Identity Cloud is the authorization server, and Identity Gateway is the resource server.

For more information about Identity Gateway as an OAuth 2.0 resource server, see Validate access tokens through the introspection endpoint.

This procedure uses the Resource Owner Password Credentials grant type. According to information in the The OAuth 2.0 Authorization Framework, minimize use of this grant type and utilize other grant types whenever possible.

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

Set up Identity Cloud:
1. Log in to the Identity Cloud admin UI as an administrator.
2. 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
3. Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
4. Add a web application:
  1. In the Identity Cloud admin UI, click Applications > Add Application > Web, and add a web application with the following values:
    
    Client ID: oauth2-client
    
    Client Secret: password
  2. On the application page, add the following general settings:
    
    Grant Types: Resource Owner Password Credentials
    
    Scopes: mail
5. Add an IG agent with the following values, as described in Set up an IG agent in Identity Cloud:
  - ID: ig_agent
  - Password: password

Set up Identity Gateway:

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 Identity Gateway, replacing the value for the property amInstanceUrl:

Linux
Windows

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

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

{
  "name": "oauth2rs-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/oauth2rs-idc')}",
  "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"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "OAuth2ResourceServerFilter-1",
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "scopes": [
              "mail"
            ],
            "requireHttps": false,
            "realm": "OpenIG",
            "accessTokenResolver": {
              "name": "TokenIntrospectionAccessTokenResolver-1",
              "type": "TokenIntrospectionAccessTokenResolver",
              "config": {
                "amService": "AmService-1",
                "providerHandler": {
                  "type": "Chain",
                  "config": {
                    "filters": [
                      {
                        "type": "HttpBasicAuthenticationClientFilter",
                        "config": {
                          "username": "ig_agent",
                          "passwordSecretId": "agent.secret.id",
                          "secretsProvider": "SystemAndEnvSecretStore-1"
                        }
                      }
                    ],
                    "handler": "ForgeRockClientHandler"
                  }
                }
              }
            }
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html; charset=UTF-8" ]
          },
          "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }
    }
  }
}

Notice the following features of the route compared to rs-introspect.json in Validate access tokens through the introspection endpoint, where a local Access Management instance is the authorization server:

The AmService URL points to Access Management in the Identity Cloud.
The AmService realm points to the realm where you have configured your web application and the IG agent.

Test the setup:

In a terminal, export an environment variable for URL of Access Management in the Identity Cloud:
```
$ export amInstanceUrl='myAmInstanceUrl'
```

Use a curl command similar to the following to retrieve an access token:

$ mytoken=$(curl -s \
--user "oauth2-client:password" \
--data 'grant_type=password&username=demo&password=Ch4ng3!t&scope=mail' \
$amInstanceUrl/oauth2/realms/alpha/access_token | jq -r ".access_token")

Validate the access token returned in the previous step:

$ curl -v http://ig.example.com:8080/oauth2rs-idc --header "Authorization: Bearer ${mytoken}"

{
  active = true,
  scope = mail,
  realm = /alpha,
  client_id = oauth2-client,
  ...
}

Single sign-on with OpenID Connect and the ForgeRock Identity Cloud

This example sets up ForgeRock Identity Cloud as an OpenID Connect identity provider, and Identity Gateway as a relying party.

For more information about Identity Gateway and OpenID Connect, see OpenID Connect.

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

Set up Identity Cloud:
1. Log in to the Identity Cloud admin UI as an administrator.
2. 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
3. Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
4. Add a web application:
  1. In the Identity Cloud admin UI, click Applications > Add Application > Web, and add a web application with the following values:
    
    Client ID: oidc-client
    
    Client Secret: password
  2. In General Settings on the application page, add the following values:
    
    Sign-in URLs: http://ig.example.com:8080/home/id_token/callback
    
    Grant Types: Authorization Code
    
    Scopes: openid, profile, mail
  3. Click Show advanced settings > Authentication, and click Implied Consent:
    
    The resource owner is not asked for consent during authorization flows.

Set up Identity Gateway:

Set an environment variable for the oidc-client password, and then restart IG:
```
$ export CLIENT_SECRET_ID='cGFzc3dvcmQ='
```

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, replacing the value for the property amInstanceUrl:

Linux
Windows

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

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

{
  "name": "oidc-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/id_token')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "AuthorizationCodeOAuth2ClientFilter-1",
          "type": "AuthorizationCodeOAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/home/id_token",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/plain"
                  ]
                },
                "entity": "Error in OAuth 2.0 setup."
              }
            },
            "registrations": [
              {
                "name": "oauth2-client",
                "type": "ClientRegistration",
                "config": {
                  "clientId": "oidc-client",
                  "clientSecretId": "client.secret.id",
                  "issuer": {
                    "name": "Issuer",
                    "type": "Issuer",
                    "config": {
                      "wellKnownEndpoint": "&{amInstanceUrl}/oauth2/realms/alpha/.well-known/openid-configuration"
                    }
                  },
                  "scopes": [
                    "openid",
                    "profile",
                    "mail"
                  ],
                  "secretsProvider": "SystemAndEnvSecretStore-1",
                  "tokenEndpointAuthMethod": "client_secret_basic"
                }
              }
            ],
            "requireHttps": false,
            "cacheExpiration": "disabled"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Notice the following features of the route compared to 07-openid.json in Use AM As a Single OpenID Connect Provider, where Access Management is running locally:

The ClientRegistration wellKnownEndpoint points to the Identity Cloud.

Test the setup:
1. Go to http://ig.example.com:8080/home/id_token. The Identity Cloud login page is displayed.
2. Log in to Identity Cloud as user demo, password Ch4ng3!t. The home page of the sample application is displayed.

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, see 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:
1. Log in to the Identity Cloud admin UI as an administrator.
2. Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
3. 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
4. Add an IG agent with the following values, as described in Set up an IG agent in Identity Cloud:
  - ID: ig_agent
  - Password: password
  - Redirect URLs: https://ig.example.com:8443/home/cdsso/redirect
5. 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.example.com:8443/*
    
    https://ig.example.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.

Restart IG.

Test the setup:
1. Go to https://ig.example.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.

Policy enforcement

The following procedure gives an example of how to request and enforce policy decisions from Identity Cloud.

Enforce a simple policy

Before you start, set up and test the example in Cross-domain single sign-on.

Set up Identity Cloud:
1. In the Identity Cloud admin UI, select Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Authorization > Policy Sets > New Policy Set, and add a policy set with the following values:
  - Id : PEP-CDSSO
  - Resource Types : URL
3. In the new policy set, add a policy with the following values:
  - Name : CDSSO
  - Resource Type : URL
  - Resource pattern : *://*:*/*
  - Resource value : http://app.example.com:8081/home/cdsso
    
    This policy protects the home page of the sample application.
4. On the Actions tab, add an action to allow HTTP GET.
5. On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.

Set up IG:

Replace cdsso-idc.json with the following route, and correct the value for the property amInstanceUrl:

Linux
Windows

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

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

{
  "name": "pep-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"
          }
        },
        {
          "name": "PolicyEnforcementFilter-1",
          "type": "PolicyEnforcementFilter",
          "config": {
            "application": "PEP-CDSSO",
            "ssoTokenSubject": "${contexts.cdsso.token}",
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Note the following feature of the route compared to cdsso-idc.json:

The CrossDomainSingleSignOnFilter is followed by a PolicyEnforcementFilter to enforce the policy PEP-CDSSO.

Test the setup:
1. Go to https://ig.example.com:8443/home/cdsso.
  
  If you have warnings that the site is not secure respond to the warnings to access the site.
  
  IG redirects you to Identity Cloud for authentication.
2. Log in to Identity Cloud as user demo, password Ch4ng3!t.
  
  Identity Cloud redirects you back to the request URL, and IG requests a policy decision. Identity Cloud returns a policy decision that grants access to the sample application.

Step up authorization for a transaction

Before you start, set up and test the example in pep.adoc#pep-cdsso.

In the Identity Cloud admin UI, select Scripts > Auth Scripts > New Script > Journey Decision Node > Next, and add a default Journey Decision Node Script script called TxTestPassword:

/*
  - Data made available by nodes that have already executed are available in the sharedState variable.
  - The script should set outcome to either "true" or "false".
 */

var givenPassword = nodeState.get("password").asString()

if (givenPassword.equals("7890")) {
  outcome = "true"
} else {
  outcome = "false"
}

Configure a journey:
1. Click Journeys and add a journey with the following configuration:
  - Name: Tx01_Tree
  - Identity Object: Alpha realm users
    
    The journey canvas is displayed.
2. In Nodes > Basic Authentication, drag a Password Collector node onto the canvas.
3. In Nodes > Utilities, drag a Scripted decision node onto the canvas.
4. Configure the scripted decision node as follows:
  - Script: select TxTestPassword
  - Outcomes: enter true and false
5. Connect the nodes as shown:
  
  For information about configuring trees, refer to ForgeRock Identity Cloud Docs
Edit the authorization policy:
1. In the Identity Cloud admin UI, select Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Authorization > Policy Sets > PEP-CDSSO, and add the following environment condition to the CDSSO policy:
  - All of
  - Type: Transaction
  - Script name: Authenticate to tree
  - Strategy Specifier: Tx01_Tree
Test the setup:
1. In a browser, go to https://ig.example.com:8443/home/cdsso.
  
  If you have not previously authenticated to Identity Cloud, the CrossDomainSingleSignOnFilter redirects the request to Identity Cloud for authentication.
2. Log in to Identity Cloud as user demo, password Ch4ng3!t.
3. Enter the password 7890 required by the script TxTestPassword.
  
  Identity Cloud redirects you back to the request URL, and IG requests a policy decision. Identity Cloud returns a policy decision based on the authentication journey.

Pass runtime data downstream in a JWT

This example sets up Identity Cloud as an identity provider, to pass identity or other runtime information downstream, in a JWT signed with a PEM.

For more information about using runtime data, refer to Passing data along the chain. To help with development, the sample application includes a /jwt endpoint to display the JWT, verify its signature, and decrypt it.

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

Set up secrets:
1. Locate a directory for secrets, and go to it:
  $ cd /path/to/secrets
2. Create the following secret key and certificate pair as PEM files:
  $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout ig.example.com-key.pem \ -out ig.example.com-certificate.pem
  Two PEM files are created, one for the secret key, and another for the associated certificate.
3. Map the key and certificate to the same secret ID in IG:
  $ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem
4. Generate PEM files to sign and verify the JWT:
  $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout id.key.for.signing.jwt.pem \ -out id.key.for.verifying.jwt.pem
5. Make sure the following files have been added to your secrets directory:
  - id.key.for.signing.jwt.pem
  - id.key.for.verifying.jwt.pem
  - key.manager.secret.id.pem
  - ig.example.com-certificate.pem
  - ig.example.com-key.pem
Set up Identity Cloud:
1. Log in to the Identity Cloud admin UI as an administrator.
2. 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
3. Add an IG agent with the following values, as described in Set up an IG agent in Identity Cloud:
  - ID: ig_agent_jwt
  - Password: password
  - Redirect URLs: https://ig.example.com:8443/jwt/redirect
4. 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.example.com:8443/*
    
    https://ig.example.com:8443/*?*

Set up IG:

Set up TLS by adding the following file to IG, replacing the value for the property secretsDir:

Linux
Windows

$HOME/.openig/config/admin.json

appdata\OpenIG\config\admin.json

{
  "mode": "DEVELOPMENT",
  "properties": {
    "secretsDir": "/path/to/secrets"
  },
  "connectors": [
    {
      "port": 8080
    },
    {
      "port": 8443,
      "tls": "ServerTlsOptions-1"
    }
  ],
  "session": {
    "cookie": {
      "sameSite": "none",
      "secure": true
    }
  },
  "heap": [
    {
      "name": "ServerTlsOptions-1",
      "type": "ServerTlsOptions",
      "config": {
        "keyManager": {
          "type": "SecretsKeyManager",
          "config": {
            "signingSecretId": "key.manager.secret.id",
            "secretsProvider": "ServerIdentityStore"
          }
        }
      }
    },
    {
      "name": "ServerIdentityStore",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "&{secretsDir}",
        "suffix": ".pem",
        "mappings": [{
          "secretId": "key.manager.secret.id",
          "format": {
            "type": "PemPropertyFormat"
          }
        }]
      }
    }
  ]
}

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 IG, replacing the value for the properties secretsDir and amInstanceUrl:

Linux
Windows

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

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

{
  "name": "jwt-idc",
  "condition": "${find(request.uri.path, '/jwt')}",
  "baseURI": "http://app.example.com:8081",
  "properties": {
    "secretsDir": "/path/to/secrets",
    "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_jwt",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "pemPropertyFormat",
      "type": "PemPropertyFormat"
    },
    {
      "name": "FileSystemSecretStore-1",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "&{secretsDir}",
        "suffix": ".pem",
        "mappings": [{
          "secretId": "id.key.for.signing.jwt",
          "format": "pemPropertyFormat"
        }]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/jwt/redirect",
            "authCookie": {
              "path": "/jwt",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1",
            "verificationSecretId": "verify",
            "secretsProvider": {
              "type": "JwkSetSecretStore",
              "config": {
                "jwkUrl": "&{amInstanceUrl}/oauth2/realms/alpha/connect/jwk_uri"
              }
            }
          }
        },
        {
          "name": "UserProfileFilter",
          "type": "UserProfileFilter",
          "config": {
            "username": "${contexts.ssoToken.info.uid}",
            "userProfileService": {
              "type": "UserProfileService",
              "config": {
                "amService": "AmService-1"
              }
            }
          }
        },
        {
          "name": "JwtBuilderFilter-1",
          "type": "JwtBuilderFilter",
          "config": {
            "template": {
              "name": "${contexts.userProfile.commonName}",
              "email": "${contexts.userProfile.rawInfo.mail[0]}"
            },
            "secretsProvider": "FileSystemSecretStore-1",
            "signature": {
              "secretId": "id.key.for.signing.jwt",
              "algorithm": "RS512"
            }
          }
        },
        {
          "name": "HeaderFilter-1",
          "type": "HeaderFilter",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "x-openig-user": ["${contexts.jwtBuilder.value}"]
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Test the setup:
1. Go to https://ig.example.com:8443/jwt.
  
  If you receive 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. The sample app displays the signed JWT along with its header and payload.
3. In USE PEM FILE, enter the absolute path to id.key.for.verifying.jwt.pem to verify the JWT signature.

IG 2023.2

Identity Cloud guide

Example installation for this guide

Set up an IG agent in Identity Cloud

Set up a demo user in Identity Cloud

About Identity Gateway and the ForgeRock Identity Cloud

API security with OAuth 2.0 and the ForgeRock Identity Cloud

Single sign-on with OpenID Connect and the ForgeRock Identity Cloud

Cross-domain single sign-on

Policy enforcement

Enforce a simple policy

Step up authorization for a transaction

Pass runtime data downstream in a JWT