Enforce policy decisions from AM

The following sections describe how to set up single sign on for requests in the same domain and in a different domain:

About policy enforcement

IG as a policy enforcement point (PEP) intercepts requests for a resource, and provides information about the request to AM.

AM as a policy decision point (PDP) evaluates requests based on their context and the configured policies. AM then returns decisions that indicate what actions are allowed or denied, as well as any advices, subject attributes, or static attributes for the specified resources.

After a policy decision, IG continues to process requests as follows:

If the request is allowed, processing continues.
If the request is denied with advices, IG checks whether it can respond to the advices. If IG can respond, it sends a redirect and information about how to meet the conditions in the advices.

By default, the request is redirected to AM. If the SingleSignOnFilter property loginEndpoint is configured, the request is redirected to that endpoint.
If the request is denied without advice, or if IG cannot respond to the advice, IG forwards the request to a failureHandler declared in the PolicyEnforcementFilter. If there is no failureHandler, IG returns a 403 Forbidden.
If an error occurs during the process, IG returns 500 Internal Server Error.

For more information, see PolicyEnforcementFilter and AM’s Authentication and SSO guide.

Enforce AM policy decisions in the same domain

The following procedure gives an example of how to create a policy in AM and configure an agent that can request policy decisions, when IG and AM are in the same domain.

Before you start, set up and test the example in Authenticate with SSO through the default authentication service.

Set up AM:
1. In the AM console, select Authorization > Policy Sets > New Policy Set, and add a policy set with the following values:
  - Id : PEP-SSO
  - Resource Types : URL
2. In the policy set, add a policy with the following values:
  - Name : PEP-SSO
  - Resource Type : URL
  - Resource pattern : *://*:*/*
  - Resource value : http://app.example.com:8081/home/pep-sso*
    
    This policy protects the home page of the sample application.
3. On the Actions tab, add an action to allow HTTP GET.
4. On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.

Set up IG:

Set an environment variable for the IG agent password, and then restart IG:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

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

Linux
Windows

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

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

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

Add the following route to IG:

Linux
Windows

$HOME/.openig/config/routes/04-pep.json

%appdata%\OpenIG\config\routes\04-pep.json

{
  "name": "pep-sso",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/pep-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://am.example.com:8088/openam/",
        "version": "7.2"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SingleSignOnFilter-1",
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "name": "PolicyEnforcementFilter-1",
          "type": "PolicyEnforcementFilter",
          "config": {
            "application": "PEP-SSO",
            "ssoTokenSubject": "${contexts.ssoToken.value}",
            "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.

For an example route that uses claimsSubject instead of ssoTokenSubject to identify the subject, see Example policy enforcement using claimsSubject.

Test the setup:
1. If you are logged in to AM, log out and clear any cookies.
2. Go to http://ig.example.com:8080/home/pep-sso.
  
  Because you have not previously authenticated to AM, the request does not contain a cookie with an SSO token. The SingleSignOnFilter redirects you to AM for authentication.
3. Log in to AM as user demo, password Ch4ng31t.
  
  When you have authenticated, AM redirects you back to the request URL, and IG requests a policy decision using the AM session cookie.
  
  AM returns a policy decision that grants access to the sample application.

Require users to authenticate to a specific realm

This example creates a policy that requires users to authenticate in a specific realm.

To reduce the attack surface on the top level realm, ForgeRock advises you to create federation entities, agent profiles, authorizations, OAuth2/OIDC, and STS services in a subrealm. For this reason, the AM policy, AM agent, and services are in a subrealm.

Set up AM:
1. In the AM console, click REALMS, and add a realm named alpha. Leave all other values as default.
  
  For the rest of the steps in this procedure, make sure you are managing the alpha realm by checking that the alpha icon is displayed on the top left.
2. (From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:
  - http://ig.example.com:8080/*
  - http://ig.example.com:8080/*?*
3. Select Applications > Agents > Identity Gateway, and add an agent with the following values:
  - Agent ID: ig_agent
  - Password: password
    
    For AM 6.5.x and earlier versions, set up an agent as described in Set up an IG agent in AM 6.5 and earlier.
4. Add a policy:
  1. Select Authorization > Policy Sets > New Policy Set, and add a policy set with the following values:
    
    Id : PEP-SSO-REALM
    
    Resource Types : URL
  2. In the policy set, add a policy with the following values:
    
    Name : PEP-SSO-REALM
    
    Resource Type : URL
    
    Resource pattern : *://*:*/*
    
    Resource value : http://app.example.com:8081/home/pep-sso-realm
    
    This policy protects the home page of the sample application.
  3. On the Actions tab, add an action to allow HTTP GET.
  4. On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.
  5. On the Environments tab, add an environment condition that requires the user to authenticate to the alpha realm:
    
    Type : Authentication to a Realm
    
    Authenticate to a Realm : /alpha

Set up IG:

Add the following route to IG:

Linux
Windows

$HOME/.openig/config/routes/04-pep-sso-realm.json

%appdata%\OpenIG\config\routes\04-pep-sso-realm.json

{
  "name": "pep-sso-realm",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/pep-sso-realm')}",
  "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://am.example.com:8088/openam/",
        "realm": "/alpha",
        "version": "7.2"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SingleSignOnFilter-1",
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "name": "PolicyEnforcementFilter-1",
          "type": "PolicyEnforcementFilter",
          "config": {
            "application": "PEP-SSO-REALM",
            "ssoTokenSubject": "${contexts.ssoToken.value}",
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Notice the following differences compared to 04-pep-sso.json:

The AmService is in the alpha realm. That means that the user authenticates to AM in that realm.
The PolicyEnforcementFilter realm is not specified, so it takes the same value as the AmService realm. If refers to a policy in the AM alpha realm.

Test the setup:
1. In a private browser, go to http://ig.example.com:8080/home/pep-sso-realm, and log in to AM as user demo, password Ch4ng31t.
  
  Because you are authenticating in the alpha realm, AM returns a policy decision that grants access to the sample application.
  
  If you were to send the request from a different realm, AM would redirect the request with an AuthenticateToRealmConditionAdvice.

Enforce AM policy decisions in different domains

The following procedure gives an example of how to create a policy in AM and configure an agent that can request policy decisions, when IG and AM are in different domains. This example uses IG in standalone mode, but can be adapted for web container mode.

Before you start, set up and test the example in Authenticate with CDSSO for IG in standalone mode.

Set up AM:
1. In the AM console, select Applications > Agents > Identity Gateway, and change the redirect URL for ig_agent_cdsso:
  - Redirect URL for CDSSO : https://ig.ext.com:8443/home/pep-cdsso/redirect
2. Select Authorization > Policy Sets > New Policy Set, and add a policy set with the following values:
  - Id : PEP-CDSSO
  - Resource Types : URL
    
    In the new policy set, add a policy with the following values:
  - Name : CDSSO
  - Resource Type : URL
  - Resource pattern : *://*:*/*
  - Resource value : http://app.example.com:8081/home/pep-cdsso*
    
    This policy protects the home page of the sample application.
  - On the Actions tab, add an action to allow HTTP GET.
  - On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.

Set up IG:

Set an environment variable for the IG agent password, and then restart IG:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

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

Linux
Windows

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

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

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

Add the following route to IG:

Linux
Windows

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

%appdata%\OpenIG\config\routes\04-pep-cdsso.json

{
  "name": "pep-cdsso",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/pep-cdsso')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent_cdsso",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/",
        "version": "7.2"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/home/pep-cdsso/redirect",
            "authCookie": {
              "path": "/home",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1"
          }
        },
        {
          "name": "PolicyEnforcementFilter-1",
          "type": "PolicyEnforcementFilter",
          "config": {
            "application": "PEP-CDSSO",
            "ssoTokenSubject": "${contexts.cdsso.token}",
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

For an example of how to set up a similar route in Studio, see Policy enforcement for CDSSO in Structured Editor.

Test the setup:
1. If you are logged in to AM, log out and clear any cookies.
2. Go to https://ig.ext.com:8443/home/pep-cdsso.
  
  If you see warnings that the site is not secure respond to the warnings to access the site.
  
  IG redirects you to AM for authentication.
3. Log in to AM as user demo, password Ch4ng31t.
  
  When you have authenticated, AM redirects you back to the request URL, and IG requests a policy decision. AM returns a policy decision that grants access to the sample application.

Using WebSocket notifications to evict the policy cache

When WebSocket notifications are enabled, IG receives notifications whenever AM creates, deletes, or changes a policy.

The following procedure gives an example of how to change the configuration in Enforce AM policy decisions in the same domain and Enforce AM policy decisions in different domains to evict outdated entries from the policy cache. For information about WebSocket notifications, see WebSocket notifications.

Set up and test the example in Enforce AM policy decisions in the same domain.
Websocket notifications are enabled by default. If they are disabled, enable them by adding the following configuration to the AmService in your route:
```
"notifications": {
  "enabled": true
}
```
Enable policy cache in the PolicyEnforcementFilter in your route:
```
"cache": {
  "enabled": true
}
```
In logback.xml add the following logger for WebSocket notifications, and then restart IG:
```
<logger name="org.forgerock.openig.tools.notifications.ws" level="TRACE" />
```
For information, see Changing the log level for different object types.
Go to http://ig.example.com:8080/home/pep-sso, and log in to AM as user demo, password Ch4ng31t.
In a seperate terminal, log on to AM as admin, and change the PEP-SSO policy. For example, in the Actions tab, add an action to allow HTTP DELETE.

Note that the IG system logs are updated with Websocket notifications about the change:

... | TRACE | vert.x-eventloop-thread-2 | o.f.o.t.n.w.SubscriptionService | @system | Received a message: { "topic": "/agent/policy", "timestamp": ..., "body": { "realm": "/", "policy": "PEP-SSO", "policySet": "PEP-SSO", "eventType": "UPDATE" } }
... | TRACE | vert.x-eventloop-thread-2 | o.f.o.t.n.w.SubscriptionService | @system | Received a notification: { "topic": "/agent/policy", "timestamp": ..., "body": { "realm": "/", "policy": "PEP-SSO", "policySet": "PEP-SSO", "eventType": "UPDATE" } }

Identity Gateway 7.2

Enforce policy decisions from AM

About policy enforcement

Enforce AM policy decisions in the same domain

Require users to authenticate to a specific realm

Enforce AM policy decisions in different domains

Using WebSocket notifications to evict the policy cache