Requiring authentication to an PingAM 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, 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 admin UI, 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. Select Services > Add a Service and add a Validation Service with the following Valid goto URL Resources:
  - https://ig.example.com:8443/*
  - https://ig.example.com:8443/*?*
3. Register a PingGateway agent with the following values, as described in Register a PingGateway agent in AM:
  - Agent ID: ig_agent
  - Password: password
    
    Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.
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 : https://app.example.com:8444/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 PingGateway:

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).
Make sure PingGateway connects to the sample application over HTTPS with a route to access static resources.

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

Add the following route to PingGateway:

Linux: $HOME/.openig/config/routes/04-pep-sso-realm.json
Windows: %appdata%\OpenIG\config\routes\04-pep-sso-realm.json

{
  "name": "pep-sso-realm",
  "baseURI": "https://app.example.com:8444",
  "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"
      }
    }
  ],
  "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"
    }
  }
}

Source: 04-pep-sso-realm.json

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 isn’t 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 your browser’s privacy or incognito mode, go to https://ig.example.com:8443/home/pep-sso-realm and accept the server certificate.
2. Sign on to AM as user demo, password Ch4ng31t.
  
  When you authenticate in the alpha realm, AM returns a policy decision that grants access to the sample application.
  
  If you sent the request from a different realm, AM would redirect the request with an AuthenticateToRealmConditionAdvice.