Web Agents 2024.11

Policy enforcement

The agent evaluates policies as defined by the Policy evaluation mode (AM_POLICY_CACHE_MODE) environment variable. For information about caching policy decisions, refer to Caches.

This example sets up AM as a policy decision point for requests processed by Web Agent. Before you start, install a Web Agent as described in the Installation, with the following values:

  • AM server URL: https://am.example.com:8443/am

  • Agent URL: https://agent.example.com:443

  • Agent profile name: web-agent

  • Agent profile realm: /

  • Agent profile password: /secure-directory/pwd.txt

Enforce a policy decision from AM

  1. Using the PingAM documentation for information, log in to AM as an administrator, and make sure you are managing the / realm.

  2. Add a Web Agent profile:

    1. In the AM admin UI, select Applications > Agents > Web.

    2. Add an agent with the following values:

      • Agent ID: web-agent

      • Agent URL: https://agent.example.com:443

      • Server URL: https://am.example.com:8443/am

      • Password: password

  3. Add a policy set and policy:

    1. In the AM admin UI, select Authorization > Policy Sets, and add a policy set with the following values:

      • Id : PEP

      • Resource Types : URL

    2. In the policy set, add a policy with the following values:

      • Name : PEP-policy

      • Resource Type : URL

      • Resources : *://*:*/*

    3. On the Actions tab, add actions to allow HTTP GET and POST.

    4. On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.

  4. Assign the new policy set to the agent profile:

    1. In the AM admin UI, Select Applications > Agents > Web, and select your agent.

    2. On the agent page, select the AM Services tab.

    3. Set Policy Set to PEP, and then click Save.

  5. Test the setup:

    1. In the AM admin UI, select Identities > Add Identity, and add a user with the following values:

      • Username : demo

      • First name : demo

      • Last name : user

      • Email Address : demo@example.com

      • Password : Ch4ng31t

    2. Log out of AM, and clear any cookies.

    3. Go to https://agent.example.com:443. The AM login page is displayed.

    4. Log in to AM as user demo, password Ch4ng31t, to access the web page protected by the Web Agent.

Retrieve advice or response attributes from policy decisions

When AM makes a policy decision, it communicates an entitlement to the agent, which can optionally include advice and response attributes.

When AM denies a request with advice, the agent uses the advice to take remedial action. For example, when AM denies a request because the authentication level is too low, it can send advice to increase the authentication level. The agent then prompts the user to reauthenticate at a higher level, for example, by using a one-time password.

When AM allows a request it can include the following types of response attributes in the entitlement:

  • Subject response attributes: Any LDAP user attribute configured for the identity store where AM looks up the user’s profile. Learn more in Identity stores in AM’s Setup guide.

    The agent adds the listed attributes to the response.

  • Static response attributes: Any key:value pair, for example, FrequentFlyerStatus: gold.

    Depending on the value of Response Attribute Map, and Response Attribute Fetch Mode, the agent adds the listed attributes to HTTP headers or HTTP cookies in the response.

This example builds on the example in Enforce a policy decision from AM. Set up and test that example first.

  1. Configure subject response attributes and static response attributes in the AM policy you created earlier:

    1. In the AM admin UI, select the PEP-policy, and go to the Response Attributes tab.

    2. In the SUBJECT ATTRIBUTES frame, select one or more of the available attributes. For example, select cn.

    3. In the STATIC ATTRIBUTES frame, add a response attribute pair. For example, add the following pair:

      • PROPERTY NAME: FrequentFlyerStatus

      • PROPERTY VALUE: gold

    4. Click Save Changes.

  2. In the AM admin UI, select the web-agent you created earlier.

    The agent must use the AM policy set and realm where the response attributes are configured.

    If the response attributes are not present in the policy decision from AM, the agent does not create the corresponding HTTP header or cookie.

  3. In the Application tab, set Response Attribute Fetch Mode to HTTP-HEADER or HTTP-COOKIE to select whether to map response attribute names to HTTP header names or HTTP cookie names.

    Learn more in Response Attribute Fetch Mode.

  4. In the Response Attribute Map field, map the subject response attributes you selected in AM:

    • Key: cn

    • Value: CUSTOM-name

      The name of the AM response attribute cn is mapped to the HTTP header or cookie called CUSTOM-name. The value is taken from the user profile.

      Learn more in Response Attribute Fetch Mode.

  5. In the Response Attribute Map field, map the static response attributes you added in AM:

    • Key: FrequentFlyerStatus

    • Value: CUSTOM-flyer-status

      The name of the AM response attribute FrequentFlyerStatus is mapped to the HTTP header or cookie called CUSTOM-flyer-status. The value is gold.

      Learn more in Response Attribute Map