Follow these steps to install IG:

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

2. Copy (or move) and rename the .war file to the root context of the web application container:

   • For Jetty, name the .war file root.war. Jetty automatically deploys IG in the root context on startup.

   • For Tomcat, name the .war file ROOT.war.

   • 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 OPENIG_BASE env variable or openig.base 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"

By default, IG operates in development mode. After creating your configuration in development mode, switch to production mode to prevent any unwanted changes:

1. Add the following file to the IG configuration as $HOME/.openig/config/admin.json.

   On Windows, add the file to %appdata%\OpenIG\config:

   {
     "mode": "PRODUCTION"
   }

   The file changes the operating mode from the default value of DEVELOPMENT, used when you don't provide an admin.json file, to PRODUCTION.

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

2. Prevent routes from being reloaded after startup:

   • To prevent all routes in the configuration from being reloaded, edit the main router in config.json.

   • To prevent individual routes from being reloaded, edit 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 routes endpoint is not available and is not displayed in the log. When you try to access IG Studio on http://openig.example.com:8080/openig/studio, an HTTP 404 is returned.

Follow these steps to prepare the database:

1. On the system where IG runs, download and unpack H2 database.

2. Start H2:

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

   H2 starts, listening on port 8082, and opens a browser console page.

3. In the browser console page, select Generic H2 (Server) under Saved Settings. This sets the Driver Class, org.h2.Driver, the JDBC URL, jdbc:h2:tcp://localhost/~/test, the User Name, sa.

   In the Password field, type password.

   Then click Connect to access the console.

4. Run a statement to create a users table based on the user file from "Log in With Credentials From a File".

   If you have not created the user file on your system, put the following content 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
   

   Then create the users table through the H2 console:

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

   On success, the table should contain the same users as the file. You can check this by running SELECT * FROM users; in the H2 console.

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

1. Configure Jetty for JNDI.

   For the version of Jetty used in this sample, stop Jetty and add the following lines to /path/to/jetty/start.ini:

   # ===========================================================
   # 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. To add the route, 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": "ClientHandler"
       }
     },
     "condition": "${matches(request.uri.path, '^/sql')}"
   }
   

   On Windows, the file name should be %appdata%\OpenIG\config\routes\03-sql.json.

2. Notice the following features of the new route:

   • The SqlAttributesFilter 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 PasswordReplayFilter's request retrieves the username and password from the attributes map and replaces your browser's original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate.

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

   • The route matches requests to /sql.

With H2, Jetty, and IG correctly configured, you can try it out:

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

  IG logs you in automatically as George.

Create a text file containing the password specified in "To Create a Policy Agent Profile in AM".

1. Create the password file:

   $ echo password > /tmp/pwd.txt

   On Windows:

   C:\> echo password > pwd.txt

2. Protect the password file:

   $ chmod 400 /tmp/pwd.txt

   In Windows Explorer, right-click the created password file, select Read-Only, and then select OK.

In this procedure you generate a DES shared key in IG that you then use later in the AM and IG configuration.

When you configure password capture and replay, an AM policy agent shares captured passwords with IG. Before communicating passwords to IG, however, AM encrypts them with a DES shared key. IG uses the DES shared key to decrypt the shared passwords.

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.

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

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:

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

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 browse to Subjects.

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

   • ID: george

   • Last Name: costanza

   • Full Name: george costanza

   • Password: costanza

For more information about configuring policy agents in AM, see Configuring Java EE Policy Agents in the ForgeRock Access Management Java EE Policy Agent User's Guide.

1. In the top-level realm, select Applications > Agents > J2EE.

2. Add an agent with the following values:

   • Name: JavaEE

   • Password: password

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

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

3. Edit the agent profile to add these settings, making sure to save your changes in each tab:

   • On the Global settings tab, select General, and change the Agent Filter Mode from ALL to SSO_ONLY.

   • On the Application tab, select Session Attributes Processing, and change the following values:

     • Session Attribute Fetch Mode: Change from NONE to HTTP_HEADER.

     • Session Attribute Mapping: Add [UserToken]=username and [sunIdentityUserPassword]=password.

   Note

   If you plan to use ForgeRock Common REST to create or edit routes, on the Application tab, under Not Enforced URI Processing, add /openig/api/*.

   This step adds the URL pattern for Common REST requests to the list of not-enforced URIs. The policy agent bypasses requests that match this URL pattern, granting them access without requiring authentication.

   For information about managing routes through Common REST, see " Creating and Editing Routes Through Common REST ".

For more information about configuring policy agents in AM, see Configuring Java EE Policy Agents in the ForgeRock Access Management Java EE Policy Agent User's Guide.

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

   1. In the top level realm, select Authentication > Settings > Post Authentication Processing.

   2. Add the following class to Authentication Post Processing Classes, and then save the changes: 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. Restart AM.

For more information about how to install the AM policy agent, see To Install the Policy Agent into Jetty in the ForgeRock Access Management Java EE Policy Agent User's Guide.

1. Make sure that IG is stopped and AM is running.

2. Download and then unzip the AM Java EE policy agent in the directory alongside IG. For example, in the /path/to directory.

   A /path/to/j2ee_agents directory is created.

3. Install the agent with a command similar to this:

   $ /path/to/j2ee_agents/jetty_v7_agent/bin/agentadmin --install --acceptLicense

   You are prompted to enter information about the installation.

4. Answer the prompts with the following hints:

   • Jetty Server Config Directory: /path/to/jetty/etc

   • Jetty installation directory: /path/to/jetty

   • AM server URL: http://openam.example.com:8088/openam

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

   • Agent Profile Name: JavaEE

   • Agent Profile Password file name : /tmp/pwd.txt

5. Add the following filter configuration to /path/to/jetty/etc/webdefault.xml:

   <filter>
     <filter-name>Agent</filter-name>
     <display-name>Agent</display-name>
     <description>OpenAM Policy Agent Filter</description>
     <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
   </filter>
   
   <filter-mapping>
     <filter-name>Agent</filter-name>
     <url-pattern>/replay</url-pattern>
     <dispatcher>REQUEST</dispatcher>
     <dispatcher>INCLUDE</dispatcher>
     <dispatcher>FORWARD</dispatcher>
     <dispatcher>ERROR</dispatcher>
   </filter-mapping>
   

6. To test the setup of the policy agent, start IG, and browse to http://openig.example.com:8080/replay.

   You should be redirected to AM for authentication, but do not log in yet.

1. Add the following route to IG configuration as $HOME/.openig/config/routes/04-replay.json:

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

   {
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "PasswordReplayFilter",
             "config": {
               "loginPage": "${true}",
               "headerDecryption": {
                 "algorithm": "DES/ECB/NoPadding",
                 "key": "DESKEY",
                 "keyType": "DES",
                 "charSet": "utf-8",
                 "headers": [
                   "password"
                 ]
               },
               "request": {
                 "method": "POST",
                 "uri": "http://app.example.com:8081/login",
                 "form": {
                   "username": [
                     "${request.headers['username'][0]}"
                   ],
                   "password": [
                     "${request.headers['password'][0]}"
                   ]
                 }
               }
             }
           },
           {
             "type": "HeaderFilter",
             "config": {
               "messageType": "REQUEST",
               "remove": [
                 "password",
                 "username"
               ]
             }
           }
         ],
         "handler": "ClientHandler"
       }
     },
     "condition": "${matches(request.uri.path, '^/replay')}"
   }
   

2. Edit the route to change DESKEY to the actual key value that you generated in "To Create a DES Shared Key In IG".

   Notice the following features of the new route:

   • The route matches requests to /replay.

   • The PasswordReplayFilter uses the headerDecryption information to decrypt the password that AM captured and encrypted, and that the AM policy agent included in the headers for the request.

     The headerDecryption object uses the DES shared key value that you generated.

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

   • The HeaderFilter removes the username and password headers before continuing to process the request.

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 george, password costanza.

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

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 browse to Subjects.

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

   • ID: george

   • Last Name: costanza

   • Full Name: george costanza

   • Password: costanza

3. In the User window, select the new user and 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 IG 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 ClientHandler to submit the request to the sample application.

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

   {
     "name" : "rs-pwreplay",
     "monitor" : false,
     "baseURI" : "http://app.example.com:8081",
     "condition" : "${matches(request.uri.path, '^/rs-pwreplay')}",
     "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" : {
                 "endpoint" : "http://openam.example.com:8088/openam/oauth2/tokeninfo"
               }
             }
           }
         },
           {
             "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": "ClientHandler"
       }
     }
   }

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 browse to Subjects.

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

   • ID: george

   • Last Name: costanza

   • Full Name: george costanza

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

      • ID Token Signing Algorithm: 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. Make sure that your config.json has a main router named _router.

1. Access IG Studio on 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:

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

   • Condition: Path: /home/id_token

   • Name: 07-openid

3. Select Create route.

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

6. Select Save.

   The  icon in the OpenID Connect panel indicates that OpenID Connect is configured. Select the panel again to edit your settings.

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

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 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 ClientHandler redirects the request to the home page of the sample application.

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

1. Edit config.json to comment the baseURI in the top-level handler. The handler declaration appears as follows:

   {
       "handler": {
           "type": "Router",
           "name": "_router",
           "_baseURI": "http://app.example.com:8081",
           "capture": "all"
       }
   }

   Restart IG for the changes to take effect.

2. Add the following route to the IG configuration as $HOME/.openig/config/routes/50-idtoken.json

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

   {
     "heap": [
       {
         "name": "openam",
         "type": "ClientRegistration",
         "config": {
           "clientId": "oidc_client",
           "clientSecret": "password",
           "issuer": {
             "type": "Issuer",
             "config": {
               "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
             }
           },
           "scopes": [
             "openid",
             "profile",
             "email"
           ]
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "OAuth2ClientFilter",
             "config": {
               "clientEndpoint": "/home/id_token",
               "requireHttps": false,
               "requireLogin": true,
               "registrations": "openam",
               "target": "${attributes.openid}",
               "failureHandler": {
                 "type": "StaticResponseHandler",
                 "config": {
                   "entity": "OAuth2ClientFilter failed...",
                   "reason": "NotFound",
                   "status": 500
                 }
               }
             }
           }
         ],
         "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
           }
         }
       }
     },
     "condition": "${matches(request.uri.path, '^/home/id_token')}"
   }

   Notice the following features of the route:

   • The route matches requests to /home/id_token.

   • The client registration is defined in the heap. The registration holds configuration parameters provided during " To Set Up AM as an OpenID Connect Provider ", and IG uses these parameters to connect with AM.

   • 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}. This is where subsequent filters and handlers can find access tokens and user information.

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

3. To prevent conflicts with the route you set up in "Acting As an OAuth 2.0 Client or OpenID Connect Relying Party", rename the route 07-openid.json to 07-openid.json.old

4. With IG running, access http://openig.example.com:8080/home/id_token.

   The AM login screen is displayed.

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

   An OpenID Connect request to access private information is displayed.

6. Select Allow.

   The id_token is displayed above an empty placeholder for the SAML assertion.

   {"id_token":
   "eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAiYXRfaGFzaCI6ICJ . . ."}
   
   {"saml_assertions":
   ""}

1. Add the following filter in the chain of 50-idtoken.json, after the OAuth2ClientFilter. An example of the edited route is at the end of this procedure.

   {
     "type": "TokenTransformationFilter",
     "config": {
       "openamUri": "http://openam.example.com:8088/openam",
       "username": "oidc_client",
       "password": "password",
       "idToken": "${attributes.openid.id_token}",
       "instance": "openig",
       "ssoTokenHeader": "iPlanetDirectoryPro"
     }
   }

   Notice the following features of the new filter:

   • Requests from this filter are made to http://openam.example.com:8088/openam.

   • The username and password are for the AM subject set up in " To Set Up AM as an OpenID Connect Provider ".

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

2. With IG running, access http://openig.example.com:8080/home/id_token.

   The SAML assertions are displayed under the id_token.

   {"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 subjects in the top-level realm:

1. In the top-level realm, select Subjects.

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

   • ID: alice

   • First Name: Alice

   • Last Name: User

   • Full Name: Alice User

   • Password: password

   • User Status: Active

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

   • ID: bob

   • First Name: Bob

   • Last Name: User

   • Full Name: Bob User

   • Password: password

   • User Status: Active

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",
           "authorizationServerUri": "http://openam.example.com:8088/openam/", 
           "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. It uses 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-5.5.2.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-5.5.2.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 CREST:

   • 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 CREST:

   • 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 LDAP authentication script, follow these steps:

1. Install an LDAP directory server such as ForgeRock Directory Services.

   Either import some sample users who can authenticate over LDAP, or generate sample users at installation time.

2. Save the script as $HOME/.openig/scripts/groovy/LdapAuthFilter.groovy (%appdata%\OpenIG\scripts\groovy\LdapAuthFilter.groovy on Windows).

   If the directory server installation does not match the assumptions made in the script, adjust the script to use the correct settings for your installation.

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

   {
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "ScriptableFilter",
             "config": {
               "type": "application/x-groovy",
               "file": "LdapAuthFilter.groovy"
             }
           }
         ],
         "handler": {
           "type": "ScriptableHandler",
           "config": {
             "type": "application/x-groovy",
             "source": [
               "dn = request.headers['Ldap-User-Dn'].values[0]",
               "entity = '<html><body><p>Ldap-User-Dn: ' + dn + '</p></body></html>'",
               "",
               "response = new Response(Status.OK)",
               "response.entity = entity",
               "return response"
             ]
           }
         }
       }
     },
     "condition": "${matches(request.uri.path, '^/ldap')}"
   }
   

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": "ClientHandler"
       }
     },
     "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. Access IG Studio on 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. In Percentiles, remove the default percentiles, add the percentiles 0.25, 0.5, and 0.75, and then select Save.

   These are example values. Alternatively, use the default values or other values.

5. On the top-right of the screen, select ⋮ > Display, and review the route. The following route should be displayed.

   {
     "name": "00-monitor",
     "baseURI": "http://app.example.com:8081",
     "monitor": {
       "enabled": true,
       "percentiles": [
         0.25,
         0.5,
         0.75
       ]
     },
     "condition": "${matches(request.uri.path, '^/home/monitor')}",
     "handler": "ClientHandler"
   }

   Notice the following features of the new 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 statistics.

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.

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

8. Go to the monitoring endpoint for the route, at http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-monitor/monitoring.

   The monitoring resource displays statistics for requests and responses, as in the following example:

   {
       "requests": {
           "active": 0,
           "total": 3
       },
       "responseTime": {
           "mean": 0.108,
           "median": 0.109,
           "percentiles": {
               "0.25": 0.085,
               "0.5": 0.109,
               "0.75": 0.13
           },
           "standardDeviation": 0.018,
           "total": 0
       },
       "responses": {
           "clientError": 0,
           "errors": 0,
           "info": 0,
           "null": 0,
           "other": 0,
           "redirect": 0,
           "serverError": 0,
           "success": 3,
           "total": 3
       },
       "throughput": {
           "last15Minutes": 0.0,
           "last5Minutes": 0.0,
           "lastMinute": 0.0,
           "mean": 0.1
       }
   }
   

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide. Make sure that your config.json has a main router named _router.

1. Access IG Studio on http://openig.example.com:8080/openig/studio, and select  Protect an Application.

2. In the Create 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/throttle-simple

   • Name: 00-throttle-simple

3. Select  Throttling, and then enable throttling.

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

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

5. In RATE POLICY, select  and allow 6 requests each 10 seconds.

6. 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": "ClientHandler"
       }
     }
   }

   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.

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

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

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

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

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

2. Search the output file to see the result:

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

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

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide. Make sure that your config.json has a main router named _router.

1. Access IG Studio on http://openig.example.com:8080/openig/studio, and select  Protect an Application.

2. In the Create 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/throttle-mapped

   • Name: 00-throttle-mapped

3. Select  Throttling, and then enable throttling.

4. 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 ${request.headers['UserId'][0]} to evaluate to the first UserID in the request header.

   4. Save the grouping policy.

5. Set up the rate policy:

   1. In RATE POLICY, select Mapped.

   2. Select to map requests by custom criteria.

   3. Enter the custom expression ${request.headers['X-Forwarded-For'][0]} to evaluate to the first value of the request header X-Forwarded-For, representing the hostname of the department.

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

   5. In Mapped Rates, add the following rate for the accounts department:

      • Match Value: accounts.example.com

      • Number of requests: 6

      • Period: 10 seconds

   6. Add a different rate for the sales department:

      • Match Value: sales.example.com

      • Number of requests: 3

      • Period: 10 seconds

   7. Save the rate policy.

6. 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')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "type": "ThrottlingFilter",
             "name": "ThrottlingFilter-1",
             "config": {
               "requestGroupingPolicy": "${request.headers['UserId'][0]}",
               "throttlingRatePolicy": {
                 "type": "MappedThrottlingPolicy",
                 "name": "MappedPolicy",
                 "config": {
                   "throttlingRateMapper": "${request.headers['X-Forwarded-For'][0]}",
                   "throttlingRatesMapping": {
                     "accounts.example.com": {
                       "numberOfRequests": 6,
                       "duration": "10 s"
                     },
                     "sales.example.com": {
                       "numberOfRequests": 3,
                       "duration": "10 s"
                     }
                   },
                   "defaultRate": {
                     "numberOfRequests": 1,
                     "duration": "10 s"
                   }
                 }
               }
             }
           }
         ],
         "handler": "ClientHandler"
       }
     }
   }

   Notice the following features of the new route:

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

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

   • The mapping policy maps different throttling rates for each department. If the request does not come from a mapped department, the default rate is applied.

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

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

1. With IG and the sample application running, 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 "X-Forwarded-For:accounts.example.com" \
   --header "UserId:Alice" \
   > /tmp/Alice.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "X-Forwarded-For:accounts.example.com" \
   --header "UserId:Bob" \
   > /tmp/Bob.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "X-Forwarded-For:sales.example.com" \
   --header "UserId:Carol" \
   > /tmp/Carol.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-mapped/\[01-10\] \
   --header "X-Forwarded-For:finance.example.com" \
   --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 the first six requests from Alice and Bob in accounts are successful, and the first three requests from Carol in sales are successful, consistent with the mapping in 00-throttle-mapped.json. Requests from finance are not mapped, and therefore receive the default rate.

Before you start, prepare IG and the sample application as described in "First Steps" in the Getting Started Guide. Make sure that your config.json has a main router named _router.

1. Access IG Studio on http://openig.example.com:8080/openig/studio, and select  Protect an Application.

2. In the Create 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/throttle-scriptable

   • Name: throttle-scriptable

3. Select  Throttling, and then enable throttling.

4. 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 ${request.headers['UserId'][0]} to evaluate to the first UserID in the request header.

   4. Save the grouping policy.

5. Set up the rate policy:

   1. In RATE POLICY, select Scripted.

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

      For information about using a reference script instead, see "To Create a Reference Script".

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

      if (request.headers['X-Forwarded-For'].values[0]  == 'accounts.example.com') {
        return new ThrottlingRate(6, '10 seconds')
      } else {
        return null
      }

      Note

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

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

   5. Save the rate policy.

6. 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": [
           {
             "name": "ThrottlingFilter-1",
             "type": "ThrottlingFilter",
             "config": {
               "requestGroupingPolicy": "${request.headers['UserId'][0]}",
               "throttlingRatePolicy": {
                 "type": "DefaultRateThrottlingPolicy",
                 "config": {
                   "delegateThrottlingRatePolicy": {
                     "name": "ScriptedPolicy",
                     "type": "ScriptableThrottlingPolicy",
                     "config": {
                       "type": "application/x-groovy",
                       "source": [
                         "if (request.headers['X-Forwarded-For'].values[0]  == 'accounts.example.com') {",
                         "  return new ThrottlingRate(6, '10 seconds')",
                         "  } else {",
                         "  return null",
                         "}"
                       ]
                     }
                   },
                   "defaultRate": {
                     "numberOfRequests": 1,
                     "duration": "10 s"
                   }
                 }
               }
             }
           }
         ],
         "handler": "ClientHandler"
       }
     }
   }

   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 the accounts department of example.com. For all other requests, the script returns null and the default rate is applied.

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

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

1. With IG and the sample application running, 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 "X-Forwarded-For:accounts.example.com" \
   --header "UserId:Alice" \
   > /tmp/Alice.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "X-Forwarded-For:accounts.example.com" \
   --header "UserId:Bob" \
   > /tmp/Bob.txt 2>&1
   
   $ curl -v http://openig.example.com:8080/home/throttle-scriptable/\[01-10\] \
   --header "X-Forwarded-For:sales.example.com" \
   --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
   

   Notice that the first six requests from Alice and Bob in accounts are successful, consistent with the value in the script. The script returns null for requests from Carol in sales, so those requests receive the default throttling rate.