Authenticating With SSO

This procedure gives an example of how to set up SSO, where AM on openam.example.com authenticates users that are processed by IG on openig.example.com.

Before you start, prepare AM, IG, and the sample application as described in "Example Installation for This Guide".

1. Set up AM:

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

   2. (For AM 6.5.3 and later versions) Select  Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:

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

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

   3. Select Applications > Agents > Identity Gateway, add an agent with the following values:

      • Agent ID: ig_agent

      • Password: password

      Leave all other values as default.

      See how to set up an agent in AM 6.5.2 and earlier versions.

      1. Select Applications > Agents > Java (or J2EE).

      2. Add an agent with the following values:

         • Agent ID: ig_agent

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

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

         • Password: password

      3. On the Global tab, deselect Agent Configuration Change Notification.

         This option stops IG from being notified about agent configuration changes in AM, because they are not required by IG.

   4. Select Configure > Global Services > Platform, and add example.com as an AM cookie domain.

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

2. Set up IG:

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

      $ export AGENT_SECRET_ID='cGFzc3dvcmQ='

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

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

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

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

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

   3. Add the following route to IG:

      $HOME/.openig/config/routes/sso.json

      %appdata%\OpenIG\config\routes\sso.json

      {
        "name": "sso",
        "baseURI": "http://app.example.com:8081",
        "condition": "${matches(request.uri.path, '^/home/sso$')}",
        "heap": [
          {
            "name": "SystemAndEnvSecretStore-1",
            "type": "SystemAndEnvSecretStore"
          },
          {
            "name": "AmService-1",
            "type": "AmService",
            "config": {
              "agent": {
                "username": "ig_agent",
                "passwordSecretId": "agent.secret.id"
              },
              "secretsProvider": "SystemAndEnvSecretStore-1",
              "url": "http://openam.example.com:8088/openam/",
              "version": "7"
            }
          }
        ],
        "handler": {
          "type": "Chain",
          "config": {
            "filters": [
              {
                "name": "SingleSignOnFilter-1",
                "type": "SingleSignOnFilter",
                "config": {
                  "amService": "AmService-1"
                }
              }
            ],
            "handler": "ReverseProxyHandler"
          }
        }
      }
      

      For information about how to set up the IG route in Studio, see "Policy Enforcement in Structured Editor" or "Protecting a Web App With Freeform Designer".

3. Test the setup:

   1. If you are logged in to AM, log out and clear any cookies.

   2. Go to http://openig.example.com:8080/home/sso.

      The SingleSignOnFilter redirects the request to AM for authentication.

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

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

This procedure gives an example of how to authenticate by using SSO and the example authentication tree provided in AM, instead of the default authentication service.

1. Set up the example in "Authenticate With SSO".

2. Add the following route to IG:

   $HOME/.openig/config/routes/sso-authservice.json

   %appdata%\OpenIG\config\routes\sso-authservice.json

   {
     "name": "sso-authservice",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(request.uri.path, '^/home/sso-authservice')}",
     "heap": [
       {
         "name": "SystemAndEnvSecretStore-1",
         "type": "SystemAndEnvSecretStore"
       },
       {
         "name": "AmService-1",
         "type": "AmService",
         "config": {
           "agent": {
             "username": "ig_agent",
             "passwordSecretId": "agent.secret.id"
           },
           "secretsProvider": "SystemAndEnvSecretStore-1",
           "url": "http://openam.example.com:8088/openam/",
           "version": "7"
         }
       }
     ],
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "SingleSignOnFilter-1",
             "type": "SingleSignOnFilter",
             "config": {
               "amService": "AmService-1",
               "authenticationService": "Example"
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }
   

   Notice the features of the route compared to sso.json:

   • The route matches requests to /home/sso-authservice.

   • The authenticationService property of SingleSignOnFilter refers to Example, the name of the example authentication tree in AM. This authentication tree is used for authentication instead of the AM XUI.

3. Test the setup:

   1. If you are logged in to AM, log out and clear any cookies.

   2. Go to http://openig.example.com:8080/home/sso-authservice, and note that the login page is different to that returned in "Authenticate With SSO".