Java Agents 2024.3

Policy enforcement

This example sets up AM as a policy decision point for requests processed by Java Agent.

Before you start, install a Java Agent as described in the Installation, with the following values:

  • AM server URL: http://am.example.com:8080/am

  • Agent URL: http://agent.example.com:80/app

  • Agent profile name: java-agent

  • Agent profile realm: /

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

Enforce a policy decision from AM

  1. Using the ForgeRock Access Management docs for information, log in to AM as an administrator, and make sure that you are managing the / realm.

  2. Add a Java Agent profile:

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

    2. Add an agent with the following values:

      • Agent ID: java-agent

      • Agent URL: http://agent.example.com:80/app

      • Server URL: http://am.example.com:8080/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 > Java, 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 http://agent.example.com:80/app. The AM login page is displayed.

    4. Log in to AM as user demo, password Ch4ng31t, to access the web page protected by the Java 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 attribute in the entitlement:

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

  • 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, HTTP cookies, or request attributes 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 java-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 select whether to map response attribute names to HTTP headers, HTTP cookies, or request attributes. For more information, refer to 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 an HTTP header, HTTP cookie, or request attribute called CUSTOM-name. The value is taken from the user profile.

      For more information, refer to Response Attribute Map.

  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 Frequent flyer status is mapped to an HTTP header, HTTP cookie, or request attribute called CUSTOM-flyer-status. The value is gold.

      For more information, refer to Response Attribute Map.