Follow these steps to install IG:

1. Download IG-6.5.4.war from the ForgeRock BackStage download site .

2. Copy the .war file to the root context of the web application container:

   • For Tomcat, copy the file to /path/to/tomcat/webapps/ROOT.war.

   • For Jetty, copy the file to /path/to/jetty/webapps/IG-6.5.4.war. Jetty automatically deploys IG in the root context on startup.

   • For JBoss, see "JBoss EAP For IG".

   Important

   If you use startup scripts to bootstrap the IG web container, the scripts can start the container process with a different user. To prevent errors, make sure that the location of the IG configuration is correct. Alternatively, adapt the startup scripts to specify the IG_INSTANCE_DIR env variable or ig.instance.dir system properties, taking care to set file permissions correctly.

   If you start and stop the IG web container yourself, the default location of the IG configuration files is correct. By default, IG configuration files are located under $HOME/.openig on Linux, Mac, and UNIX systems, and under %appdata%\OpenIG on Windows.

3. Prepare your IG configuration files.

   For information about configuration files, see "Configuration Directories and Files". For information about how to change the default location of the configuration files, see "Changing the Default Location of the Configuration Folders".

   If you have not yet prepared configuration files, then start with the configuration described in "Trying IG With a Simple Configuration" in the Getting Started Guide.

   Copy the template to $HOME/.openig/config/config.json. Replace the baseURI of the DispatchHandler with that of the protected application.

   On Windows, copy the template to %appdata%\OpenIG\config\config.json. To locate the %appdata% folder for your version of Windows, open Windows Explorer, type %appdata% as the file path, and press Enter. You must create the %appdata%\OpenIG\config folder, and then add the configuration file.

4. Start the web container where IG is deployed.

5. Browse to the protected application.

   IG should now proxy all traffic to the application.

6. Make sure the browser is going through IG.

   Verify this in one of the following ways:

   • Follow these steps:

     1. Stop the IG web container.

     2. Verify that you cannot browse to the protected application.

     3. Start the IG web container.

     4. Verify that you can now browse to the protected application again.

   • Check the logs to see that traffic is going through IG.

1. Generate a keystore, where the keystore and the private key have the same password:

   $ keytool \
     -genkey \
     -alias jwe-key \
     -keyalg rsa \
     -keystore /path/to/secrets/jwtsessionkeystore.pkcs12 \
     -storepass password \
     -keypass password \
     -dname "CN=openig.example.com,O=Example Corp"

   Note

   Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.

2. Create an IG environment variable with the value of the KeyStore password, password, and restart IG:

   $ export KEYSTORE_SECRET_ID='cGFzc3dvcmQ='

   The password is retrieved by the default SystemAndEnvSecretStore, and must be base64-encoded.

3. In IG, add the following route as $HOME/.openig/config/routes/jwt-session.json (on Windows, %appdata%\OpenIG\config\routes\jwt-session.json).

   {
     "name": "jwt-session",
     "secrets": {
       "stores": [
         {
           "name": "KeyStoreSecretStore",
           "type": "KeyStoreSecretStore",
           "config": {
             "file": "/path/to/secrets/jwtsessionkeystore.pkcs12",
             "storeType": "PKCS12",
             "storePassword": "keystore.secret.id",
             "mappings": [{
               "secretId": "jwtsession.encryption.secret.id",
               "aliases": [ "jwe-key" ]
             }]
           }
         }
       ]
     },
     "session": {
       "type": "JwtSession",
       "config": {
         "encryptionSecretId": "jwtsession.encryption.secret.id",
         "cookie": {
           "name": "IG",
           "domain": ".example.com"
         }
       }
     },
     "handler": {
       "type": "StaticResponseHandler",
       "config": {
         "status": 200,
         "reason": "OK",
         "entity": "Hello, world!"
       }
     },
     "condition": "${matches(request.uri.path, '^/jwt-session')}"
   }

4. Notice the following features of the route:

   • The route matches requests to /jwt-session.

   • The secrets object configures a KeyStoreSecretStore to manage secrets for session encryption. The KeyStoreSecretStore includes a secret ID mapping to the alias of the session encryption key.

     For information, see KeyStoreSecretStore(5) in the Configuration Reference.

   • The session refers to the encryption key to encrypt the JWT.

In deployments with more than one IG instance, configure a JWT signature to sign and verify the JWTs.

1. Create an IG environment variable with the value of a session signature secret, and restart IG: this_is_a_session_signature_secret:

   $ export JWTSESSION_SIGNATURE_SECRET_ID='dGhpc19pc19hX3Nlc3Npb25fc2lnbmF0dXJlX3NlY3JldA=='

   The secret must be at least 32-characters long and base64-encoded.

2. Add the signatureSecretId to the session object in the previous route:

   {
     "session": {
       "type": "JwtSession",
       "config": {
         "encryptionSecretId": "jwtsession.encryption.secret.id",
         "cookie": {
           "name": "IG",
           "domain": ".example.com"
         },
         "signatureSecretId": "jwtsession.signature.secret.id"
       }
     }
   }

1. In $HOME/.openig/config/admin.json (on Windows, %appdata%\OpenIG\config), change the value of mode from DEVELOPMENT to PRODUCTION:

   {
     "mode": "PRODUCTION"
   }

   The file changes the operating mode from development mode to production mode. For more information about the admin.json file, see AdminHttpApplication(5) in the Configuration Reference.

   The value set in admin.json overrides any value set by the configuration token ig.run.mode when it is used in an environment variable or system property. For information about ig.run.mode, see Configuration Tokens(5) in the Configuration Reference.

2. (Optional) Prevent routes from being reloaded after startup:

   • To prevent all routes in the configuration from being reloaded, add a config.json as described in "Trying IG With a Simple Configuration" in the Getting Started Guide, and configure the scanInterval of the main router.

   • To prevent individual routes from being reloaded, configure the scanInterval of the routers in those routes.

   {
     "type": "Router",
     "config": {
       "scanInterval": "disabled"
     }
   }

   For more information, see Router(5) in the Configuration Reference.

3. Restart IG.

   When IG starts up, the route endpoints are not displayed in the logs, and are not available. You can't access Studio on http://openig.example.com:8080/openig/studio.

This procedure uses StudioProtectionFilter and SingleSignOnFilter to require users to authenticate with AM before they can access Studio. To allow access for specific users only, consider using StudioProtectionFilter with SingleSignOnFilter and PolicyEnforcementFilter.

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide, and access Studio as described in "Accessing Studio" in the Getting Started Guide. IG must be running in development mode.

1. (For AM 6.5.3 and earlier versions) Select  Identities > demo, and set the demo user password to Ch4ng31t.

2. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

   • http://openig.example.com:8080/*

   • http://openig.example.com:8080/*?*

3. (For AM 6.5.3 and later versions) Select Applications > Agents > Identity Gateway, and add an agent with the following values:

   • Agent ID: ig_agent

   • Password: password

   Leave all other values as default.

   (For AM 6.5.2 and earlier versions) Set up an agent as described in "To Set Up a Java Agent in AM".

4. Set an IG environment variable for the Java agent password:

   $ export AGENT_SECRET_ID='cGFzc3dvcmQ='

   The password is retrieved by the default SystemAndEnvSecretStore, and must be base64-encoded.

5. In IG, add the following file as $HOME/.openig/config/admin.json (on Windows, %appdata%\OpenIG\config\admin.json):

   {
     "prefix": "openig",
     "mode": "DEVELOPMENT",
     "properties": {
       "SsoTokenCookieOrHeader": "iPlanetDirectoryPro"
     },
     "heap": [
       {
         "name": "SystemAndEnvSecretStore-1",
         "type": "SystemAndEnvSecretStore"
       },
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "agent" : {
             "username" : "ig_agent",
             "passwordSecretId" : "agent.secret.id"
           },
           "secretsProvider": "SystemAndEnvSecretStore-1",
           "url": "http://openam.example.com:8088/openam/",
           "ssoTokenHeader": "&{SsoTokenCookieOrHeader}",
           "version": "${platform.version}"
         }
       },
       {
         "name": "StudioProtectionFilter",
         "type": "ChainOfFilters",
         "config": {
           "filters": [
             {
               "type": "SingleSignOnFilter",
               "config": {
                 "amService": "AmService-1"
               }
             },
             {
               "type": "CsrfFilter",
               "config": {
                 "cookieName": "&{SsoTokenCookieOrHeader}",
                 "failureHandler": {
                   "type": "StaticResponseHandler",
                   "config": {
                     "status": 403,
                     "headers": {
                       "Content-Type": [
                         "text/plain"
                       ]
                     },
                     "entity": "Request forbidden"
                   }
                 }
               }
             }
           ]
         }
       }
     ]
   }

   Notice the following features of the file:

   • The prefix sets the base of the administrative route to the default value /openig. The Studio endpoint is therefore /openig/studio.

   • The mode is development, so by default the Studio endpoint is open and unfiltered.

   • The SingleSignOnFilter called StudioProtectionFilter in the heap is used by IG to protect access to the Studio endpoint.

     When a request to access Studio doesn't have valid authentication, the SingleSignOnFilter redirects the request to AM for authentication.

   • The AmService in the heap uses the Java agent configured on AM to act on behalf of IG for authentication.

6. Log out of AM, and restart IG.

7. Access Studio on http://openig.example.com:8080/openig/studio.

   The SingleSignOnFilter redirects the request to AM for authentication.

8. Log in to AM with username demo, password Ch4ng31t.

   The Studio welcome page is displayed.

Follow these steps to add an example user to the AM configuration:

1. In the AM console, select the top level realm, and then select Identities.

2. Click Add Identity and add a user with the following values:

   • ID/username: george

   • First name: george

   • Last name: costanza

   • Password: C0stanza

   • Email Address: george@example.com

   • Employee number: 123

Follow these steps to add an AM Java agent that acts on behalf of IG to authenticate with AM, get user profiles, and communicate WebSocket notifications from AM to IG:

1. In the AM console, select the top level realm, and then select select Applications > Agents > Java (or J2EE in earlier versions of AM).

2. Add an agent with the following values:

   • Agent ID: ig_agent

   • Agent URL: http://openig.example.com:8080/agentapp

   • Server URL: http://openam.example.com:8088/openam

   • Password: password

1. Create the following user data in /tmp/userfile:

   username,password,fullname,email
   george,C0stanza,George Costanza,george@example.com
   kramer,N3wman12,Kramer,kramer@example.com
   bjensen,H1falutin,Babs Jensen,bjensen@example.com
   demo,Ch4ng31t,Demo User,demo@example.com
   kvaughan,B5ibery12,Kirsten Vaughan,kvaughan@example.com
   scarter,S9rain12,Sam Carter,scarter@example.com
   

2. Download and unpack the H2 database, and then start H2:

   $ sh /path/to/h2/bin/h2.sh

   H2 starts, listening on port 8082, and opens the H2 Console in a browser.

3. Select the following options in the H2 Console, and then select Connect to access the console:

   • Saved Settings: Generic H2 (Server)

     This option sets the Driver Class, org.h2.Driver, the JDBC URL, jdbc:h2:tcp://localhost/~/test, and the User Name, sa.

   • Password: password

4. In the console, create the user table, using /tmp/userfile:

   DROP TABLE IF EXISTS USERS;
   CREATE TABLE USERS AS SELECT * FROM CSVREAD('/tmp/userfile');

5. Run the following command in the console to check that the table contains the same users as the file:

   SELECT * FROM users;

Follow these steps to enable Jetty to connect to the database:

1. Configure Jetty for JNDI.

   Stop Jetty and add the following lines to start.ini in /path/to/jetty/start.ini to configure Jetty for JNDI:

   # ===========================================================
   # Enable JNDI
   # -----------------------------------------------------------
   OPTIONS=jndi
   
   # ===========================================================
   # Enable additional webapp environment configurators
   # -----------------------------------------------------------
   OPTIONS=plus
   etc/jetty-plus.xml

   For more information, see the Jetty documentation on Configuring JNDI.

2. Copy the H2 library to the classpath for Jetty:

   $ cp /path/to/h2/bin/h2-*.jar /path/to/jetty/lib/ext/

3. Define a JNDI resource for H2 in /path/to/jetty/etc/jetty.xml:

   <New id="jdbc/forgerock" class="org.eclipse.jetty.plus.jndi.Resource">
     <Arg></Arg>
     <Arg>jdbc/forgerock</Arg>
     <Arg>
       <New class="org.h2.jdbcx.JdbcDataSource">
         <Set name="Url">jdbc:h2:tcp://localhost/~/test</Set>
         <Set name="User">sa</Set>
         <Set name="Password">password</Set>
       </New>
     </Arg>
   </New>
   

4. Add a resource reference to the data source in /path/to/jetty/etc/webdefault.xml:

   <resource-ref>
       <res-ref-name>jdbc/forgerock</res-ref-name>
       <res-type>javax.sql.DataSource</res-type>
       <res-auth>Container</res-auth>
   </resource-ref>
   

5. Restart Jetty to take the configuration changes into account.

Add a new route to the IG configuration to look up credentials in the database:

1. Add the following route configuration file as $HOME/.openig/config/routes/03-sql.json:

   {
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "PasswordReplayFilter",
             "config": {
               "loginPage": "${true}",
               "credentials": {
                 "type": "SqlAttributesFilter",
                 "config": {
                   "dataSource": "java:comp/env/jdbc/forgerock",
                   "preparedStatement":
                   "SELECT username, password FROM users WHERE email = ?;",
                   "parameters": [
                     "george@example.com"
                   ],
                   "target": "${attributes.sql}"
                 }
               },
               "request": {
                 "method": "POST",
                 "uri": "http://app.example.com:8081/login",
                 "form": {
                   "username": [
                     "${attributes.sql.USERNAME}"
                   ],
                   "password": [
                     "${attributes.sql.PASSWORD}"
                   ]
                 }
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     },
     "condition": "${matches(request.uri.path, '^/sql')}"
   }
   

   On Windows, add the file as %appdata%\OpenIG\config\routes\03-sql.json.

2. Notice the following features of the route:

   • The route matches requests to /sql.

   • The SqlAttributesFilter in PasswordReplayFilter specifies the data source to access, a prepared statement to look up the user's record, a parameter to pass into the statement, and where to store the search results in the request context attributes map.

   • The request in PasswordReplayFilter retrieves the username and password from the attributes map and replaces the browser's original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate.

     The request is for username, password, but H2 returns the fields as USERNAME and PASSWORD. The configuration reflects this difference.

   • The sample application validates the credentials, and responds with a profile page, which IG then passes to your browser.

Before you start, set up H2, Jetty, and IG as described in the previous procedures, make sure that sample application is running, and log out of AM.

• Access the route on http://openig.example.com:8080/sql.

  IG logs you in to the sample application as George.

Before AM communicates passwords to IG, it encrypts them with a key. IG then uses the key to decrypt the shared passwords.

This example uses DES as the decryption algorithm. For more information about DES shared keys, see DesKeyGenHandler(5) in the Configuration Reference.

The shared key is sensitive information. If it is possible for others to inspect the response, make sure you use HTTPS to protect the communication.

Use this procedure to generate a DES shared key in IG that you can use later in the AM and IG configuration:

1. Add the following route to the IG configuration as $HOME/.openig/config/routes/04-keygen.json. On Windows, add the route as %appdata%\OpenIG\config\routes\04-keygen.json.

   {
     "name": "04-keygen",
     "handler": {
       "type": "DesKeyGenHandler"
     },
     "condition": "${matches(request.uri.path, '^/keygen') and (matches(contexts.client.remoteAddress, ':1') or matches(contexts.client.remoteAddress, '127.0.0.1'))}"
   }
   

2. Call the route to generate a key:

   $ curl http://localhost:8080/keygen
   {"key":"1A+BCdEfGhI="}

   In this example, the key is 1A+BCdEfGhI=.

3. Set an IG environment variable for the key:

   export DESKEY='1A+BCdEfGhI='

   IG uses the default SecretsService to retrieve the value from the environment variable. For more information, see Secrets in the Configuration Reference.

1. (For AM 6.5.3 and earlier versions) Select  Identities > demo, and set the demo user password to Ch4ng31t.

2. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

   • http://openig.example.com:8080/*

   • http://openig.example.com:8080/*?*

3. (For AM 6.5.3 and later versions) Select Applications > Agents > Identity Gateway, and add an agent with the following values:

   • Agent ID: ig_agent

   • Password: password

   Leave all other values as default.

   (For AM 6.5.2 and earlier versions) Set up an agent as described in "To Set Up a Java Agent in AM".

4. Update the Authentication Post Processing Classes for password replay:

   1. Select Authentication > Settings > Post Authentication Processing.

   2. Add the following class to Authentication Post Processing Classes: com.sun.identity.authentication.spi.ReplayPasswd.

5. Add the key you created in "To Create a DES Shared Key In IG" to the AM configuration:

   1. In the AM console, select DEPLOYMENT > Servers, and then select the AM server name. In some earlier releases, select Configuration > Servers and Sites.

   2. Select Advanced, and add the property com.sun.am.replaypasswd.key with the value of the DES shared key.

6. Add sunIdentityUserPassword to the session whitelist, so that the property can be read from the session:

   1. Select Services > Session Property Whitelist Service.

   2. Add sunIdentityUserPassword as a whitelisted session property name.

7. Add example.com as an AM cookie domain:

   1. In AM, select Configure > Global Services > Platform.

   2. Add the domain example.com.

   By default, AM sets host-based cookies. After authentication with AM, requests can be redirected to AM instead of to the resource.

8. Restart AM.

1. Set an environment variable for the Java agent password, and then restart IG:

   $ export AGENT_SECRET_ID='cGFzc3dvcmQ='

   The password is retrieved by the default SystemAndEnvSecretStore, and must be base64-encoded.

2. In IG, add the following route as $HOME/.openig/config/routes/04-replay.json (on Windows, %appdata%\OpenIG\config\routes\04-replay.json).

   {
     "name": "04-replay",
     "condition": "${matches(request.uri.path, '^/replay')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "agent" : {
             "username" : "ig_agent",
             "passwordSecretId" : "agent.secret.id"
           },
           "url": "http://openam.example.com:8088/openam/",
           "version": "6.5"
         }
       },
       {
         "name": "CapturedUserPasswordFilter",
         "type": "CapturedUserPasswordFilter",
         "config": {
           "ssoToken": "${contexts.ssoToken.value}",
           "keySecretId": "DESKEY",
           "amService": "AmService-1"
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "SingleSignOnFilter",
             "config": {
               "amService": "AmService-1"
             }
           },
           {
             "type": "PasswordReplayFilter",
             "config": {
               "loginPage": "${true}",
               "credentials": "CapturedUserPasswordFilter",
               "request": {
                 "method": "POST",
                 "uri": "http://app.example.com:8081/login",
                 "form": {
                   "username": [
                     "${contexts.ssoToken.info.uid}"
                   ],
                   "password": [
                     "${contexts.capturedPassword.value}"
                   ]
                 }
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

3. If necessary, change the value of version for AmService to your version of AM.

4. Notice the following features of the route:

   • The route matches requests to /replay.

   • The first filter in the chain is the SingleSignOnFilter.

     If the request does not have a valid iPlanetDirectoryPro cookie, the SingleSignOnFilter redirects the request to AM for authentication.

     If the request already has a valid iPlanetDirectoryPro cookie, or after authenticating with AM to get a valid iPlanetDirectoryPro cookie, the SingleSignOnFilter passes the request to the next filter. The SingleSignOnFilter stores the cookie value in an SsoTokenContext.

     See SingleSignOnFilter(5) in the Configuration Reference.

   • The next filter in the chain is the PasswordReplayFilter.

     The PasswordReplayFilter uses the CapturedUserPasswordFilter declared in the heap to retrieve the AM password from session properties. The CapturedUserPasswordFilter uses the DES shared key to decrypt the password, and then makes it available in a CapturedUserPasswordContext.

     The PasswordReplayFilter retrieves the username and password from the context. It replaces the browser's original HTTP GET request with an HTTP POST login request containing the credentials to authenticate to the sample application.

     See PasswordReplayFilter(5) in the Configuration Reference and CapturedUserPasswordFilter(5) in the Configuration Reference.

1. Log out of AM if you are logged in.

2. Access the route on http://openig.example.com:8080/replay.

   You should be redirected to the AM login page.

3. Log in with username demo, password Ch4ng31t.

   The request is redirected to the sample application.

1. (For AM 6.5.3 and earlier versions) Select  Identities > demo, and set the demo user password to Ch4ng31t.

2. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

   • http://openig.ext.com:8080/*

   • http://openig.ext.com:8080/*?*

3. In the top-level realm, select Applications > Agents > Java (or J2EE in earlier versions of AM).

4. Add an agent with the following values:

   • Agent ID: ig_agent_cdsso

   • Agent URL: http://openig.ext.com:8080/agentapp

   • Server URL: http://openam.example.com:8088/openam

   • Password: password

5. Select the agent you just created, and on the SSO tab select set the following values:

   • Cross Domain SSO: Deselect this option

   • CDSSO Redirect URI: /home/cdsso/redirect

6. Add example.com as an AM cookie domain:

   1. In AM, select Configure > Global Services > Platform.

   2. Add the domain example.com.

   By default, AM sets host-based cookies. After authentication with AM, requests can be redirected to AM instead of to the resource.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

Before you start, make sure that IG is running in development mode on http://openig.ext.com:8080, the sample application on http://app.example.com:8081, and AM on http://openam.example.com:8088.

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /home/cdsso

   • Name: cdsso

3. Configure authentication:

   1. Select  Authentication.

   2. Select Cross-Domain Single Sign-On, and enter the following information to reflect the configuration in "To Set Up AM for CDSSO", and then save the settings:

      • AM service: Configure an AM service to use for authentication:

        • URI: http://openam.example.com:8088/openam

        • Version: The version of the AM instance, for example, 6.5.

        • Agent: The credentials of the agent you created in AM.

          • Username: ig_agent_cdsso

          • Password: password

      • Redirect endpoint: /home/cdsso/redirect

      • Authentication cookie:

        • Path: /home

      Leave all other values as default.

4. On the top-right of the screen, select  and  Display to review the route.

   The following route should be displayed:

   {
     "name": "cdsso",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/cdsso')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.5",
           "agent": {
             "username": "ig_agent_cdsso",
             "password": "password"
           },
           "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"
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Note

   If necessary, change the value of version for AmService to your version of AM.

5. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. Log out of AM if you are logged in, and clear any cookies.

2. Browse to http://openig.ext.com:8080/home/cdsso.

   The CrossDomainSingleSignOnFilter redirects the request to AM for authentication.

3. Log in to AM as user demo, password Ch4ng31t.

   When you have authenticated, AM calls /home/cdsso/redirect, and includes the CDSSO token.

   The CrossDomainSingleSignOnFilter then passes the request to sample app, which returns the profile page.

Before you start, set up and test one of the previous examples for SSO.

• In the AmService heap object of your route, enable sessionCache:

  "sessionCache": {
    "enabled" : true
  }

Before you start, set up and test one of the previous examples for enforcing policy decisions.

• In the PolicyEnforcementFilter, enable cache:

  "cache": {
    "enabled" : true
  }

Before you start, configure IG and AM:

1. In the AM console, add an environment condition to the policy:

   1. Select a policy set:

      • For SSO, select Authorization > Policy Sets > PEP-SSO.

      • For CDSSO, select Authorization > Policy Sets > PEP-CDSSO.

   2. In the IG policy, select Environments, and add the following environment condition:

      • All of

      • Type: Authentication by Service

      • Authenticate to Service: VerificationCodeLevel1

2. Set up client-side and server-side scripts:

   1. Select Scripts > Scripted Module - Client Side, and replace the default script with one of the following scripts:

      • For AM 6 and later versions, use this script:

        /*
         * Copyright 2018 ForgeRock AS. All Rights Reserved
         *
         * Use of this code requires a commercial software license with ForgeRock AS.
         * or with one of its affiliates. All use shall be exclusively subject
         * to such license between the licensee and ForgeRock AS.
         */
        autoSubmitDelay = 60000;
        
        function callback() {
            var parent = document.createElement("div");
            parent.className = "form-group";
        
            var label = document.createElement("label");
            label.className = "sr-only separator";
            label.setAttribute("for", "answer");
            label.innerText = "Verification Code";
            parent.appendChild(label);
        
            var input = document.createElement("input");
            input.className = "form-control input-lg";
            input.type = "text";
            input.placeholder = "Enter your verification code";
            input.name = "answer";
            input.id = "answer";
            input.value = "";
            input.oninput = function(event) {
                var element = document.getElementById("clientScriptOutputData");
                if (!element.value) element.value = "{}";
                var json = JSON.parse(element.value);
                json["answer"] = event.target.value;
                element.value = JSON.stringify(json);
            };
            parent.appendChild(input);
        
            var fieldset = document.forms[0].getElementsByTagName("fieldset")[0];
            fieldset.prepend(parent);
        }
        
        if (document.readyState !== 'loading') {
            callback();
        } else {
            document.addEventListener("DOMContentLoaded", callback);
        }
        

      • For earlier versions of AM, use this script:

        spinner.hideSpinner();
        autoSubmitDelay = 60000;
        $(document).ready(function() {
          fs = $(document.forms[0]).find("fieldset");
          strUI = '<div class="form-group"> \
                   <label class="sr-only separator" for="answer"> \
                   Verification Code</label><input onchange="s=$(\'#clientScriptOutputData\')[0]; \
                   if (!s.value) s.value=\'{}\'; d=JSON.parse(s.value); d[\'answer\']=value; \
                   s.value=JSON.stringify(d);" id="answer" class="form-control input-lg" type="text" \
                   placeholder="Enter your verification code" value="" name="answer"></input></div>';
          $(fs).prepend(strUI);
        });

      Leave all other values as default.

      This client-side script adds a field to the AM form, in which the user is required to enter a verification code. The script formats the entered code as a JSON object, as required by the server-side script.

   2. Select Scripts > Scripted Module - Server Side, and replace the default script with the following script:

      username = 'demo'
      logger.error('username: ' + username)
      
      // Test whether the user 'demo' enters the correct validation code
      data = JSON.parse(clientScriptOutputData);
      answer = data.answer;
      
      if (answer !== '123456') {
        logger.error('Authentication Failed !!')
        authState = FAILED;
      } else {
        logger.error('Authenticated !!')
        authState = SUCCESS;
      }

      Leave all other values as default.

      This server-side script tests that the user has entered 123456 as the verification code.

3. Add an authentication module:

   1. In the top level realm, select Authentication > Modules, and add a module with the following settings:

      • Name: VerificationCodeLevel1

      • Type: Scripted Module

   2. In the authentication module, enable the option for client-side script, and select the following options:

      • Client-side Script: Scripted Module - Client Side

      • Server-side Script: Scripted Module - Server Side

      • Authentication Level: 1

4. Add the authentication module to an authentication chain:

   1. Select Authentication > Chains, and add a chain called VerificationCodeLevel1.

   2. Add a module with the following settings:

      • Select Module: VerificationCodeLevel1

      • Select Criteria: Required

1. Log out of AM.

2. Access the route:

   • For SSO, browse to http://openig.example.com:8080/home/pep-sso.

   • For CDSSO, browse to http://openig.ext.com:8080/home/pep-cdsso.

   If you have not previously authenticated to AM, the SingleSignOnFilter redirects the request to AM for authentication.

3. Log in to AM as user demo, password Ch4ng31t.

   AM creates a session with the default authentication level 0, and IG requests a policy decision.

   The updated policy requires authentication level 1, which is higher than the session's current authentication level. AM issues a redirect with a AuthenticateToServiceConditionAdvice to authenticate at level 1.

4. In the session upgrade window, enter the verification code 123456.

   AM upgrades the authentication level for the session to 1, and grants access to the sample application. If you try to access the sample application again in the same session, you don't need to provide the verification code.

Before you start, configure AM as described in "To Set Up the Authentication Level for a Session". The IG configuration is not changed.

1. In the AM console, add a new Environment condition:

   1. Select the policy set:

      • For SSO, select Authorization > Policy Sets > PEP-SSO.

      • For CDSSO, select Authorization > Policy Sets > PEP-CDSSO.

   2. In the IG policy, select Environments and add another environment condition:

      • All of

      • Type: Transaction

      • Authentication strategy: Authenticate To Module

      • Strategy specifier: TxVerificationCodeLevel5

2. Set up client-side and server-side scripts:

   1. Select Scripts > New Script, and add the following client-side script:

      • Name: Tx Scripted Module - Client Side

      • Script Type: Client-side Authentication

      /*
       * Copyright 2018 ForgeRock AS. All Rights Reserved
       *
       * Use of this code requires a commercial software license with ForgeRock AS.
       * or with one of its affiliates. All use shall be exclusively subject
       * to such license between the licensee and ForgeRock AS.
       */
      autoSubmitDelay = 60000;
      
      function callback() {
          var parent = document.createElement("div");
          parent.className = "form-group";
      
          var label = document.createElement("label");
          label.className = "sr-only separator";
          label.setAttribute("for", "answer");
          label.innerText = "Verification Code";
          parent.appendChild(label);
      
          var input = document.createElement("input");
          input.className = "form-control input-lg";
          input.type = "text";
          input.placeholder = "Enter your TX code";
          input.name = "answer";
          input.id = "answer";
          input.value = "";
          input.oninput = function(event) {
              var element = document.getElementById("clientScriptOutputData");
              if (!element.value) element.value = "{}";
              var json = JSON.parse(element.value);
              json["answer"] = event.target.value;
              element.value = JSON.stringify(json);
          };
          parent.appendChild(input);
      
          var fieldset = document.forms[0].getElementsByTagName("fieldset")[0];
          fieldset.prepend(parent);
      }
      
      if (document.readyState !== 'loading') {
          callback();
      } else {
          document.addEventListener("DOMContentLoaded", callback);
      }

      This client-side script adds a field to the AM form, in which the user is required to enter a TX code. The script formats the entered code as a JSON object, as required by the server-side script.

   2. Select Scripts > New Script, and add the following server side script:

      • Name: Tx Scripted Module - Server Side

      • Script Type: Server-side Authentication

      username = 'demo'
      logger.error('username: ' + username)
      
      // Test whether the user 'demo' enters the correct validation code
      data = JSON.parse(clientScriptOutputData);
      answer = data.answer;
      
      if (answer !== '789') {
        logger.error('Authentication Failed !!')
        authState = FAILED;
      } else {
        logger.error('Authenticated !!')
        authState = SUCCESS;
      }

      This server-side script tests that the user has entered 789 as the verification code.

3. Add an authentication module:

   1. Select Authentication > Modules, and add a module with the following settings:

      • Name: TxVerificationCodeLevel5

      • Type: Scripted Module

   2. In the authentication module, enable the option for client-side script, and select the following options:

      • Client-side Script: Tx Scripted Module - Client Side

      • Server-side Script: Tx Scripted Module - Server Side

      • Authentication Level: 5

1. Log out of AM.

2. Browse to your route:

   • For SSO, browse to http://openig.example.com:8080/home/pep-sso.

   • For CDSSO, browse to http://openig.ext.com:8080/home/pep-cdsso.

   If you have not previously authenticated to AM, the SingleSignOnFilter redirects the request to AM for authentication.

3. Log in to AM as user demo, password Ch4ng31t.

   AM creates a session with the default authentication level 0, and IG requests a policy decision.

4. Enter the verification code 123456 to upgrade the authorization level for the session to 1.

   The authentication module you configured for transactional authorization requires authentication level 5, so AM issues a TransactionConditionAdvice.

5. In the transaction upgrade window, enter the verification code 789.

   AM upgrades the authentication level for this policy evaluation to 5, and then returns a policy decision that grants a one-time access to the sample application. If you try to access the sample application again, you must enter the code again.

Configure the network so that browser traffic to the application hosts is proxied through IG. The example in this chapter uses the host name sp.example.com.

• Add sp.example.com to your /etc/hosts file:

  127.0.0.1    localhost openam.example.com openig.example.com app.example.com sp.example.com

1. In AM, Select Identities, and add a user with the following values:

   • ID/username: george

   • First name: george

   • Last name: C0stanza

     Note that, for this example, the last name must be the same as the password.

   • Password: C0stanza

2. Set up a hosted IDP:

   1. In the top level realm select Configure SAMLv2 Provider > Create Hosted Identity Provider.

   2. Create an IDP with the following settings, and then select Configure:

      • Name: openam

      • Signing Key: test

      • Circle of Trust: Circle of Trust

      • Attribute Mapping: cn to cn, and sn to sn

        The mapping indicates that IG (the SP) wants AM (the IDP) to get the value of the cn and sn attributes from the user profile and send them to IG. IG can use the attribute values to log the user in to the application it protects. In a real deployment, you would use other attributes.

      A confirmation page is displayed. You can start to create a Fedlet from this page or go back to the top level realm, as described in the following step.

3. Create a fedlet configuration to act as a lightweight SAML v2.0 SP.

   1. In the top level realm, select Create Fedlet Configuration.

   2. Select the following options, and then select Create:

      • Name: sp

      • Destination URL: http://sp.example.com:8080/saml

      • Attribute Mapping: Map cn to cn, and sn to sn.

   The federation configuration files are created in a directory similar to this: $HOME/openam/myfedlets/openig-fedlet/Fedlet.zip. In versions of AM before 13.5, the configuration files are provided in a war directory or .zip file.

   By default, AM as an IDP uses the NameID format urn:oasis:names:tc:SAML:2.0:nameid-format:transient to communicate about a user. For information about using a different NameID format, see "Using a Non-Transient NameID Format".

Before you start, set up AM as described in "To Configure AM as An IDP for SAML 2.0".

1. Retrieve the Fedlet configuration files:

   1. Unpack the fedlet files created in the previous procedure into the IG configuration. For example:

      $ cd $HOME/openam/myfedlets/sp
      $ unzip Fedlet.zip
      $ mkdir $HOME/.openig/SAML
      $ cp conf/* $HOME/.openig/SAML
      $ ls -l $HOME/.openig/SAML
      
      FederationConfig.properties
      fedlet.cot
      idp-extended.xml
      idp.xml
      sp-extended.xml
      sp.xml

   2. If the following header is defined in sp-extended.xml, comment it out to prevent issues with timeout:

      <!--
        <Attribute name="fedletAdapter">
          <Value>com.sun.identity.saml2.plugins.DefaultFedletAdapter</Value>
        </Attribute>
      -->

   3. The SAML library component validates the SP's AssertionConsumerService Location against the incoming IDP SAML Assertion, based on the request information, including the port. In sp.xml, always specify the port in the Location value of AssertionConsumerService, even when using defaults of 443 or 80, as follows:

      <AssertionConsumerService isDefault="true" index="0" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sp.example.com:443/fedletapplication"/>

   4. Restart IG.

2. Add the following route for credential injection as $HOME/.openig/config/routes/05-saml.json (on Windows, %appdata%\OpenIG\config\routes\05-saml.json):

   {
     "handler": {
       "type": "SamlFederationHandler",
       "config": {
         "assertionMapping": {
           "username": "cn",
           "password": "sn"
         },
         "subjectMapping": "sp-subject-name",
         "redirectURI": "/federate"
       }
     },
     "condition": "${matches(request.uri.path, '^/saml')}",
     "session": "JwtSession"
   }
   

   Notice the following features of the route:

   • The route matches requests to /saml.

   • After authentication, the SamlFederationHandler extracts cn and sn from the SAML assertion, and maps them to the session fields session.username and session.password.

   • The handler stores the subject name as a string in the session field session.sp-subject-name, which is named by the subjectMapping property. By default, the subject name is stored in the session field session.subjectName.

   • The handler redirects the request to the /federate route.

   • The route uses the JwtSession implementation, meaning it stores encrypted session information in a browser cookie. The name is a reference to the JwtSession object defined in config.json. For details, see JwtSession(5) in the Configuration Reference.

3. Add the following route for SAML federation as $HOME/.openig/config/routes/05-federate.json (on Windows, %appdata%\OpenIG\config\routes\05-federate.json):

   {
     "handler": {
       "type": "DispatchHandler",
       "config": {
         "bindings": [
           {
             "condition": "${empty session.username}",
             "handler": {
               "type": "StaticResponseHandler",
               "config": {
                 "status": 302,
                 "reason": "Found",
                 "headers": {
                   "Location": [
                     "http://sp.example.com:8080/saml/SPInitiatedSSO"
                   ]
                 }
               }
             }
           },
           {
             "handler": {
               "type": "Chain",
               "config": {
                 "filters": [
                   {
                     "type": "StaticRequestFilter",
                     "config": {
                       "method": "POST",
                       "uri": "http://app.example.com:8081/login",
                       "form": {
                         "username": [
                           "${session.username[0]}"
                         ],
                         "password": [
                           "${session.password[0]}"
                         ]
                       }
                     }
                   }
                 ],
                 "handler": "ReverseProxyHandler"
               }
             }
           }
         ]
       }
     },
     "condition": "${matches(request.uri.path, '^/federate')}",
     "session": "JwtSession"
   }
   

   Notice the following features of the route:

   • The route matches requests to /federate.

   • If the user is not authenticated with AM, the username is not populated in the context. The DispatchHandler then dispatches the request to the StaticResponseHandler, which redirects it to the SP-initiated SSO endpoint.

     If the credentials are in the context, or after successful authentication, the DispatchHandler dispatches the request to the Chain.

   • The StaticRequestFilter retrieves the first value for the username and password attributes of the SAML assertion. It replaces the original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate.

   • The route uses the JwtSession implementation, meaning it stores encrypted session information in a browser cookie. The name is a reference to the JwtSession object defined in config.json. For details, see JwtSession(5) in the Configuration Reference.

   Tip

   For more control over the URL where the user agent is redirected, use the RelayState query string parameter in the URL of the redirect Location header. RelayState specifies where to redirect the user when the SAML 2.0 web browser SSO process is complete. It overrides the redirectURI set in the SamlFederationHandler.

   The RelayState value must be URL-encoded. When using an expression, use a function to encode the value. For example, use ${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}.

   In the following example, the user is finally redirected to the original URI from the request:

   "headers": {
     "Location": [
       "http://openig.example.com:8080/saml/SPInitiatedSSO?RelayState=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}"
     ]
   }

1. Test IDP-initiated SSO:

   1. Log out of AM, and select this link to AM for IDP-initiated SSO.

      Because the user is not authenticated with AM, AM displays its login page.

   2. Log in to AM as user george, password C0stanza.

      After authentication, the request is processed as follows:

      • AM directs the request to the /saml route on IG, providing SAML assertions for the user.

      • The SamlFederationHandler in the /saml route validates the assertion, sets the attributes, and redirects the request to the route.

      • The DispatchHandler in the /federate route directs the request to the StaticRequestFilter.

      • The StaticRequestFilter retrieves the credentials and replaces the original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate to the protected application.

      • IG returns the response page showing that the user has logged in.

2. Test SP-initiated SSO:

   1. Log out of AM, and browse to http://openig.example.com:8080/federate.

      Because the user is not authenticated, the session username is not populated in the context. The DispatchHandler in the /federate route directs the request to AM for SP-initiated SSO.

   2. Log in to AM as user george, password C0stanza.

      After authentication, the request is processed as follows:

      • AM directs the request to the /saml route on IG, providing SAML assertions for the user.

      • The SamlFederationHandler in the /saml route validates the assertion, sets the attributes, and redirects the request to the route.

      • The DispatchHandler in the /federate route directs the request to the StaticRequestFilter.

      • The StaticRequestFilter retrieves the credentials and replaces the original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate to the protected application.

      • IG returns the response page showing that the user has logged in.

Before you start, install and configure AM on http://openam.example.com:8088/openam, with the default configuration. If you use a different configuration, substitute in the tutorial accordingly.

For more information about configuring AM as an OAuth 2.0 authorization service, see Configuring the OAuth 2.0 Authorization Service in the AM OAuth 2.0 Guide.

1. In AM, add a Java agent as described in "To Set Up a Java Agent in AM".

2. Add a user as described in "To Set Up a Sample User In AM".

3. Configure an OAuth 2.0 Authorization Server:

   1. In the top level realm, select Configure OAuth Provider > Configure OAuth 2.0.

   2. Accept all of the default values and select Create.

4. Create an OAuth2 Client to request OAuth 2.0 access_tokens:

   1. Select Applications > OAuth 2.0.

   2. Add a client with the following values:

      • Client ID: client-application

      • Client secret: password

      • Scope(s): mail, employeenumber

   3. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Resource Owner Password Credentials

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide, and access Studio as described in "Accessing Studio" in the Getting Started Guide. IG must be running in development mode.

To configure IG without using Studio, add the route in the following procedure as $HOME/.openig/config/routes/rs-tokeninfo.json (on Windows, %appdata%\OpenIG\config\routes\rs-tokeninfo.json).

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /rs-tokeninfo

   • Name: rs-tokeninfo

3. Configure authorization:

   1. Select  Authorization.

   2. Select OAuth 2.0 Resource Server, and enter the following information to reflect the configuration in AM:

      • Token resolver configuration:

        • Access token resolver: AM token info endpoint

        • AM service:

          • URI: http://openam.example.com:8088/openam

          • Version: The version of the AM instance, for example, 6.5.

          • Agent: The credentials of the Java agent you created in AM.

            • Username: ig_agent

            • Password: password

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

      Leave all other values as default.

4. Add a StaticResponseHandler:

   1. On the top-right of the screen, select  and  Editor mode to switch into editor mode.

      Warning

      After switching to Editor mode, you cannot go back. You will be able to use the JSON file editor to manually edit the route, but will no longer be able use the full Studio interface to add or edit filters.

   2. Replace the last ReverseProxyHandler in the route with the following StaticResponseHandler, and then save the route:

      "handler": {
        "type": "StaticResponseHandler",
        "config": {
         "status": 200,
         "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }

5. On the top-right of the screen, select  and  Display to review the route.

   Make sure that the following route is displayed:

   {
     "name": "rs-tokeninfo",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/rs-tokeninfo')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.5",
           "agent": {
             "username": "ig_agent",
             "password": "password"
           },
           "sessionCache": {
             "enabled": false
           }
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ResourceServerFilter-1",
             "type": "OAuth2ResourceServerFilter",
             "config": {
               "scopes": [
                 "mail",
                 "employeenumber"
               ],
               "requireHttps": false,
               "realm": "OpenIG",
               "accessTokenResolver": {
                 "name": "token-resolver-1",
                 "type": "OpenAmAccessTokenResolver",
                 "config": {
                   "amService": "AmService-1"
                 }
               }
             }
           }
         ],
         "handler": {
           "type": "StaticResponseHandler",
           "config": {
             "status": 200,
             "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
           }
         }
       }
     }
   }

   Note

   If necessary, change the value of version for AmService to your version of AM.

   Notice the following features of the route:

   • The route matches requests to /rs-tokeninfo.

   • The OAuth2ResourceServerFilter expects an OAuth 2.0 access_token in the header of the incoming authorization request, with the scopes mail and employeenumber.

     The accessTokenResolver uses the AM server declared in the heap. The token info endpoint to validate the access token is extrapolated from the URL of the AM server.

     For convenience in this test, "requireHttps" is false. In production environments, set it to true.

   • After the filter successfully validates the access_token, it creates a new context from the authorization server response. The context is named oauth2, and can be reached at contexts.oauth2 or contexts['oauth2'].

     The context contains information about the access_token, which can be reached at contexts.oauth2.accessToken.info. Filters and handlers further down the chain can access the token info through the context. For an example that uses the scopes email and employeenumber to log the user in to the sample application, see "Using the OAuth 2.0 Context to Log In To the Sample Application".

     If there is no access_token in the request, or token validation does not complete successfully, the filter returns an HTTP error status to the user-agent, and IG does not continue processing the request. This is done as specified in the RFC, OAuth 2.0 Bearer Token Usage.

   • The StaticResponseHandler returns the content of the access_token from the context ${contexts.oauth2.accessToken.info}.

6. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

The following configuration gets an access_token from AM and use it to access IG, which then uses the OAuth 2.0 resource owner password credentials authorization grant.

1. In a terminal window, use a curl command similar to the following to retrieve an access_token:

   $ mytoken=$(curl -s \
   --user "client-application:password" \
   --data "grant_type=password&username=george&password=C0stanza&scope=mail%20employeenumber" \
   http://openam.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

2. Validate the access_token returned in the previous step:

   $ curl -v http://openig.example.com:8080/rs-tokeninfo --header "Authorization: Bearer ${mytoken}"
   
   {
     access_token=gofyKg3ulxhEMfiFQ3H-0CBsoXc,
     employeenumber=123,
     mail=george@example.com,
     grant_type=password,
     auth_level=0,
     scope=[employeenumber, mail],
     realm=/,
     token_type=Bearer,
     expires_in=3548,
     client_id=client-application
   }

   Note that the token info endpoint returns the scopes, employeenumber and mail.

Before you start, install and configure AM on http://openam.example.com:8088/openam, with the default configuration. If you use a different configuration, substitute in the tutorial accordingly.

For more information about configuring AM as an OAuth 2.0 authorization service, see Configuring the OAuth 2.0 Authorization Service in the AM OAuth 2.0 Guide.

1. Add a user as described in "To Set Up a Sample User In AM".

2. Configure an OAuth 2.0 Authorization Server:

   1. In the top level realm, select Configure OAuth Provider > Configure OAuth 2.0.

   2. Accept all of the default values and select Create.

3. Create an OAuth2 Client to request OAuth 2.0 access_tokens:

   1. Select Applications > OAuth 2.0.

   2. Add a client with the following values:

      • Client ID: client-application

      • Client secret: password

      • Scope(s): mail, employeenumber

   3. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Resource Owner Password Credentials

4. Create an OAuth2 Client authorized to examine (introspect) tokens:

   1. In the top level realm, select Applications > OAuth 2.0.

   2. Add a client with the following values:

      • Client ID: resource-server

      • Client secret password

      • Scope(s): am-introspect-all-tokens

   3. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Resource Owner Password Credentials

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide, and access Studio as described in "Accessing Studio" in the Getting Started Guide. IG must be running in development mode.

To configure IG without using Studio, add the route in the following procedure to the IG configuration as $HOME/.openig/config/routes/rs-introspect.json (on Windows, %appdata%\OpenIG\config\routes\rs-introspect.json).

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /rs-introspect

   • Name: rs-introspect

3. Configure authorization:

   1. Select  Authorization.

   2. Select OAuth 2.0 Resource Server, and enter the following information to reflect the configuration in AM:

      • Token resolver configuration:

        • Access token resolver: OAuth 2.0 introspection endpoint

        • Introspection endpoint URI: http://openam.example.com:8088/openam/oauth2/introspect

        • Client name and Client secret: resource-server and password

          This is the name and password of the OAuth 2.0 client with the scope to examine (introspect) tokens, configured in AM.

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

      Leave all other values as default.

4. Add a StaticResponseHandler:

   1. On the top-right of the screen, select  and  Editor mode to switch into editor mode.

      Warning

      After switching to Editor mode, you cannot go back. You will be able to use the JSON file editor to manually edit the route, but will no longer be able use the full Studio interface to add or edit filters.

   2. Replace the last ReverseProxyHandler in the route with the following StaticResponseHandler, and then save the route:

      "handler": {
        "type": "StaticResponseHandler",
        "config": {
         "status": 200,
         "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }

5. On the top-right of the screen, select  and  Display to review the route.

   Make sure that the following route is displayed:

   {
     "name": "rs-introspect",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/rs-introspect')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ResourceServerFilter-1",
             "type": "OAuth2ResourceServerFilter",
             "config": {
               "scopes": [
                 "mail",
                 "employeenumber"
               ],
               "requireHttps": false,
               "realm": "OpenIG",
               "accessTokenResolver": {
                 "name": "token-resolver-1",
                 "type": "TokenIntrospectionAccessTokenResolver",
                 "config": {
                   "endpoint": "http://openam.example.com:8088/openam/oauth2/introspect",
                   "providerHandler": {
                     "type": "Chain",
                     "config": {
                       "filters": [
                         {
                           "type": "HeaderFilter",
                           "config": {
                             "messageType": "request",
                             "add": {
                               "Authorization": [
                                 "Basic ${encodeBase64('resource-server:password')}"
                               ]
                             }
                           }
                         }
                       ],
                       "handler": "ForgeRockClientHandler"
                     }
                   }
                 }
               }
             }
           }
         ],
         "handler": {
           "type": "StaticResponseHandler",
           "config": {
             "status": 200,
             "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
           }
         }
       }
     }
   }

   Notice the following features of the route compared to rs-tokeninfo.json:

   • The route matches requests to /rs-introspect.

   • The accessTokenResolver uses the token introspection endpoint to validate the access_token.

   • The providerHandler is a chain that adds an authorization header to the request. The header contains the username and password of the OAuth 2.0 client with the scope to examine (introspect) access_tokens.

6. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

The following configuration gets an access_token from AM and use it to access IG, which then uses the OAuth 2.0 resource owner password credentials authorization grant.

1. In a terminal window, use a curl command similar to the following to retrieve an access_token:

   $ mytoken=$(curl -s \
   --user "client-application:password" \
   --data "grant_type=password&username=george&password=C0stanza&scope=mail%20employeenumber" \
   http://openam.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

2. Validate the access_token returned in the previous step:

   $ curl -v http://openig.example.com:8080/rs-introspect --header "Authorization: Bearer ${mytoken}"
        
   {
     ...
     active=true,
     scope=employeenumber mail,
     client_id=client-application,
     user_id=george,
     token_type=access_token,
     exp=1534867911,
     sub=george,
     iss=http://openam.example.com:8088/openam/oauth2, auth_level=0
    ...
   }

   Note that the token introspection endpoint returns different information than the token info endpoint.

Before you start, run the example in "To Set Up IG As a Resource Server Using the Token Info Endpoint".

1. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

   • http://openig.example.com:8080/*

   • http://openig.example.com:8080/*?*

2. Edit the user created in "To Set Up a Sample User In AM", to set:

   • Email address: george

   • Employee number: C0stanza

   The IG route in this procedure assigns the value of mail as the username, and employeenumber as the password to log in to the sample application.

3. Edit the route, rs-tokeninfo.json, created in "To Set Up IG As a Resource Server Using the Token Info Endpoint":

   • Remove the StaticResponseHandler.

   • Add an AssignmentFilter to access the token info through the context, and inject the username and password into session.

   • Add a StaticRequestFilter to retrieve the username and password from session, and replace the original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate.

   • Add a ReverseProxyHandler to submit the request to the sample application.

   An example route with a different name and condition is as follows:

   {
     "name" : "rs-pwreplay",
     "baseURI" : "http://app.example.com:8081",
     "condition" : "${matches(request.uri.path, '^/rs-pwreplay')}",
     "heap" : [ {
       "name" : "AmService-1",
       "type" : "AmService",
       "config" : {
         "url" : "http://openam.example.com:8088/openam",
         "realm" : "/",
         "ssoTokenHeader" : "iPlanetDirectoryPro",
         "version": "6.5",
         "agent": {
           "username": "ig_agent",
           "password": "password"
         },
         "sessionCache": {
           "enabled": false
         }
       }
     } ],
     "handler" : {
       "type" : "Chain",
       "config" : {
         "filters" : [ {
           "name" : "OAuth2ResourceServerFilter-1",
           "type" : "OAuth2ResourceServerFilter",
           "config" : {
             "scopes" : [ "mail", "employeenumber" ],
             "requireHttps" : false,
             "realm" : "OpenIG",
             "accessTokenResolver" : {
               "name" : "token-resolver-1",
               "type" : "OpenAmAccessTokenResolver",
               "config" : {
                 "amService" : "AmService-1"
               }
             }
           }
         },
           {
             "type": "AssignmentFilter",
             "config": {
               "onRequest": [{
                 "target": "${session.username}",
                 "value": "${contexts.oauth2.accessToken.info.mail}"
               },
                 {
                   "target": "${session.password}",
                   "value": "${contexts.oauth2.accessToken.info.employeenumber}"
                 }
               ]
             }
           },
           {
             "type": "StaticRequestFilter",
             "config": {
               "method": "POST",
               "uri": "http://app.example.com:8081/login",
               "form": {
                 "username": [
                   "${session.username}"
                 ],
                 "password": [
                   "${session.password}"
                 ]
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Note

   If necessary, change the value of version for AmService to your version of AM.

4. In a terminal window, use a curl command similar to the following to retrieve an access_token:

   $ mytoken=$(curl -s \
   --user "client-application:password" \
   --data "grant_type=password&username=george&password=C0stanza&scope=mail%20employeenumber" \
   http://openam.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

5. Validate the access_token returned in the previous step:

   $ curl -v http://openig.example.com:8080/rs-pwreplay --header "Authorization: Bearer ${mytoken}"

   HTML for the sample application is displayed.

Before you start, install and configure AM on http://openam.example.com:8088/openam, with the default configuration. If you use a different configuration, substitute in the tutorial accordingly.

1. In AM, add a user as described in "To Set Up a Sample User In AM".

2. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

   • http://openig.example.com:8080/*

   • http://openig.example.com:8080/*?*

3. Configure an OAuth 2.0 Authorization Server and OpenID Connect Provider.

   1. In the top level realm, select Configure OAuth Provider > Configure OpenID Connect.

   2. Accept all of the default values and select Create.

4. Create an OAuth 2.0 Client to enable IG to communicate as an OAuth 2.0 relying party with AM.

   1. Select Applications > OAuth 2.0.

   2. Add a client with the following values:

      • Client ID: oidc_client

      • Client secret: password

      • Redirection URIs: http://openig.example.com:8080/home/id_token/callback

      • Scope(s): openid, profile, and email.

   3. (From AM 6.5) On the Advanced tab, select the following options:

      • Grant Types: Authorization Code and Resource Owner Password Credentials

   4. On the Signing and Encryption tab, change ID Token Signing Algorithm to HS256, HS384, or HS512.

      The algorithm must be HMAC.

5. Log out of AM.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /home/id_token

   • Name: 07-openid

3. Configure authentication:

   1. Select  Authentication.

   2. Select OpenID Connect, and then select the following options to reflect the configuration in " To Set Up AM as an OpenID Connect Provider ":

      • Client Filter:

        • Client Endpoint: /home/id_token

        • Require HTTPS: Deselect this option

      • Client Registration:

        • Client ID: oidc_client

        • Client secret: password

        • Scopes: openid, profile, and email

        • Basic authentication: Select this option

      • Issuer:

        • Well-known Endpoint: http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration

      Leave all other values as default.

4. On the top-right of the screen, select  and  Display to review the route.

   The following route should be displayed:

   {
     "name": "07-openid",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/id_token')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ClientFilter-1",
             "type": "OAuth2ClientFilter",
             "config": {
               "clientEndpoint": "/home/id_token",
               "failureHandler": {
                 "type": "StaticResponseHandler",
                 "config": {
                   "status": 500,
                   "headers": {
                     "Content-Type": [
                       "text/plain"
                     ]
                   },
                   "entity": "An error occurred during the OAuth2 setup."
                 }
               },
               "registrations": [
                 {
                   "name": "oidc-user-info-client",
                   "type": "ClientRegistration",
                   "config": {
                     "clientId": "oidc_client",
                     "clientSecret": "password",
                     "issuer": {
                       "name": "Issuer",
                       "type": "Issuer",
                       "config": {
                         "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
                       }
                     },
                     "scopes": [
                       "openid",
                       "profile",
                       "email"
                     ],
                     "tokenEndpointAuthMethod": "client_secret_basic"
                   }
                 }
               ],
               "requireHttps": false,
               "cacheExpiration": "disabled"
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Notice the following features about the route:

   • The route matches requests to /home/id_token.

   • The OAuth2ClientFilter enables IG to act as a relying party. It uses a single client registration that is defined inline and refers to the AM server configured in " Setting Up AM for OpenID Connect ".

   • The filter has a base client endpoint of /home/id_token, which creates the following service URIs:

     • Requests to /home/id_token/login start the delegated authorization process.

     • Requests to /home/id_token/callback are expected as redirects from the OAuth 2.0 Authorization Server (OpenID Connect provider). This is why the redirect URI in the client profile in AM is set to http://openig.example.com:8080/home/id_token/callback.

     • Requests to /home/id_token/logout remove the authorization state for the end user, and redirect to the specified URL if a goto parameter is provided.

     These endpoints are implicitly reserved. Attempts to access them directly can cause undefined errors.

   • For convenience in this test, "requireHttps" is false. In production environments, set it to true. So that you see the delegated authorization process when you make a request, "requireLogin" has the default value true.

   • The target for storing authorization state information is ${attributes.openid}. This is where subsequent filters and handlers can find access tokens and user information.

5. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. Log out of AM.

2. Browse to http://openig.example.com:8080/home/id_token.

   The AM login page is displayed.

3. Log in as user george, password C0stanza, and then allow the application to access user information.

   The home page of the sample application is displayed.

   What's happening behind the scenes?

   • When IG gets the browser request, the OAuth2ClientFilter redirects you to authenticate with AM and authorize access to user information. AM then returns an access token to the filter.

   • The OAuth2ClientFilter uses the access token to get the user information, and then injects the authorization state information into attributes.openid.

   • The ReverseProxyHandler redirects the request to the home page of the sample application.

Before you start, set up AM as described in " Setting Up AM for OpenID Connect ".

1. Select the user george, and change the last name to C0stanza. Note that, for this example, the last name must be the same as the password.

2. Select Services > OAuth2 Provider.

3. On the Client Dynamic Registration tab, enable Allow Open Dynamic Client Registration. In earlier versions of AM, this option is in Advanced OpenID Connect.

1. Add the following route to the IG configuration as $HOME/.openig/config/routes/07-discovery.json (on Windows, %appdata%\OpenIG\config\routes\07-discovery.json):

   {
     "heap": [
       {
         "name": "DiscoveryPage",
         "type": "StaticResponseHandler",
         "config": {
           "status": 200,
           "reason": "OK",
           "entity": "
             <!doctype html>
             <html>
             <head>
               <title>OpenID Connect Discovery</title>
               <meta charset='UTF-8'>
             </head>
             <body>
               <form id='form' action='/discovery/login?'>
                 Enter your user ID or email address:
               <input type='text' id='discovery' name='discovery'
                      placeholder='george or george@example.com' />
               <input type='hidden' name='goto'
                      value='${contexts.router.originalUri}' />
               </form>
               <script>
               // The sample application handles the WebFinger request,
               // so make sure the request is sent to the sample app.
               window.onload = function() {
                 document.getElementById('form').onsubmit = function() {
                   // Fix the URL if not using the default settings.
                   var sampleAppUrl = 'http://app.example.com:8081/';
                   var discovery = document.getElementById('discovery');
                   discovery.value = sampleAppUrl + discovery.value.split('@', 1)[0];
                 };
               };
               </script>
             </body>
           </html>"
         }
       }
     ],
     "name": "07-discovery",
     "condition": "${matches(request.uri.path, '^/discovery')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "DynamicallyRegisteredClient",
             "type": "OAuth2ClientFilter",
             "config": {
               "clientEndpoint": "/discovery",
               "requireHttps": false,
               "requireLogin": true,
               "target": "${attributes.openid}",
               "failureHandler": {
                 "type": "StaticResponseHandler",
                 "config": {
                   "comment": "Trivial failure handler for debugging only",
                   "status": 500,
                   "reason": "Error",
                   "entity": "${attributes.openid}"
                 }
               },
               "loginHandler": "DiscoveryPage",
               "metadata": {
                 "client_name": "My Dynamically Registered Client",
                 "redirect_uris": [
                   "http://openig.example.com:8080/discovery/callback"
                 ],
                 "_scope": "openid profile email",
                 "scopes": [
                   "openid",
                   "profile",
                   "email"
                 ]
               }
             }
           },
           {
             "type": "StaticRequestFilter",
             "config": {
               "method": "POST",
               "uri": "http://app.example.com:8081/login",
               "form": {
                 "username": [
                   "${attributes.openid.user_info.sub}"
                 ],
                 "password": [
                   "${attributes.openid.user_info.family_name}"
                 ]
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }
   

2. Consider the differences with 07-openid.json:

   • The route matches requests to /discovery.

   • The StaticResponseHandler, DiscoveryPage, is used as a login handler for the client filter (there is no issuer or client registration), and serves an HTML page that provides the following information to IG:

     • The value of a discovery parameter.

       IG uses the value to perform OpenID Connect discovery. Examples from the specification include acct:joe@example.com, https://example.com:8080/, and https://example.com/joe. First, IG extracts the domain host and port from the value, and attempts to find a match in the supportedDomains lists for any issuers that are already configured for the route. If it finds a match, then it can potentially use the issuer's registration end point and avoid an additional request to look up the user's issuer using the WebFinger protocol. If there is no match in the supported domains lists, IG uses the discovery value as the resource for a WebFinger request according to the OpenID Connect Discovery protocol.

       On success, IG has either found an appropriate issuer in the configuration, or found the issuer using the WebFinger protocol. IG can thus proceed to dynamic client registration.

       The small JavaScript function in the HTML page transforms user input into a useful discovery value for IG. This is not a requirement for deployment, only a convenience for the purposes of this example. Alternatives are described in the discovery protocol specification.

     • The value of a goto parameter.

       The goto parameter takes a URI that tells IG where to redirect the end user's browser once the process is complete and IG has injected the OpenID Connect user information into the context. In this case, the user is redirected back to this route so that the innermost chain of the configuration can log the user in to the protected application.

   • The OAuth2ClientFilter specifies the following configuration:

     • Login handler to point to the login page described above.

     • Metadata that IG uses to prepare the dynamic registration request, including:

       • Client name

       • Redirection URIs

         As set out in RFCs for OAuth2 and OpenID, redirection URIs are mandatory. One of the registered redirection URI values must exactly match the clientEndpoint/callback URI.

       • Scopes:

         • Use scope for dynamic client registration with AM 5.5 and later versions, or with identity providers that support RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol.

         • Use scopes for dynamic client registration with all AM versions.

         • Use both scope and scopes to dynamically register with a wider range of identity providers.

1. Log out of AM.

2. Browse to http://openig.example.com:8080/discovery.

3. Enter the following email address: george@example.com.

   The AM login page is displayed.

4. Log in as user george, password C0stanza, and then allow the application to access user information.

   If successful, IG logs you in to the sample application as George Costanza, and the sample application returns George's page.

   What is happening behind the scenes?

   After IG gets the browser request, it returns the example page for discovery. You provide a user ID or email address, and the page transforms that into a discovery value. The value is tailored to let IG use the sample application as a WebFinger server. (The WebFinger server is more likely to be a service on the issuer's domain, not part of the protected application. For the purposes of this tutorial the WebFinger service has been embedded in the sample application to avoid leaving you with another server to manage during the tutorial.)

   IG learns from the WebFinger service that AM is the issuer for the user. IG retrieves the OpenID Provider configuration from AM, and registers itself dynamically with AM, using the redirection URIs and scopes specified in the OAuth 2.0 client filter configuration.

   Once the issuer and client registration are properly configured, the OAuth 2.0 client filter redirects the browser to AM for authentication and authorization to access to the user information. The rest is the same as the previous tutorial in this chapter. For details, see "Testing the Setup".

   IG reuses issuer and client registration configurations that it builds after discovery and dynamic registration. These dynamically generated configuration objects are held in memory, and do not persist when IG is restarted.

1. Set up AM as described in " Setting Up AM for OpenID Connect ". IG authenticates with AM and retrieves an OpenID Connect ID token (id_token) to be transformed by STS.

2. Add a Java agent as described in "To Set Up a Java Agent in AM".

3. Create a Bearer Module:

   1. In the top level realm, select Authentication > Modules.

   2. Add a module with the following values:

      • Module name: oidc

      • Type: OpenID Connect id_token bearer

   3. In the configuration page, enter the following values:

      • OpenID Connect validation configuration type: Client Secret

      • OpenID Connect validation configuration value: password

        This is the password of the OAuth 2.0/OpenID Connect client.

      • Client Secret: password

      • Name of OpenID Connect ID Token Issuer: http://openam.example.com:8088/openam/oauth2

      • Audience name: oidc_client

        This is the name of the OAuth 2.0/OpenID Connect client.

      • List of accepted authorized parties: oidc_client

      Leave all other values as default, and save your settings.

4. Create an instance of STS REST.

   1. In the top level realm, select STS.

   2. Add a Rest STS instance with the following values, and then select Create:

      • Deployment Url Element: openig

        This value identifies the STS instance and is used by the instance parameter in the TokenTransformationFilter.

      • SAML2 TOKEN

        • SAML2 issuer Id: OpenAM

        • Service Provider Entity Id: openig_sp

        • NameIdFormat: Select urn:oasis:names:tc:SAML:2.0:nameid-format:transient

        Note

        For STS, it isn't necessary to create a SAML SP configuration in AM.

      • OPENID CONNECT TOKEN

        • OpenIdConnect Token Provider Issuer Id: oidc

        • Token signature algorithm: Enter a value that is consistent with " To Set Up AM as an OpenID Connect Provider ", for example, HMAC SHA 256

        • Client Secret (for HMAC-signed-tokens): password

        • Issued Tokens Audience: oidc_client

   3. Select the SAML2 Token tab, add the following values, and then save your changes:

      • Attribute Mappings: Add password=mail and userName=uid

5. Log out of AM.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide, and access Studio as described in "Accessing Studio" in the Getting Started Guide. IG must be running in development mode.

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /home/id_token

   • Name: 50-idtoken

3. Configure authentication:

   1. Select  Authentication.

   2. Select OpenID Connect, and enter the following information:

      • Client Filter:

        • Client Endpoint: /home/id_token

        • Require HTTPS: Deselect this option

      • Client Registration:

        • Client ID: oidc_client

        • Client secret: password

        • Scopes: openid, profile, and email

        • Basic authentication: Select this option

      • Issuer:

        • Well-known endpoint: http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration

      Leave all other values as default, and save your settings.

4. Set up token transformation:

   1. Select  Token transformation, and then enable it.

   2. Enter the following information:

      • AM service: Configure an AM service to use for authentication and REST STS requests.

        • URI: http://openam.example.com:8088/openam

        • Version: The version of the AM instance, for example, 6.5.

        • Agent: The credentials of the agent you created in AM.

          • Username: ig_agent

          • Password: password

      • Username: oidc_client

      • Password: password

      • id_token: ${attributes.openid.id_token}

      • Instance: openig

5. Add a StaticResponseHandler:

   1. On the top-right of the screen, select  and  Editor mode to switch into editor mode.

      Warning

      After switching to Editor mode, you cannot go back. You will be able to use the JSON file editor to manually edit the route, but will no longer be able use the full Studio interface to add or edit filters.

   2. Replace the last ReverseProxyHandler in the route with the following StaticResponseHandler, and then save the route:

      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "entity": "{\"id_token\":\n\"${attributes.openid.id_token}\"} \n\n\n{\"saml_assertions\":\n\"${contexts.sts.issuedToken}\"}",
           "reason": "Found",
           "status": 200
        }
      }

6. On the top-right of the screen, select  and  Display to review the route.

   Make sure that the following route is displayed:

   {
     "name": "50-idtoken",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/id_token')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.5",
           "agent": {
             "username": "ig_agent",
             "password": "password"
           },
           "sessionCache": {
             "enabled": false
           }
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ClientFilter-1",
             "type": "OAuth2ClientFilter",
             "config": {
               "clientEndpoint": "/home/id_token",
               "failureHandler": {
                 "type": "StaticResponseHandler",
                 "config": {
                   "status": 500,
                   "headers": {
                     "Content-Type": [
                       "text/plain"
                     ]
                   },
                   "entity": "An error occurred during the OAuth2 setup."
                 }
               },
               "registrations": [
                 {
                   "name": "oidc-user-info-client",
                   "type": "ClientRegistration",
                   "config": {
                     "clientId": "oidc_client",
                     "clientSecret": "password",
                     "issuer": {
                       "name": "Issuer",
                       "type": "Issuer",
                       "config": {
                         "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
                       }
                     },
                     "scopes": [
                       "openid",
                       "profile",
                       "email"
                     ],
                     "tokenEndpointAuthMethod": "client_secret_basic"
                   }
                 }
               ],
               "requireHttps": false,
               "cacheExpiration": "disabled"
             }
           },
           {
             "name": "TokenTransformationFilter-1",
             "type": "TokenTransformationFilter",
             "config": {
               "username": "oidc_client",
               "password": "password",
               "idToken": "${attributes.openid.id_token}",
               "instance": "openig",
               "amService": "AmService-1"
             }
           }
         ],
         "handler": {
           "type": "StaticResponseHandler",
           "config": {
             "entity": "{\"id_token\":\n\"${attributes.openid.id_token}\"} \n\n\n{\"saml_assertions\":\n\"${contexts.sts.issuedToken}\"}",
             "reason": "Found",
             "status": 200
           }
         }
       }
     }
   }

   Note

   If necessary, change the value of version for AmService to your version of AM.

   Notice the following features of the route:

   • The route matches requests to /home/id_token.

   • The AmService in the heap is used for authentication and REST STS requests.

   • The OAuth2ClientFilter enables IG to act as an OpenID Connect relying party:

     • The client endpoint is set to /home/id_token, so the service URIs for this filter on the IG server are /home/id_token/login, /home/id_token/logout, and /home/id_token/callback.

     • For convenience in this test, requireHttps is false. In production environments, set it to true. So that you see the delegated authorization process when you make a request, requireLogin is true.

     • The target for storing authorization state information is ${attributes.openid}. Subsequent filters and handlers can find access tokens and user information at this target.

   • The ClientRegistration holds configuration provided in " Setting Up AM for OpenID Connect ", and used by IG to connect with AM.

   • The TokenTransformationFilter transforms an id_token into a SAML assertion:

     • The id_token parameter defines where this filter gets the id_token created by the OAuth2ClientFilter.

       The TokenTransformationFilter makes the result of the token transformation available to downstream handlers in the issuedToken property of the ${contexts.sts} context.

     • The instance parameter must match the Deployment URL Element for the REST STS instance.

     Errors that occur during token transformation cause an error response to be returned to the client and an error message to be logged for the IG administrator.

   • When the request succeeds, a StaticResponseHandler retrieves and displays the id_token from the target {attributes.openid.id_token}.

7. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. Browse to http://openig.example.com:8080/home/id_token.

   The AM login screen is displayed.

2. Log in to AM as user george, password C0stanza.

   An OpenID Connect request to access private information is displayed.

3. Select Allow.

   The id_token and SAML assertions are displayed:

   {"id_token": "eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAiYXRfaGFzaCI6ICJ . . ."}
       
   {"saml_assertions":
   <"saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version= . . ."}

For information about CORS support, see the AM product documentation. This procedure describes how to modify the AM configuration to allow cross-site access.

1. In the WEB-INF/web.xml file of AM, edit the URL pattern for CORSFilter to match all endpoints:

   <filter-mapping>
       <filter-name>CORSFilter</filter-name>
       <url-pattern>/*</url-pattern>
   </filter-mapping>

2. In the same file, edit the CORSFilter configuration to authorize cross-site access for origins, hosts, and headers, as shown in the following excerpt:

   <filter>
       <filter-name>CORSFilter</filter-name>
       <filter-class>org.forgerock.openam.cors.CORSFilter</filter-class>
       <init-param>
           <description>
               Accepted Methods (Required):
               A comma separated list of HTTP methods for which to accept CORS requests.
           </description>
           <param-name>methods</param-name>
           <param-value>POST,GET,PUT,DELETE,PATCH,OPTIONS</param-value>
       </init-param>
       <init-param>
           <description>
               Accepted Origins (Required):
               A comma separated list of origins from which to accept CORS requests.
           </description>
           <param-name>origins</param-name>
           <param-value>http://app.example.com:8081,http://openig.example.com:8080,http://openam.example.com:8088</param-value>
       </init-param>
       <init-param>
           <description>
               Allow Credentials (Optional):
               Whether to include the Vary (Origin)
               and Access-Control-Allow-Credentials headers in the response.
               Default: false
           </description>
           <param-name>allowCredentials</param-name>
           <param-value>true</param-value>
       </init-param>
       <init-param>
           <description>
               Allowed Headers (Optional):
               A comma separated list of HTTP headers
               which can be included in the requests.
           </description>
           <param-name>headers</param-name>
           <param-value>
             Authorization,Content-Type,iPlanetDirectoryPro,X-OpenAM-Username,X-OpenAM-Password,Accept,Accept-Encoding,Connection,Content-Length,Host,Origin,User-Agent,Accept-Language,Referer,Dnt,Accept-Api-Version,If-None-Match,Cookie,X-Requested-With,Cache-Control,X-Password,X-Username,X-NoSession
           </param-value>
       </init-param>
       <init-param>
           <description>
               Expected Hostname (Optional):
               The name of the host expected in the request Host header.
           </description>
           <param-name>expectedHostname</param-name>
           <param-value>openam.example.com:8088</param-value>
       </init-param>
       <init-param>
           <description>
               Exposed Headers (Optional):
               The comma separated list of headers
               which the user-agent can expose to its CORS client.
           </description>
           <param-name>exposeHeaders</param-name>
           <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie,WWW-Authenticate</param-value>
       </init-param>
       <init-param>
           <description>
               Maximum Cache Age (Optional):
               The maximum time that the CORS client can cache
               the pre-flight response, in seconds.
               Default: 600
           </description>
           <param-name>maxAge</param-name>
           <param-value>600</param-value>
       </init-param>
   </filter>
   

3. Restart AM.

1. Log in to the AM console as administrator.

2. In the top level realm, select Configure OAuth Provider > Configure OAuth 2.0, accept the default values, and select Create.

   The AM service OAuth2 Provider is created for the authorization endpoint.

   The PAT is obtained through the OAuth 2.0 access token endpoint. The RPT is obtained through the UMA endpoint.

   If you plan to build your own examples or modify the sample clients, consider extending the default token lifetimes.

3. Select Configure OAuth Provider > Configure User Managed Access, accept the default values, and select Create.

   The AM service UMA Provider is created.

Follow these steps to register client profiles for OAuth 2.0 and UMA:

1. In the top level realm, select Applications > OAuth 2.0.

2. Add an OAuth 2.0 client to use for UMA protection:

   1. Add a client with the following values:

      • Client ID: OpenIG

      • Client secret: password

      • Scope: uma_protection

   2. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Resource Owner Password Credentials

3. Add an OAuth 2.0 client to use for accessing protected resources:

   1. Add a client with the following values:

      • Client ID: UmaClient

      • Client secret: password

      • Scope: openid

   2. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types:

        • Resource Owner Password Credentials

        • UMA: The client (on behalf of the requesting party) needs the UMA grant type to access the protected resources.

Follow these steps to create identities in the top level realm:

1. In the top level realm, select Identities.

2. Add a new identity to act as a resource owner, with the following values:

   • ID: alice

   • Password: UMAexamp1e

3. Add a new identity to act as a requesting party, with the following values:

   • ID: bob

   • Password: UMAexamp1e

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide.

1. Add the following file as $HOME/.openig/config/admin.json (on Windows, %appdata%\OpenIG\config\admin.json):

   {
     "heap": [
       {
         "name": "ClientHandler",
         "type": "ClientHandler"
       },
       {
         "name": "ApiProtectionFilter",
         "type": "ScriptableFilter",
         "config": {
           "type": "application/x-groovy",
           "file": "CorsFilter.groovy"
         }
       }
     ],
     "prefix": "openig"
   }

   To allow CORS support for the UMA share API, this route overrides the default ApiProtectionFilter that protects the reserved administrative route. By default, the administrative route is under /openig. For information, see AdminHttpApplication(5) in the Configuration Reference.

2. Add the following script to the IG configuration as $HOME/.openig/scripts/groovy/CorsFilter.groovy (on Windows, %appdata%\OpenIG\scripts\groovy\CorsFilter.groovy):

   import org.forgerock.http.protocol.Response
   import org.forgerock.http.protocol.Status
   
   if (request.method == 'OPTIONS') {
       /**
        * Supplies a response to a CORS preflight request.
        *
        * Example response:
        *
        * HTTP/1.1 200 OK
        * Access-Control-Allow-Origin: http://app.example.com:8081
        * Access-Control-Allow-Methods: POST
        * Access-Control-Allow-Headers: Authorization
        * Access-Control-Allow-Credentials: true
        * Access-Control-Max-Age: 3600
        */
   
       def origin = request.headers['Origin']?.firstValue
       def response = new Response(Status.OK)
   
       // Browsers sending a cross-origin request from a file might have Origin: null.
       response.headers.put("Access-Control-Allow-Origin", origin)
       request.headers['Access-Control-Request-Method']?.values.each() {
           response.headers.add("Access-Control-Allow-Methods", it)
       }
       request.headers['Access-Control-Request-Headers']?.values.each() {
           response.headers.add("Access-Control-Allow-Headers", it)
       }
       response.headers.put("Access-Control-Allow-Credentials", "true")
       response.headers.put("Access-Control-Max-Age", "3600")
   
       return response
   }
   
   return next.handle(context, request)
   /**
    * Adds headers to a CORS response.
    */
           .thenOnResult({ response ->
       if (response.status.isServerError()) {
           // Skip headers if the response is a server error.
       } else {
           def headers = [
                   "Access-Control-Allow-Origin": request.headers['Origin']?.firstValue,
                   "Access-Control-Allow-Credentials": "true",
                   "Access-Control-Expose-Headers": "WWW-Authenticate"
           ]
           response.headers.addAll(headers)
       }
   })
   

   This script adds a CORS filter to include headers for cross-origin requests.

   The tutorial involves JavaScript clients that are served by the sample application, and so not from the same origin as AM or IG. The route uses a CORS filter to include appropriate response headers for cross-origin requests.

   The CORS filter handles pre-flight (HTTP OPTIONS) requests, and responses for all HTTP operations. The logic for the filter is provided through the script.

   The filter adds the appropriate headers to CORS requests. Pre-flight requests are diverted to a dedicated handler, which returns the response directly to the user agent. For all other requests, the headers are added to the response.

   For information about scripting filters and handlers, see "Extending IG".

3. Add the following route to the IG configuration as $HOME/.openig/config/routes/00-uma.json (on Windows, %appdata%\OpenIG\config\routes\00-uma.json).

   {
     "heap": [
       {
         "name": "UmaService",
         "type": "UmaService",
         "config": {
           "protectionApiHandler": "ClientHandler",
           "wellKnownEndpoint": "http://openam.example.com:8088/openam/uma/.well-known/uma2-configuration",
           "resources": [
             {
               "comment": "Protects all resources matching the following pattern.",
               "pattern": ".*",
               "actions": [
                 {
                   "scopes": [
                     "#read"
                   ],
                   "condition": "${request.method == 'GET'}"
                 },
                 {
                   "scopes": [
                     "#create"
                   ],
                   "condition": "${request.method == 'POST'}"
                 }
               ]
             }
           ]
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "ScriptableFilter",
             "config": {
               "type": "application/x-groovy",
               "file": "CorsFilter.groovy"
             }
           },
           {
             "type": "UmaFilter",
             "config": {
               "protectionApiHandler": "ClientHandler",
               "umaService": "UmaService"
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     },
     "condition": "${request.uri.host == 'app.example.com'}"
   }
   

   Notice the following features of the route:

   • The UmaService describes the resources that a resource owner can share, using AM as the authorization server.

     The UmaService provides a REST API to manage sharing of resource sets.

   • The handler for the route chains together the CORS filter, the UmaFilter, and the default handler.

     The UmaFilter manages requesting party access to protected resources, using the UmaService. Protected resources are on the sample application, which responds to requests on port 8081.

   • The route matches requests to app.example.com.

4. Restart IG to reload the configuration.

Follow these steps to test the configuration and demonstrate IG acting as an UMA resource server:

1. If necessary, log out of AM, and then browse to http://app.example.com:8081/uma/.

   If you used the settings described in this chapter and "Installing the Sample Application" in the Getting Started Guide, your configuration should match the displayed configuration. If you used other settings, you might need to edit the sample files to match your settings. For information, see "Editing the Example to Match Custom Settings".

2. Select the link to demonstrate Alice sharing resources.

3. On Alice's page, select Share with Bob to simulate Alice sharing resources as described in "Sharing and Accessing Protected Resources".

   The following items are displayed:

   • The PAT that Alice receives from AM

   • The metadata for the resource set that Alice registers through IG

   • The result of Alice authenticating with AM in order to create a policy

   • The successful result when Alice configures the authorization policy attached to the shared resource.

   If the step fails, get help in "Troubleshooting the UMA Example".

4. Go back to the first page, and select the link to demonstrate Bob accessing resources.

5. On Bob's page, select Get Alice's resources to simulate Bob accessing one of Alice's resources.

   The following items are displayed:

   • The WWW-Authenticate Header

   • The OpenID Connect Token that Bob gets to obtain the RPT

   • The RPT that Bob gets in order to request the resource again

   • The final response containing the body of the resource

1. Unpack the UMA files from the sample application described in "Installing the Sample Application" in the Getting Started Guide to temporary folder:

   $ mkdir /tmp/uma
   $ cd /tmp/uma
   $ jar -xvf /path/to/IG-sample-application-6.5.4.jar uma
    created: uma/
   inflated: uma/alice.html
   inflated: uma/bob.html
   inflated: uma/common.js
   inflated: uma/index.html
   inflated: uma/style.css
         

2. Edit the configuration in common.js, alice.html, and bob.html to match your settings.

3. Repack the UMA sample client files and then restart the sample application:

   $ jar -uvf /path/to/IG-sample-application-6.5.4.jar uma
   adding: uma/(in = 0) (out= 0)(stored 0%)
   adding: uma/index.html(in = 1698) (out= 880)(deflated 48%)
   adding: uma/common.js(in = 4265) (out= 1319)(deflated 69%)
   adding: uma/bob.html(in = 5427) (out= 1811)(deflated 66%)
   adding: uma/style.css(in = 1403) (out= 696)(deflated 50%)
   adding: uma/alice.html(in = 5494) (out= 1762)(deflated 67%)

4. If necessary, adjust the CORS settings for AM.

Before you start, prepare IG as described in "First Steps" in the Getting Started Guide.

1. Add the following route to the IG configuration as $HOME/.openig/config/routes/00-crest.json.

   On Windows, add the route as %appdata%\OpenIG\config\routes\00-crest.json.

   {
     "name": "crest",
     "handler": {
       "type": "StaticResponseHandler",
       "config": {
         "status": 200,
         "reason": "OK",
         "entity": "Hello, world!"
       }
     },
     "condition": "${matches(request.uri.path, '^/crest')}"
   }

   To check that the route is working, access the route on: http://openig.example.com:8080/crest.

2. To read a route through Common REST:

   • Enter the following command in a terminal window:

     $ http GET http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-crest

     The route is displayed. Note that the route _id is displayed in the JSON of the route.

3. To add a route through Common REST:

   • Move $HOME/.openig/config/routes/00-crest.json to /tmp/00-crest.json.

   • Check in $HOME/.openig/logs/route-system.log that the route has been removed from the configuration. To double check, access http://openig.example.com:8080/crest. You should get an HTTP 404.

   • Enter the following command in a terminal window:

     $ http PUT http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-crest < /tmp/00-crest.json

     This command posts the file in /tmp/00-crest.json to the routes directory.

   • Check in $HOME/.openig/logs/route-system.log that the route has been added to configuration. To double-check, access http://openig.example.com:8080/crest. You should see the "Hello, world!" message.

4. To edit a route through Common REST:

   • Edit /tmp/00-crest.json to change the message displayed by the response handler in the route.

   • Enter the following command in a terminal window:

     $ http PUT http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-crest If-Match:* < /tmp/00-crest.json

     This command deploys the route with the new configuration. Because the changes are persisted into the configuration, the existing $HOME/.openig/config/routes/00-crest.json is replaced with the edited version in /tmp/00-crest.json.

   • Check in $HOME/.openig/logs/route-system.log, that the route has been updated. To double-check, access http://openig.example.com:8080/crest to confirm that the displayed message has changed.

5. To delete a route through Common REST:

   • Enter the following command in a terminal window:

     $ $ http DELETE http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-crest

   • Check in $HOME/.openig/logs/route-system.log that the route has been removed from the configuration. To double-check, access http://openig.example.com:8080/crest. You should get an HTTP 404.

6. To list the routes deployed on the router, in the order that they are tried by the router:

   • Enter the following command in a terminal window:

     $ http "http://openig.example.com:8080/openig/api/system/objects/_router/routes?_queryFilter=true"

     The list of loaded routes is displayed.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

1. Set up AM:

   1. (For AM 6.5.3 and earlier versions) Select  Identities > demo, and set the demo user password to Ch4ng31t.

   2. (For AM 6.5.3 and later versions) Select Services, and add a Validation Service with the following URLs for IG:

      • http://openig.example.com:8080/*

      • http://openig.example.com:8080/*?*

   3. (For AM 6.5.3 and later versions) Select Applications > Agents > Identity Gateway, and add an agent with the following values:

      • Agent ID: ig_agent

      • Password: password

      Leave all other values as default.

      (For AM 6.5.2 and earlier versions) Set up an agent as described in "To Set Up a Java Agent in AM".

2. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

3. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /websocket

   • Name: websocket

   • Enable WebSocket: Select this option

4. Configure authentication:

   1. Select  Authentication.

   2. Select Single Sign-On, and enter the following information:

      • AM service:

        • URI: http://openam.example.com:8088/openam

        • Version: The version of the AM instance, for example, 6.5.

        • Agent: The credentials of the Java agent you created in AM.

          • Username: ig_agent

          • Password: password

      Leave all other values as default.

5. On the top-right of the screen, select  and  Display to review the route.

   The following route should be displayed:

   {
     "name": "websocket",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/websocket')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.5",
           "agent": {
             "username": "ig_agent",
             "password": "password"
           },
           "sessionCache": {
             "enabled": false
           }
         }
       },
       {
         "name": "ReverseProxyHandler",
         "type": "ReverseProxyHandler",
         "config": {
           "websocket": {
             "enabled": true
           }
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "SingleSignOnFilter-1",
             "type": "SingleSignOnFilter",
             "config": {
               "amService": "AmService-1"
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

6. Notice the following features of the route:

   • The route matches requests to /websocket, the endpoint on the sample app that exposes a WebSocket server.

   • The SingleSignOnFilter redirects unauthenticated requests to AM for authentication.

   • The ReverserProxyHandler enables IG to proxy WebSocket traffic, and, after IG upgrades the HTTP connection to the WebSocket protocol, passes the messages to the WebSocket server.

7. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. If necessary log out of AM, and then browse to http://openig.example.com:8080/websocket.

   The SingleSignOnFilter redirects you to AM for authentication.

2. Log in to AM as user demo, password Ch4ng31t.

   AM authenticates the user, creates an SSO token, and redirects the request back to the original URI, with the token in a cookie.

   The request then passes to the ReverseProxyHandler, which routes the request to the HTML page /websocket/index.html of the sample app. The page initiates the HTTP handshake for connecting to the WebSocket endpoint /websocket/echo.

3. Enter text on the WebSocket echo screen, and note that the text is echoed back.

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

2. Select Advanced options, and create a route with the following options:

   • Base URI: http://app.example.com:8081

   • Condition: Path: /home/throttle-simple

   • Name: 00-throttle-simple

3. Select  Throttling, and then enable throttling.

4. In GROUPING POLICY, select to apply the rate to a single group.

   All requests are grouped together, and the default throttling rate is applied to the group. By default, no more than 100 requests can access the sample application each second.

5. In RATE POLICY, select Fixed, and Edit, and then allow 6 requests each 10 seconds.

6. On the top-right of the screen, select  and  Display to review the route.

   The following route should be displayed:

   {
     "name": "00-throttle-simple",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/throttle-simple')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "ThrottlingFilter",
             "name": "ThrottlingFilter-1",
             "config": {
               "requestGroupingPolicy": "",
               "rate": {
                 "numberOfRequests": 6,
                 "duration": "10 s"
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Notice the following features of the route:

   • The route matches requests to /home/throttle-simple.

   • The ThrottlingFilter contains a request grouping policy that is blank. This means that all requests are in the same group.

   • The rate defines the number of requests allowed to access the sample application in a given time.

7. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. With IG and the sample application running, use curl, a bash script, or another tool to access the following route in a loop: http://openig.example.com:8080/home/simple-throttle.

   Accessing the route in a loop runs the request multiple times in quick succession, allowing you to test the throttling rate.

   $ curl -v http://openig.example.com:8080/home/throttle-simple/\[01-10\] \
   > /tmp/simple-throttle.txt 2>&1

2. Search the output file to see the result:

   $ grep "< HTTP/1.1" /tmp/simple-throttle.txt | sort | uniq -c
   
   6 < HTTP/1.1 200 OK
   4 < HTTP/1.1 429 Too Many Requests

   Notice that the first six requests returned a success response, and the following four requests returned an HTTP 429 Too Many Requests. This result demonstrates that the throttling filter has allowed only six requests to access the application, and has blocked the other requests.

1. Follow the steps in "To Set Up AM As an Authorization Server for the Token Info Endpoint".

2. Select Scripts > OAuth2 Access Token Modification Script, and replace the default script as follows:

   import org.forgerock.http.protocol.Request
   import org.forgerock.http.protocol.Response
   
   def attributes = identity.getAttributes(["mail", "employeeNumber"].toSet())
   accessToken.setField("mail", attributes["mail"][0])
   def mail = attributes['mail'][0]
   if (mail.endsWith('@example.com')) {
        status = "gold"
   } else if (mail.endsWith('@other.com')) {
        status = "silver"
   } else {
        status = "bronze"
   }
   accessToken.setField("status", status)

   The AM script adds user profile information to the access_token, and defines the content of the users status field according to the email domain.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

1. In IG Studio, create a route:

   1. Browse to http://openig.example.com:8080/openig/studio, and select  Protect an Application.

   2. Choose  Structured to use the predefined menus and templates.

   3. Select Advanced options, and create a route with the following options:

      • Base URI: http://app.example.com:8081

      • Condition: Path: /home/throttle-mapped

      • Name: 00-throttle-mapped

2. Configure authorization:

   1. Select  Authorization.

   2. Select OAuth 2.0 Resource Server, and enter the following information to reflect the configuration in AM:

      • Token resolver configuration:

        • Access token resolver: AM token info endpoint

        • AM service:

          • URI: http://openam.example.com:8088/openam

          • Version: The version of the AM instance, for example, 6.5.

          • Agent: The credentials of the Java agent you created in AM.

            • Username: ig_agent

            • Password: password

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

      Leave all other values as default.

3. Configure throttling:

   1. Select  Throttling, and then enable throttling.

   2. Set up the grouping policy:

      1. In GROUPING POLICY, apply the rate to independent groups of requests.

         Requests are split into different groups according to criteria, and the throttling rate is applied to each group.

      2. Select to group requests by custom criteria.

      3. Enter ${contexts.oauth2.accessToken.info.mail} as the custom expression.

         This expression defines the subject in the OAuth2Context.

   3. Set up the rate policy:

      1. In RATE POLICY, select Mapped.

      2. Select to map requests by custom criteria.

      3. Enter the custom expression ${contexts.oauth2.accessToken.info.employeenumber}.

      4. In Default Rate, select Edit and change default rate to 1 request each 10 seconds.

      5. In Mapped Rates, add the following rate for gold status:

         • Match Value: gold

         • Number of requests: 6

         • Period: 10 seconds

      6. Add a different rate for silver status:

         • Match Value: silver

         • Number of requests: 3

         • Period: 10 seconds

      7. Add a different rate for bronze status:

         • Match Value: bronze

         • Number of requests: 1

         • Period: 10 seconds

      8. Save the rate policy.

4. Select  Chain, and change the order of the filters so that  Throttling comes after  Authorization.

5. On the top-right of the screen, select  and  Display to review the route.

   The following route should be displayed:

   {
     "name": "00-throttle-mapped",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/throttle-mapped')}",
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.5",
           "agent": {
             "username": "ig_agent",
             "password": "password"
           },
           "sessionCache": {
             "enabled": false
           }
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ResourceServerFilter-1",
             "type": "OAuth2ResourceServerFilter",
             "config": {
               "scopes": [
                 "mail",
                 "employeenumber"
               ],
               "requireHttps": false,
               "realm": "OpenIG",
               "accessTokenResolver": {
                 "name": "token-resolver-1",
                 "type": "OpenAmAccessTokenResolver",
                 "config": {
                   "amService": "AmService-1"
                 }
               }
             }
           },
           {
             "name": "ThrottlingFilter-1",
             "type": "ThrottlingFilter",
             "config": {
               "requestGroupingPolicy": "${contexts.oauth2.accessToken.info.mail}",
               "throttlingRatePolicy": {
                 "name": "MappedPolicy",
                 "type": "MappedThrottlingPolicy",
                 "config": {
                   "throttlingRateMapper": "${contexts.oauth2.accessToken.info.status}",
                   "throttlingRatesMapping": {
                     "gold": {
                       "numberOfRequests": 6,
                       "duration": "10 s"
                     },
                     "silver": {
                       "numberOfRequests": 3,
                       "duration": "10 s"
                     },
                     "bronze": {
                       "numberOfRequests": 1,
                       "duration": "10 s"
                     }
                   },
                   "defaultRate": {
                     "numberOfRequests": 1,
                     "duration": "10 s"
                   }
                 }
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Notice the following features of the route:

   • The route matches requests to /home/throttle-mapped.

   • The OAuth2ResourceServerFilter validates requests with the OpenAmAccessTokenResolver, and makes it available for downstream components in the oauth2 context.

   • The ThrottlingFilter bases the request grouping policy on the AM user's mail. The throttling rate is applied independently to each email address.

     The throttling rate is mapped to the AM user's status, which is defined by the email domain, in the AM script.

6. Select  Deploy to push the route to the IG configuration.

   You can check the $HOME/.openig/config/routes folder to see that the route is there.

1. Get an access_token for George from AM:

   $ george_token=$(curl -s \
     --user "client-application:password" \
     --data "grant_type=password&username=george&password=C0stanza&scope=mail%20employeenumber" \
     http://openam.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

2. Using the access_token for authentication, access the route multiple times. The following example accesses the route 10 times, and writes the output to a file:

   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] --header "Authorization:Bearer ${george_token}" > /tmp/george.txt 2>&1

3. Search the output file to see the result:

   $ grep "< HTTP/1.1" /tmp/george.txt | sort | uniq -c
        
   6 < HTTP/1.1 200
   4 < HTTP/1.1 429

   Notice that with a gold status, George can access the route 6 times in 10 seconds.

4. In AM, change George's email to george@other.com, and then run the last steps again to see how the access is reduced.