Follow these steps to install IG:

1. Download IG-6.0.0.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.0.0.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 the key pair in a new keystore file by using the Java keytool command.

   The following command generates a Java Keystore format file, /path/to/keystore.jks, holding a key pair with alias jwe-key. Notice that both the keystore and the private key have the same password:

   $ keytool \
    -genkey \
    -alias jwe-key \
    -keyalg rsa \
    -keystore /path/to/keystore.jks \
    -storepass changeit \
    -keypass changeit \
    -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. Add a KeyStore to your configuration that references the keystore file:

   {
       "name": "MyKeyStore",
       "type": "KeyStore",
       "config": {
           "url": "file:///path/to/keystore.jks",
           "password": "changeit"
       }
   }

   For details, see KeyStore(5) in the Configuration Reference.

3. Add a JwtSession to your configuration that references your KeyStore:

   {
       "name": "MyJwtSession",
       "type": "JwtSession",
       "config": {
           "keystore": "MyKeyStore",
           "alias": "jwe-key",
           "password": "changeit",
           "cookieName": "IG",
           "cookieDomain": ".example.com"
       }
   }

   For a deployment with more than one IG instance, also configure a "sharedSecret" as described in JwtSession(5) in the Configuration Reference.

4. Specify your JwtSession object in the top-level configuration, or in the route configuration:

   "session": "MyJwtSession"

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.

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

   username,password,fullname,email
   george,costanza,George Costanza,george@example.com
   kramer,newman,Kramer,kramer@example.com
   bjensen,hifalutin,Babs Jensen,bjensen@example.com
   demo,changeit,Demo User,demo@example.com
   kvaughan,bribery,Kirsten Vaughan,kvaughan@example.com
   scarter,sprain,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. Make a note of the key for later.

1. Update the Authentication Post Processing Classes for password replay.

   1. In the AM console, select Authentication > Settings > Post Authentication Processing.

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

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

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

4. Restart AM.

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

   {
     "heap": [{
       "name": "AmService-1",
       "type": "AmService",
       "config": {
         "url": "http://openam.example.com:8088/openam/",
         "version": "6.0"
       }
     },
       {
         "name": "CapturedUserPasswordFilter",
         "type": "CapturedUserPasswordFilter",
         "config": {
           "ssoToken": "${contexts.ssoToken.value}",
           "key": "DESKEY",
           "amService": "AmService-1"
         }
       }
     ],
     "name": "04-replay",
     "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"
       }
     },
     "condition": "${matches(request.uri.path, '^/replay')}"
   }

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

3. Change DESKEY to the key value that you generated in "To Create a DES Shared Key In IG".

   Notice the following features of the route:

   • The route matches requests to /replay.

   • The first filter in the chain is the SingleSignOnFilter. For information, see SingleSignOnFilter(5) in the Configuration Reference.

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

   The request is redirected to the sample application.

   Tip

   If requests are directed to AM instead of to the sample application, review the cookie domain in the AM configuration. For more information, see "Requests Redirected to Access Management Instead of to the Resource".

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

2. Add a new agent with the following values:

   • Agent ID: J2EE

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

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

   • Password: password

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

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. Browse to http://openig.ext.com:8080/openig/studio, and select  Protect an Application.

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

3. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/cdsso

   • Name: cdsso

4. Configure authentication:

   1. Select  Authentication, and then enable it.

   2. Select Cross-Domain Single Sign-On, and enter the following information to reflect the configuration in "To Enable CDSSO in AM", 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, with at least one point. For example, 6.0.

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

          • Username: J2EE

          • Password: password

      • Redirect endpoint: /home/cdsso/redirect

      • Authentication cookie:

        • Path: /home

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

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

   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.

   Tip

   If requests are directed to AM instead of to the sample application, review the cookie domain in the AM configuration. For more information, see "Requests Redirected to Access Management Instead of to the Resource".

If you haven't set up the user George Costanza in a previous tutorial, do so now.

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

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

   • ID: george

   • Password: costanza

3. In the User window, set the following values:

   • Email Address: george

   • Employee number: costanza

1. In the AM console, 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.

2. Configure a profile for the third-party application to request OAuth 2.0 access tokens:

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

   2. Add a client with the following values:

      • Client ID: client-application

      • Client secret: password

      • Scope(s): mail employeenumber

      This tutorial uses mail to hold the username, and employeenumber to hold the password. The attributes are part of a user's profile included with the default AM configuration, and are not needed for anything else in this tutorial. In a real deployment, you would no doubt use other attributes that depend on how the real user profiles are configured.

3. If you plan to use the token introspection endpoint to validate the access tokens, configure a profile for the resource server:

   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

        The client with this scope is authorized to examine (introspect) tokens.

4. Log out of AM.

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

   $ curl \
   --user "client-application:password" \
   --data "grant_type=password&username=george&password=costanza&scope=mail%20employeenumber" \
   http://openam.example.com:8088/openam/oauth2/access_token
   
   {
   "access_token":"aba19a55-468d-45e2-b1c4-decc7202faea",
   "scope":"employeenumber mail",
   "token_type":"Bearer",
   "expires_in":3599
   }

2. Validate the access token:

   • To use the /oauth2/tokeninfo endpoint, run the following command, replacing <access_token> with the access token returned by the previous step:

     $ curl \
     --header "Authorization: Bearer <access_token>" \
     http://openig.example.com:8080/rs-tokeninfo
     
     {
       access_token = f12c7d3e - 0183 - 4 f89 - 8 f5d - aa3055713a96,
       employeenumber = costanza,
       mail = george,
       grant_type = password,
       scope = [employeenumber, mail],
       realm = /,
       token_type = Bearer,
       expires_in = 32606,
       client_id = client-application
     }

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

   • To use the /oauth2/introspect endpoint, run the following command, replacing <access_token> with the access token returned by the previous step:

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

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

1. Run the example in "To Set Up IG As a Resource Server Using the Token Info Endpoint".

2. On the top-right of the Studio screen, select  and  Editor mode.

3. Remove the StaticResponseHandler, and add the following filters and handler:

   • An AssignmentFilter to access the token info through the context, and inject the credentials into session.

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

   • 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')}",
     "monitor": false,
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.0"
         }
       }
     ],
     "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 access the example route, replacing <access_token> with a new access token or the one returned in "To Test the Setup":

   $ curl \
   --header "Authorization: Bearer <access_token>" \
   http://openig.example.com:8080/rs-pwreplay

   HTML for the sample application should be displayed.

If you haven't set up the user George Costanza in a previous tutorial, do so now.

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

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

   • ID: george

   • Password: costanza

3. In the User window, select the new user and set Email Address: george@example.com.

1. Configure AM as an OAuth 2.0 Authorization Server and OpenID Connect Provider.

   1. In the AM console, select the top level realm and browse to Configure OAuth Provider > Configure OpenID Connect.

   2. Accept the default values and click Create.

2. Register an OpenID Connect relying party. This step enables IG to communicate as an OAuth 2.0 relying party with AM.

   1. In the top level realm, 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. Click Add then on Signing and Encryption tab:

      • Change ID Token Signing Algorithm to HS256, HS384, or HS512.

        Because the algorithm must be HMAC, the value of RS256 is not okay.

3. Log out of AM.

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. 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. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/id_token

   • Name: 07-openid

4. Select Authentication, and then enable authentication.

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

     • Basic authentication: Select this option

   • Issuer:

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

   Leave the other settings with their default values.

6. On the top-right of the screen, select  and  Display to review the route. The route in "Route for IG As a Relying Party" should be displayed.

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 running, access http://openig.example.com:8080/home/id_token.

   The AM login screen is displayed.

2. Log in to AM with the username george and password costanza.

   An OpenID Connect request to access private information is displayed.

3. Select Allow.

   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 consent to authorize access to user information. After you authorize access, AM 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.

The first steps of this procedure are the same as those for "To Set Up IG As a Relying Party". Adapt that route or follow this procedure to set up a new route.

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. 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. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/id_token

   • Name: 07-openid

4. Set up authentication:

   1. Select Authentication, and then enable 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 email

        • Basic authentication: Select this option

      • Issuer:

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

      Leave the other settings with their default values.

5. Set up token transformation:

   1. Select  Token transformation and enable it.

   2. In AM server, select Configure, and set up the following AM server:

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

        The URI of the AM service to use for authentication and REST STS requests.

      • Version: Enter the version of your AM server instance

      Leave the other fields of AM server with their default values.

   3. Enter the following values for token transformation, and then save the route:

      • Username: oidc_client

      • Password: password

      • id_token: ${attributes.openid.id_token}

      • Instance: openig

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

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

   Make sure that the following route is displayed:

   {
     "name": "50-idtoken2",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/id_token')}",
     "monitor": false,
     "heap": [
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "url": "http://openam.example.com:8088/openam",
           "realm": "/",
           "ssoTokenHeader": "iPlanetDirectoryPro",
           "version": "6.0"
         }
       }
     ],
     "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}.

8. 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. http://openig.example.com:8080/home/id_token.

   The AM login screen is displayed.

2. Log in to AM with the username george and password costanza.

   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>
   

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 a client with the following values:

   • Client ID: OpenIG

   • Client secret: password

   • Scope: uma_protection

3. Add a client to use when accessing resources, with the following values:

   • Client ID: UmaClient

   • Client secret: password

   • Scope: openid

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

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

   • ID: bob

   • Password: password

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, add the route as %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 route to the IG configuration as $HOME/.openig/config/routes/00-uma.json.

   On Windows, add the route as %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": "ClientHandler"
       }
     },
     "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.

3. Add the following script to the IG configuration as $HOME/.openig/scripts/groovy/CorsFilter.groovy.

   On Windows, add the script as %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 Identity Gateway".

4. Restart IG to reload the configuration.

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

1. Log out of AM.

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

3. Select the link to demonstrate Alice sharing resources.

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

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

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

To try the script, follow these steps:

1. Follow the tutorial in "Log in With Credentials From a Database".

   When everything in that tutorial works, you know that IG can connect to the database, look up users by email address, and successfully authenticate to the sample application.

2. Save the scripts as $HOME/.openig/scripts/groovy/SqlAccessFilter.groovy (%appdata%\OpenIG\scripts\groovy\SqlAccessFilter.groovy on Windows), and as $HOME/.openig/scripts/groovy/SqlClient.groovy (%appdata%\OpenIG\scripts\groovy\SqlClient.groovy on Windows).

3. Add the following route to your configuration as $HOME/.openig/config/routes/11-db.json (%appdata%\OpenIG\config\routes\11-db.json on Windows):

   {
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "ScriptableFilter",
             "config": {
               "type": "application/x-groovy",
               "file": "SqlAccessFilter.groovy"
             }
           },
           {
             "type": "StaticRequestFilter",
             "config": {
               "method": "POST",
               "uri": "http://app.example.com:8081/login",
               "form": {
                 "username": [
                   "${request.headers['Username'][0]}"
                 ],
                 "password": [
                   "${request.headers['Password'][0]}"
                 ]
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     },
     "condition": "${matches(request.uri.path, '^/db')}"
   }
   

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

1. Add the following route to the IG as $HOME/.openig/config/routes/30-audit.json.

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

   {
     "handler": "ForgeRockClientHandler",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/audit')}",
     "auditService": {
       "type": "AuditService",
       "config": {
         "config": {},
         "event-handlers": [
           {
             "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
             "config": {
               "name": "csv",
               "logDirectory": "/tmp/logs",
               "buffering": {
                 "enabled": "true",
                 "autoFlush": "true"
               },
               "topics": [
                 "access"
               ]
             }
           }
         ]
       }
     }
   }
   

   The route calls an audit service configuration for publishing log messages to the CSV file, /tmp/logs/access.csv. When a request matches audit, audit events are logged to the CSV file.

   The route uses the ForgeRockClientHandler as its handler, to send the X-ForgeRock-TransactionId header with its requests to external services.

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

   The home page of the sample application should be displayed and the file /tmp/logs/access.csv should be updated.

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. Make sure that Elasticsearch is installed and running.

   For Elasticsearch downloads and installation instructions, see the Elasticsearch Getting Started document. For information about configuring the Elasticsearch event handler, see ElasticsearchAuditEventHandler(5) in the Configuration Reference.

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

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

4. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/audit

   • Name: 30-elasticsearch

5. Configure auditing:

   1. Select  Audit, and then enable it.

   2. Select  New event handler and then Elasticsearch event handler.

   3. Enter the following information, and then save the settings:

      • Name: elasticsearch

      Leave the other fields with their default values and save.

   4. In the event handlers frame, enable the event handler.

6. On the top-right of the screen, select  and  Display to review the route. The following route should be displayed:

   {
     "name": "30-elasticsearch",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/audit')}",
     "monitor": false,
     "auditService": {
       "name": "AuditService",
       "type": "AuditService",
       "config": {
         "event-handlers": [
           {
             "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
             "config": {
               "name": "elasticsearch",
               "indexMapping": {
                 "indexName": "audit"
               },
               "connection": {
                 "host": "localhost",
                 "port": 9200,
                 "useSSL": false
               },
               "topics": [
                 "access"
               ]
             }
           }
         ]
       }
     },
     "handler": "ReverseProxyHandler"
   }

7. (Optional) Select  Edit and set options to manage the connection, index mapping, and buffering. Use information in ElasticsearchAuditEventHandler(5) in the Configuration Reference.

8. 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. Access the route on http://openig.example.com:8080/home/audit.

   The home page of the sample application is displayed and events are logged in Elasticsearch.

2. Access the ElasticSearch URL, http://localhost:9200/audit/access/_search?q='"OPENIG-HTTP-ACCESS"'

   The audit events logged in Elasticsearch are displayed.

3. Repeat the previous steps to confirm that each time you access the IG, Elasticsearch is updated.

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

1. Add ActiveMQ client dependencies to IG:

   1. Download the following .jar files from :

      • geronimo-j2ee-management_1.1_spec-1.0.1.jar

      • hawtbuf-1.11.jar

      • activemq-client-5.13.3.jar

   2. Add the .jar files to the IG container, at /path/to/jetty/webapps/ROOT/WEB-INF/lib.

2. Download and install the ActiveMQ message broker from http://activemq.apache.org/. For help, see the the ActiveMQ documentation on the same site.

3. Create a consumer that subscribes to the audit topic.

   From the ActiveMQ installation directory, run the following command:

   $ ./bin/activemq consumer --destination topic://audit

4. Add the following route to the IG as $HOME/.openig/config/routes/30-jms.json. On Windows, add the route as %appdata%\OpenIG\config\routes\30-jms.json.

   {
     "MyCapture" : "all",
     "auditService" : {
       "config" : {
         "event-handlers" : [
           {
             "class" : "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
             "config" : {
               "name" : "jms",
               "topics" : [ "access" ],
               "deliveryMode" : "NON_PERSISTENT",
               "sessionMode" : "AUTO",
               "jndi" : {
                 "contextProperties" : {
                   "java.naming.factory.initial" : "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
                   "java.naming.provider.url" : "tcp://openam.example.com:61616",
                   "topic.audit" : "audit"
                 },
                 "topicName" : "audit",
                 "connectionFactoryName" : "ConnectionFactory"
               }
             }
           }
         ],
         "config" : { }
       },
       "type" : "AuditService"
     },
     "handler" : {
       "type" : "StaticResponseHandler",
       "config" : {
         "status" : 200,
         "headers" : {
           "content-type" : [ "text/plain" ]
         },
         "reason" : "found",
         "entity" : "Message from audited route"
       }
     },
     "monitor" : true,
     "condition" : "${request.uri.path == '/activemq_event_handler'}"
   }

   When a request matches the /activemq_event_handler route, this configuration publishes JMS messages containing audit event data to an ActiveMQ managed JMS topic, and the StaticResponseHandler displays a message.

5. Access the route on http://openig.example.com:8080/activemq_event_handler.

   Depending on how ActiveMQ is configured, audit events are displayed on the ActiveMQ console or written to file. For example, the following log message can be written to a log file in the folder where you installed ActiveMQ:

   {
     "auditTopic": "access",
     "event": {
       "eventName": "OPENIG-HTTP-ACCESS",
       "timestamp": "2016-11-28T14:39:30.004Z",
       "transactionId": "882918f9-f7c3-47ee-9f87-5e3cfcfb98be-37",
       "server": {
         "ip": "0:0:0:0:0:0:0:1",
         "port": 8080
       },
       "client": {
         "ip": "0:0:0:0:0:0:0:1",
         "port": 56095
       },
       "http": {
         "request": {
           "secure": false,
           "method": "GET",
           "path": "http://openig.example.com:8080/activemq_event_handler",
           "queryParameters": {},
           "headers": {
             "accept": ["*/*"],
             "accept-encoding": ["gzip, deflate"],
             "Connection": ["keep-alive"],
             "host": ["openig.example.com:8080"],
             "user-agent": ["python-requests/2.9.1"]
           },
           "cookies": {}
         },
         "response": {
           "headers": {
             "Content-Length": ["26"],
             "Content-Type": ["text/plain"]
           }
         }
       },
       "response": {
         "status": "SUCCESSFUL",
         "statusCode": "200",
         "elapsedTime": 73,
         "elapsedTimeUnits": "MILLISECONDS"
       },
       "_id": "882918f9-f7c3-47ee-9f87-5e3cfcfb98be-38"
     }
   }

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. 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. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/audit

   • Name: 30-json

4. Configure auditing:

   1. Select  Audit, and then enable it.

   2. Select  New event handler and then JSON audit event handler.

   3. Enter the following information, and then save the settings:

      • Name: json

      • Log directory: /tmp/logs

      Leave the other fields with their default values and save.

5. In the event handlers frame, enable the event handler

6. On the top-right of the screen, select  and  Display to review the route. The following route should be displayed:

   {
     "name": "30-json",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/audit')}",
     "monitor": false,
     "auditService": {
       "name": "AuditService",
       "type": "AuditService",
       "config": {
         "event-handlers": [
           {
             "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
             "config": {
               "name": "json",
               "logDirectory": "/tmp/logs",
               "elasticsearchCompatible": false,
               "topics": [
                 "access"
               ],
               "buffering": {
                 "maxSize": 100000,
                 "writeInterval": "100 ms"
               },
               "rotationRetentionCheckInterval": "1 m"
             }
           }
         ]
       }
     },
     "handler": "ReverseProxyHandler"
   }

   The route calls an audit service configuration for publishing log messages to the JSON file, /tmp/audit/access.audit.json. When a request matches /home/json-audit, a single line per audit event is logged to the JSON file.

   The route uses the ForgeRockClientHandler as its handler, to send the X-ForgeRock-TransactionId header with its requests to external services.

7. (Optional) Select  Edit and set options to manage compatibility with the ElasticSearch JSON format, or file rotation, retention, and buffering. Use information in JsonAuditEventHandler(5) in the Configuration Reference.

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

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

  The home page of the sample application is displayed and the file /tmp/logs/access.audit.json is created or updated with a message. The following example message is formatted for easy reading, but it is produced as a single line for each event:

  {
    "eventName": "OPENIG-HTTP-ACCESS",
    "timestamp": "2016-11-08T15:39:59.128Z",
    "transactionId": "a386a21c-0ceb-4c6b-af77-167bd71f0161-1",
    "server": {
      "ip": "0:0:0:0:0:0:0:1",
      "port": 8080
    },
    "client": {
      "ip": "0:0:0:0:0:0:0:1",
      "port": 34066
    },
    "http": {
      "request": {
        "secure": false,
        "method": "GET",
        "path": "http://openig.example.com:8080/home/json-audit",
        "queryParameters": {},
        "headers": {
          "accept": ["text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"],
          "accept-encoding": ["gzip, deflate"],
          "Accept-Language": ["en-US;q=1"],
          "cache-control": ["max-age=0"],
          "Connection": ["keep-alive"],
          "host": ["openig.example.com:8080"],
          "upgrade-insecure-requests": ["1"],
          "user-agent": ["Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6)
                          AppleWebKit / 602.2 .14(KHTML, like Gecko)
                          Version / 10.0 .1 Safari / 602.2 .14 "]
        },
        "cookies": {
          "i18next": "en"
        }
      },
      "response": {
        "status": "SUCCESSFUL",
        "statusCode": "200",
        "elapsedTime": 104,
        "elapsedTimeUnits": "MILLISECONDS"
      },
      "_id": "a386a21c-0ceb-4c6b-af77-167bd71f0161-2"
    }
  }

This procedure assumes a Splunk instance running on the same host as IG. Adjust the instructions for your Splunk system.

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

1. Download Splunk from http://www.splunk.com, and install it with the default configuration. If you don't already have a Splunk account, create one.

   Tip

   Splunk currently uses the following ports by default: 8000, 8065, 8088, 8089, and 8091. Before you install Splunk, make sure that these ports are free. Alternatively, change the Splunk installation and IG route to use other ports.

   To find port numbers and other settings used by Splunk, select Server settings > General settings in the Splunk web interface.

2. With Splunk running, create a new source type and associate it with log data from IG:

   1. In the Splunk web interface, select Settings > Source Types > New Source Type.

   2. In the Create Source Type window, enter a name for the source type, for example, openig.

   3. In the Event Breaks panel of the same window, select Regex... and enter ^{ to indicate how the bulk messages are separated.

   4. Accept all of the other values as default and select Save.

3. Create an HTTP Event Collector to provide an authorization token so that IG can log events to Splunk:

   1. Select Settings > Data Inputs > HTTP Event Collector > New Token.

   2. Enter a Name for the token, for example, openig, leave the other fields with their default values, and select Next.

   3. In the Input Settings screen, select Select > Select Source Type > Custom, and then select the source type you created in the previous step.

   4. Select Review and then Submit.

      An authorization token is displayed. Make a note of the value or keep it on the screen so that you use it as the value of authzToken in "To Set Up IG for the Splunk Audit Event Handler".

4. In the same window, check that the Global Settings are configured correctly. For example, make sure that all tokens are enabled and that SSL is not enabled.

   The HTTP port number displayed in these global settings is used as the value of port in "To Set Up IG for the Splunk Audit Event Handler".

1. Add the following route to the IG as $HOME/.openig/config/routes/30-splunk.json.

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

   {
     "handler": {
       "type": "StaticResponseHandler",
       "config": {
         "status": 200,
         "entity": "Creating Splunk Audit Event"
       }
     },
     "condition": "${matches(request.uri.path, '^/splunk')}",
     "auditService": {
       "type": "AuditService",
       "config": {
         "config": {},
         "event-handlers": [
           {
             "class": "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
             "config": {
               "name": "splunk",
               "topics": [
                 "access"
               ],
               "enabled": true,
               "connection": {
                 "useSSL": false,
                 "host": "localhost",
                 "port": 8088
               },
               "buffering": {
                 "maxSize": 10000,
                 "writeInterval": "100 ms",
                 "maxBatchedEvents": 500
               },
               "authzToken": "<splunk-authorization-token>"
             }
           }
         ]
       }
     }
   }

2. Set the value of "authzToken" to the value of the authorization token returned in "To Set Up Splunk".

1. Access the route on http://openig.example.com:8080/splunk

2. Access the Splunk web interface on http://localhost:8000, and select Search & Reporting > Data Summary.

   Depending on how Splunk is configured, audit events are displayed on the web interface.

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

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

   The route contains a StaticResponseHandler to display a simple message.

2. Access the route a few times, on http://openig.example.com:8080/myroute1.

3. Query the Prometheus Scrape Endpoint at http://openig.example.com:8080/openig/metrics/prometheus.

   Metrics for myroute1 and _router are displayed:

   # HELP ig_router_deployed_routes Generated from Dropwizard metric import (metric=gateway._router.deployed-routes, type=gauge)
   # TYPE ig_router_deployed_routes gauge
   ig_router_deployed_routes{fully_qualified_name="gateway._router",heap="gateway",name="_router",} 1.0
   # HELP ig_route_request_active Generated from Dropwizard metric import (metric=gateway._router.route.default.request.active, type=gauge)
   # TYPE ig_route_request_active gauge
   ig_route_request_active{name="default",route="default",router="gateway._router",} 0.0
   # HELP ig_route_request_active Generated from Dropwizard metric import (metric=gateway._router.route.myroute1.request.active, type=gauge)
   # TYPE ig_route_request_active gauge
   ig_route_request_active{name="myroute1",route="myroute1",router="gateway._router",} 0.0
   # HELP ig_route_request_total Generated from Dropwizard metric import (metric=gateway._router.route.default.request, type=counter)
   # TYPE ig_route_request_total counter
   ig_route_request_total{name="default",route="default",router="gateway._router",} 0.0
   # HELP ig_route_response_error Generated from Dropwizard metric import (metric=gateway._router.route.default.response.error, type=counter)
   # TYPE ig_route_response_error counter
   ig_route_response_error{name="default",route="default",router="gateway._router",} 0.0
   # HELP ig_route_response_null Generated from Dropwizard metric import (metric=gateway._router.route.default.response.null, type=counter)
   # TYPE ig_route_response_null counter
   ig_route_response_null{name="default",route="default",router="gateway._router",} 0.0
   # HELP ig_route_response_status_total Generated from Dropwizard metric import (metric=gateway._router.route.default.response.status.client_error, type=counter)
   # TYPE ig_route_response_status_total counter
   ig_route_response_status_total{family="client_error",name="default",route="default",router="gateway._router",} 0.0
   ...

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

1. Set up IG and some example routes, as described in the first few steps of "To Monitor the Prometheus Scrape Endpoint".

2. Query the Forgerock Common REST Monitoring Endpoint at http://openig.example.com:8080/openig/metrics/api?_prettyPrint=true&_sortKeys=_id&_queryFilter=true

   Metrics for myroute1 are displayed:

   {
      "result" : [ {
      "_id" : "gateway._router.deployed-routes",
      "value" : 1.0,
      "_type" : "gauge"
      }, {
      "_id" : "gateway._router.route.default.request",
      "count" : 204,
      "_type" : "counter"
      }, {
      "_id" : "gateway._router.route.default.request.active",
      "value" : 0.0,
      "_type" : "gauge"
      }, {
   
     . . .
   
     _id" : "gateway._router.route.myroute1.response.status.unknown",
     "count" : 0,
     "_type" : "counter"
      }, {
      "_id" : "gateway._router.route.myroute1.response.time",
      "count" : 204,
      "max" : 0.420135,
      "mean" : 0.08624678327176545,
      "min" : 0.045079999999999995,
      "p50" : 0.070241,
      "p75" : 0.096049,
      "p95" : 0.178534,
      "p98" : 0.227217,
      "p99" : 0.242554,
      "p999" : 0.420135,
      "stddev" : 0.046611762381930474,
      "m15_rate" : 0.2004491450567003,
      "m1_rate" : 2.8726563452698075,
      "m5_rate" : 0.5974045160056258,
      "mean_rate" : 0.010877725092634833,
      "duration_units" : "milliseconds",
      "rate_units" : "calls/second",
      "total" : 17.721825,
      "_type" : "timer"
      } ],
      "resultCount" : 11,
      "pagedResultsCookie" : null,
      "totalPagedResultsPolicy" : "EXACT",
      "totalPagedResults" : 11,
      "remainingPagedResults" : -1
   }

3. Change the query to access metrics only for myroute1: http://openig.example.com:8080/openig/metrics/api?_prettyPrint=true&_sortKeys=_id&_queryFilter=_id+sw+"gateway._router.route.myroute1".

   Note that metric for the router, "_id" : "gateway._router.deployed-routes", is no longer displayed.

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

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

2. In the Create a route window, select Advanced Options and enter the following information, and then select Create route:

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

   • Condition: Path: /home/monitor

   • Name: 00-monitor

3. Select Statistics, and then enable statistics.

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

   {
     "name": "00-monitor",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/monitor')}",
     "monitor": {
       "enabled": true
     },
     "handler": "ReverseProxyHandler"
   }
       

   Notice the following features of the route:

   • The route matches requests to /home/monitor.

   • Each time the route is accessed, the ClientHandler passes the request to the sample application and IG collects metrics.

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.

6. Access the route a few times at http://openig.example.com:8080/home/monitor.

7. Go to the IG Route Monitoring Endpoint at http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-monitor/monitoring.

   The monitoring resource displays metrics for requests and responses:

   {
     "requests": {
       "total": 29,
       "active": 0
     },
     "responses": {
       "total": 29,
       "info": 0,
       "success": 29,
       "redirect": 0,
       "clientError": 0,
       "serverError": 0,
       "other": 0,
       "errors": 0,
       "null": 0
     },
     "throughput": {
       "mean": 2.1,
       "lastMinute": 0,
       "last5Minutes": 0,
       "last15Minutes": 0
     },
     "responseTime": {
       "mean": 4845.642,
       "median": 3552.415,
       "standardDeviation": 4236.919,
       "total": 140.836059,
       "percentiles": {
         "0.999": 25831.901,
         "0.9999": 25831.901,
         "0.99999": 25831.901
       }
     }
   }
   

1. Add the following script to the IG configuration as $HOME/.openig/scripts/groovy/BasicAuthResourceServerFilter.groovy (on Windows, %appdata%\OpenIG\scripts\groovy\BasicAuthResourceServerFilter.groovy): this script is a very simple implementation of the HTTP Basic Authentication mechanism.

   With such a filter, the endpoint /openig/metrics is not now protected through the standard HTTP Basic Authentication mechanism. It is possible to use here any kind of filter to protect that endpoint.

   /**
    * This scripts is a simple implementation of HTTP Basic Authentication on
    * server side.
    * It expects the following arguments:
    *  - realm: the realm to display when the user-agent prompts for
    *    username and password if none were provided.
    *  - username: the expected username
    *  - password: the expected password
    */
   
   import static org.forgerock.util.promise.Promises.newResultPromise;
   
   import java.nio.charset.Charset;
   import org.forgerock.util.encode.Base64;
   
   String authorizationHeader = request.getHeaders().getFirst("Authorization");
   if (authorizationHeader == null) {
       // No credentials provided, reply that they are needed.
       Response response = new Response(Status.UNAUTHORIZED);
       response.getHeaders().put("WWW-Authenticate", "Basic realm=\"" + realm + "\"");
       return newResultPromise(response);
   }
   
   String expectedAuthorization = "Basic " + Base64.encode((username + ":" + password).getBytes(Charset.defaultCharset()))
   if (!expectedAuthorization.equals(authorizationHeader)) {
       return newResultPromise(new Response(Status.FORBIDDEN));
   }
   // Credentials are as expected, let's continue
   return next.handle(context, request);
        

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

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

   {
     "heap": [{
       "name": "ClientHandler",
       "type": "ClientHandler"
     }, {
       "name": "MetricsProtectionFilter",
       "type": "ScriptableFilter",
       "config": {
         "type": "application/x-groovy",
         "file": "BasicAuthResourceServerFilter.groovy",
         "args": {
           "realm": "/",
           "username": "metric",
           "password": "password"
         }
       }
     }],
     "prefix": "openig"
   }
       

3. Restart IG to reload the configuration.

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. 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. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/throttle-simple

   • Name: 00-throttle-simple

4. Select  Throttling, and then enable throttling.

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

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

7. On the top-right of the screen, select  and  Display to view the route. The following route should be displayed:

   {
     "name": "00-throttle-simple",
     "monitor": false,
     "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 new 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.

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

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. Add the following CSV file as /tmp/userfile:

   UserId,status
   Alice,gold
   Bob,gold
   Carol,silver
   Dave,bronze

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

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

4. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/throttle-mapped

   • Name: 00-throttle-mapped

5. Select  Throttling, and then enable throttling.

6. Set up the grouping policy:

   1. In GROUPING POLICY, select to 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 the custom expression ${attributes.rate.UserId}.

   4. Save the grouping policy.

7. Set up the rate policy:

   1. In RATE POLICY, select Mapped.

   2. Select to map requests by custom criteria.

   3. Enter the custom expression ${attributes.rate.status}.

   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: sales.example.com

      • Number of requests: 3

      • Period: 10 seconds

   7. Save the rate policy.

8. Add the FileAttributesFilter:

   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. Insert the following FileAttributesFilter at the beginning of the chain and then save the route:

      {
        "type": "FileAttributesFilter",
        "config": {
           "file": "/tmp/userfile",
           "key": "UserId",
           "value": "${request.headers['UserId'][0]}",
           "target": "${attributes.rate}"
        }
      }

9. Select  and  Display to view the route. The following route should be displayed:

   {
     "name": "00-throttle-mapped",
     "monitor": false,
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/throttle-mapped')}",
     "capture": "all",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "FileAttributesFilter",
             "config": {
               "file": "/tmp/userfile",
               "key": "UserId",
               "value": "${request.headers['UserId'][0]}",
               "target": "${attributes.rate}"
             }
           },
           {
             "type": "ThrottlingFilter",
             "name": "ThrottlingFilter-1",
             "config": {
               "requestGroupingPolicy": "${attributes.rate.UserId}",
               "throttlingRatePolicy": {
                 "type": "MappedThrottlingPolicy",
                 "name": "MappedPolicy",
                 "config": {
                   "throttlingRateMapper": "${attributes.rate.status}",
                   "throttlingRatesMapping": {
                     "gold": {
                       "numberOfRequests": 6,
                       "duration": "10 s"
                     },
                     "silver": {
                       "numberOfRequests": 3,
                       "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 FileAttributesFilter uses the request header UserId and the CSV file to expose the user IDs and statuses in the target ${attributes.rate}.

     Whenever the CSV file is edited to change the user status, the throttling rate for the user is also changed.

   • The request grouping policy of the ThrottlingFilter groups requests by user ID. This means that the throttling rate is applied independently to each user ID.

   • The mapping policy applies a throttling rate to requests from users with gold or silver status. If the request does not have a mapped status, the mapping policy applies the default rate.

10. 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, access the following route in a loop: http://openig.example.com:8080/home/throttle-mapped.

   Accessing the route in a loop runs the request multiple times in quick succession, allowing you to test the throttling rate. You can use a command-line tool such as curl to run the following commands in quick succession or in a bash script:

   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "UserId:Alice" \
   > /tmp/Alice.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
    --header "UserId:Bob" \
   > /tmp/Bob.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "UserId:Carol" \
   > /tmp/Carol.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "UserId:Dave" \
   > /tmp/Dave.txt 2>&1

2. Search the output files to see the result for each user and each department:

   $ grep "< HTTP/1.1" /tmp/Alice.txt | sort | uniq -c
   
    6 < HTTP/1.1 200 OK
    4 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Bob.txt | sort | uniq -c
   
    6 < HTTP/1.1 200 OK
    4 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Carol.txt | sort | uniq -c
   
    3 < HTTP/1.1 200 OK
    7 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Dave.txt | sort | uniq -c
   
    1 < HTTP/1.1 200 OK
    9 < HTTP/1.1 429 Too Many Requests
   

   Notice that Alice and Bob, with gold status, are allowed six requests, and Carol, with silver status, is allowed three. This is consistent with the mapping in 00-throttle-mapped.json. Because Dave has the bronze status, which is not mapped, he gets the default rate.

3. Edit the CSV file to change the status of Alice from gold to silver, and then run the previous steps again.

   Notice that with a silver status, Alice is now allowed only three requests in 10 seconds.

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. Add the following CSV file as /tmp/userfile:

   UserId,status
   Alice,gold
   Bob,gold
   Carol,silver
   Dave,bronze

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

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

4. In the  Create a route window, select Advanced Options, enter the following information, and then select Create route:

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

   • Condition: Path: /home/throttle-scriptable

   • Name: throttle-scriptable

5. Select  Throttling, and then enable throttling.

6. Set up the grouping policy:

   1. In GROUPING POLICY, select to 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 the custom expression ${attributes.rate.UserId}.

   4. Save the grouping policy.

7. Set up the rate policy:

   1. In RATE POLICY, select Scripted.

   2. Select to create a new script, and name it X-User-Status. So that you can easily identify the script, use a name that describes the content of the script.

   3. Add the following argument/value pairs:

      • argument: status, value: "gold"

      • argument: rate, value: 6

      • argument: duration, value: "10 seconds"

   4. Replace the default script with the content of a valid Groovy script. For example, enter the following script:

      if (attributes.rate.status == status) {
        return new ThrottlingRate(rate, duration)
      } else {
        return null
      }

      Tip

      Alternatively, you can skip the step where you define arguments, and add the following script instead:

      if (attributes.rate.status == 'gold') {
        return new ThrottlingRate(6, '10 seconds')
      } else {
        return null
      }

      Note

      Studio does not check the validity of the Groovy script.

      When you save, the script is added to the list of reference scripts available to use in scriptable throttling filters.

   5. Enable the default rate, and set it to 1 request each 10 seconds.

   6. Save the rate policy.

8. Add the FileAttributesFilter:

   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. Insert the following FileAttributesFilter at the beginning of the chain and then save the route:

      {
        "type": "FileAttributesFilter",
        "config": {
           "file": "/tmp/userfile",
           "key": "UserId",
           "value": "${request.headers['UserId'][0]}",
           "target": "${attributes.rate}"
        }
      }

9. Select  and  Display to view the route. The following route should be displayed:

   {
     "name": "throttle-scriptable",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/throttle-scriptable')}",
     "monitor": false,
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "FileAttributesFilter",
             "config": {
               "file": "/tmp/userfile",
               "key": "UserId",
               "value": "${request.headers['UserId'][0]}",
               "target": "${attributes.rate}"
             }
           },
           {
             "name": "ThrottlingFilter-1",
             "type": "ThrottlingFilter",
             "config": {
               "requestGroupingPolicy": "${attributes.rate.UserId}",
               "throttlingRatePolicy": {
                 "type": "DefaultRateThrottlingPolicy",
                 "config": {
                   "delegateThrottlingRatePolicy": {
                     "name": "ScriptedPolicy",
                     "type": "ScriptableThrottlingPolicy",
                     "config": {
                       "type": "application/x-groovy",
                       "source": [
                         "if (attributes.rate.status == status) {",
                         "  return new ThrottlingRate(rate, duration)",
                         "} else {",
                         "  return null",
                         "}"
                       ],
                       "args": {
                         "status": "gold",
                         "rate": 10,
                         "duration": "10 seconds"
                       }
                     }
                   },
                   "defaultRate": {
                     "numberOfRequests": 1,
                     "duration": "10 s"
                   }
                 }
               }
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }

   Notice the following features of the new route:

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

   • The DefaultRateThrottlingPolicy delegates the management of throttling to the ScriptableThrottlingPolicy.

   • The script applies a throttling rate to requests from users with gold status. For all other requests, the script returns null and the default rate is applied.

10. 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, access the following route in a loop: http://openig.example.com:8080/home/throttle-scriptable.

   Accessing the route in a loop runs the request multiple times in quick succession, allowing you to test the throttling rate. You can use a command-line tool such as curl to run the following commands in quick succession or in a bash script:

   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "UserId:Alice" \
   > /tmp/Alice.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "UserId:Bob" \
   > /tmp/Bob.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "UserId:Carol" \
   > /tmp/Carol.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "UserId:Carol" \
   > /tmp/Carol.txt 2>&1

2. Search the output files to see the result for each user and each organization:

   $ grep "< HTTP/1.1" /tmp/Alice.txt | sort | uniq -c
   
   6 < HTTP/1.1 200 OK
   4 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Bob.txt | sort | uniq -c
   
   6 < HTTP/1.1 200 OK
   4 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Carol.txt | sort | uniq -c
   
   1 < HTTP/1.1 200 OK
   9 < HTTP/1.1 429 Too Many Requests
   
   $ grep "< HTTP/1.1" /tmp/Carol.txt | sort | uniq -c
   
   1 < HTTP/1.1 200 OK
   9 < HTTP/1.1 429 Too Many Requests

   Notice that Alice and Bob, with gold status, are allowed 6 requests, consistent with the value in the script. Carol and Dave, with silver and bronze status, get the default throttling rate.

1. In Studio, select ROUTES and then select a route.

2. On the left side of the screen, select  Capture, and then select capture options. You can capture the body and context of messages passing to and from the user agent, the protected application, and the ForgeRock Identity Platform.

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

4. Access the route, and then check $HOME/.openig/logs for a log file named by the route. The log file should contain the messages defined by your capture configuration.