Identity Cloud

Scripted policy conditions

You can use scripts to tailor the actions that AM takes as part of policy evaluation.

AM includes a sample policy condition script that demonstrates how to access a user’s profile information, use that information in HTTP calls, and make a policy decision based on the outcome.

To examine the contents of the sample policy condition script in the AM admin UI, go to Realms > realm name > Scripts, and select Scripted Policy Condition.

Test scripted policy conditions with the sample script

The sample policy condition script requires the subject of the policy to have an address in their profile. The script compares this address to the country in the resource URL and to the country from which the request originated (determined by an external GeoIP web service). The script also requires the user to have access to evaluate policies.

Add an address to a user profile

Add an address value to a user’s profile. The sample policy condition script uses the address when performing policy evaluation. This example assumes that the user you are updating exists and has the ID demo.

  1. In the AM admin UI, go to Realms > realm name > Identities.

  2. On the Identities tab, select (demo).

  3. In the Home Address field, enter a valid address.

    For example:

    201 Mission St, Suite 2900, San Francisco, CA 94105
  4. Click Save Changes.

Add a user who can evaluate policies

Add a user to a group and assign the privilege required to perform policy evaluations.

  1. In the AM admin UI, go to Realms > realm name > Identities.

  2. Click Add Identity, enter an ID for the identity, such as restPolicyUser, complete the required fields, and click Create.

  3. Return to Realms > realm name > Identities.

    On the Groups tab, click Add Group, enter an ID for the group, such as policyEval, and click Create.

  4. Return to Realms > realm name > Identities.

    • Select the user you created in step 2, for example, restPolicyUser.

    • On the Groups tab, in the Name field, select the group you created in step 3, for example policyEval.

    • Click Save Changes.

  5. Go to Realms > realm name > Identities > Groups.

  6. Select the group you created in step 3, for example policyEval.

  7. On the Privileges tab, select Policy Admin, then click Save Changes.

Create a policy that uses the sample policy condition script

Create a policy that uses the sample policy condition script. Policy evaluations can then be performed to test the script functionality.

  1. In the AM admin UI, go to Realms > realm name > Authorization > Policy Sets.

  2. On the Policy Sets page, select Default OAuth2 Scopes Policy Set.

  3. Click Add a Policy.

  4. Define the policy as follows:

    • Enter a name for the policy.

    • Define resources to which the policy applies:

      • Select URL from the Resource Type list.

      • Select the resource pattern *://*:*/* from the Resources list, then click Add.

        The *://*:*/* resource appears in the Resources field.

      • Select Add Resource to add a second resource to the policy.

      • Select the resource pattern *://*:*/*?* from the Resources list, then click Add.

        The *://*:*/*?* resource appears along with the *://*:*/* resource in the Resources field.

      • Click Create to create the policy.

        The Resources tab appears as follows:

        Configure resources to try out the default policy condition script.
    • Specify actions to which the policy applies:

      • On the Actions tab, select GET from the Add an Action list.

      • The GET action appears in the list of actions. The default state for the GET action is Allow.

        The Actions tab appears as follows:

        Configure actions to try out the default policy condition script.
      • Click Save Changes.

    • Configure identities to which the policy applies:

      • On the Subjects tab, select the edit icon ().

      • Select Authenticated Users from the Type list.

      • Select the OK icon—the check mark.

        The Subjects tab appears as follows:

        Configure subjects to try out the default policy condition script.
      • Click Save Changes.

    • Configure environments in which the policy applies:

      • On the Environments tab, select Add an Environment Condition.

      • Select Script from the Type list.

      • Select Scripted Policy Condition from the Script Name list.

      • Select the OK icon—the check mark.

        The Environments tab appears as follows:

        Configure environments to try out the default policy condition script.
      • Click Save Changes.

    • No additional configuration is required in the Response Attributes or Details tabs.

Test the sample policy condition script

To evaluate against a policy, you must first obtain an SSO token for the subject performing the evaluation, in this case demo. You can then make a call to the policies?_action=evaluate endpoint, including some environment information, which the policy uses to make an authorization decision.

Evaluate a policy

  1. Obtain an SSO token for the demo user:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: demo" \
    --header "X-OpenAM-Password: Ch4ng31t" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM…​TU3OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }
  2. Obtain an SSO token for the user who has the privilege required to evaluate policies.

    For example, restPolicyUser.

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: restPolicyUser" \
    --header "X-OpenAM-Password: myStrongPassword" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC8aF…​TA1OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }
  3. Send an evaluation request to the policies endpoint, providing the SSO token of the restPolicyUser user as the value of the <session-cookie-name> header.

    In the JSON data, set the subject object to the SSO token of the demo user. In the resources object, include a URL that resides on a server in the same country as the address set for the demo user. In the environment object, include an IP address that is also based in the same country as the user and the resource.

    The example below uses the URL of a web site and an IP address located in the United States:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "<session-cookie-name>: AQIC8aF…​TA1OQ*" \
    --data '{
        "resources":[
            "https://www.us-site.com:8443/index.html"
        ],
        "application":"iPlanetAMWebAgentService",
        "subject":{
            "ssoToken":"AQIC5wM…​TU3OQ*"
        },
        "environment":{
            "IP":[
                "38.99.39.210"
            ]
        }
    }' \
    "https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate"
    {
        "advices":{},
        "ttl":9223372036854775807,
        "resource":"https://www.us-site.com:8443/index.html",
        "actions":{
            "POST":true,
            "GET":true
        },
        "attributes":{
            "countryOfOrigin":[
                "United States"
            ]
        }
    }

    If the country in the subject’s profile matches the country determined from the source IP in the environment and the country determined from the resource URL, then AM returns a list of actions available. The script will also add an attribute to the response called countryOfOrigin with the country as the value.

    If the countries do not match, no actions are returned. In the following example, the resource URL is based in France, while the IP and user’s address in the profile are based in the United States:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "<session-cookie-name>: AQIC8aF…​TA1OQ*" \
    --data '{
        "resources":[
            "https://www.france-site.com:8443/index.html"
        ],
        "application":"iPlanetAMWebAgentService",
        "subject":{
            "ssoToken":"AQIC5wM…​TU3OQ*"
        },
        "environment":{
            "IP":[
                "38.99.39.210"
            ]
        }
    }' \
    "https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate"
    {
        "advices": {},
        "ttl": 9223372036854775807,
        "resource": "https://www.france-site.com:8443/index.html",
        "actions": {},
        "attributes": {}
    }
Copyright © 2010-2022 ForgeRock, all rights reserved.