---
title: Requiring authentication to an PingAM realm
description: Configure PingGateway to enforce a policy requiring users to authenticate to a specific PingAM realm before accessing a protected resource
component: pinggateway
version: 2026
page_id: pinggateway:gateway-guide:pep-sso-realm
canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/pep-sso-realm.html
revdate: 2025-10-15T18:45:22Z
---

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

1. Set up AM:

   1. In the AM admin UI, click [icon: cloud, set=fa]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 [icon: cloud, set=fa]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](preface.html#register-agent-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 [icon: key, set=fa]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 [icon: cloud, set=fa]alpha realm:

         * Type : `Authentication to a Realm`

         * Authenticate to a Realm : `/alpha`

2. Set up PingGateway:

   1. Set up PingGateway for HTTPS, as described in [Configure PingGateway for TLS (server-side)](../installation-guide/securing-connections.html#server-side-tls).

   2. Make sure PingGateway connects to the sample application over HTTPS with a route to access static resources.

      Learn more in [Using the sample application](../getting-started/start-sampleapp.html).

   3. Set an environment variable for the PingGateway agent password, and then restart PingGateway:

      ```console
      $ export AGENT_SECRET_ID='cGFzc3dvcmQ='
      ```

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

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

      ```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](../_attachments/config/routes/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.

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