Scripting a Policy Condition

You can use scripts to tailor the actions AM does as part of policy evaluation to your environment.

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, navigate to Realms > Top Level Realm > Scripts, and then select Scripted Policy Condition.

Related information:

Preparing AM to use Scripted Policy Conditions

AM requires a small amount of configuration before trying the default policy condition script. The default policy condition script requires that the subject of the policy has an address in their profile. The script compares the address to the country in the resource URL and to the country from which the request originated, as determined by an external GeoIP web service. The demo user also requires access to evaluate policies.

To Add an Address to the Demo User

In this procedure, add an address value to the demo user’s profile. The default policy condition script uses the address when performing policy evaluation.

  1. Log in as an AM administrator, for example amAdmin.

  2. Select Realms > Top Level Realm > Identities.

  3. On the Identities tab, select the demo user.

  4. In Home Address, enter a valid address.

    For example:

    201 Mission St, Suite 2900, San Francisco, CA 94105
  5. Select Save Changes.

To Allow a User to Evaluate Policies

In this procedure, add a user to a group and assign the privilege required to perform policy evaluations.

  1. Log in as an AM administrator, for example amAdmin.

  2. Select Realms > Top Level Realm > Identities.

  3. Select Add Identity, enter an ID for the identity, such as restPolicyUser, complete the required fields, and then select Create.

  4. Return to Realms > Top Level Realm > Identities.

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

  5. Return to Realms > Top Level Realm > Identities.

    • Select the user you created, for example, restPolicyUser.

    • Select the Groups tab.

    • In the Name box, select the group created in step 3, for example policyEval.

    • Select Save Changes.

  6. Select Realms > Top Level Realm > Identities > Groups.

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

  8. On the Privileges tab, select Policy Admin.

  9. Select Save Changes.

To Create a Policy that Uses the Default Policy Condition Script

In this procedure, create a policy that uses the default policy condition script. Policy evaluations can then be performed to test the script functionality.

  1. Log in as an AM administrator, for example amAdmin.

  2. Select Realms > Top Level Realm > Authorization > Policy Sets.

  3. On the Policy Sets page, select Default Policy Set.

  4. On the Default Policy Set page, select Add a Policy.

  5. Define the policy as follows:

    • Enter a name for the policy.

    • Define resources to which the policy applies:

      • Select URL from the Resource Type drop down list.

      • Select the resource pattern *://*:*/* from the Resources drop down list.

      • Select 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 drop down list.

      • Select Add.

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

      • Select 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:

      • Select the Actions tab.

      • Select GET from the Add an Action drop down 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.
      • Select Save Changes.

    • Configure identities to which the policy applies:

      • Select the Subjects tab.

      • Select the edit icon ().

      • Select Authenticated Users from the Type drop down list.

      • Select the OK icon—the check mark.

        The Subjects tab appears as follows:

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

    • Configure environments in which the policy applies:

      • Select the Environments tab.

      • Select Add an Environment Condition.

      • Select Script from the Type drop down list.

      • Select Scripted Policy Condition from the Script Name drop down list.

      • Select the OK icon—the check mark.

        The Environments tab appears as follows:

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

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

To Enable Debug Logging for Scripted Policy Conditions

This procedure shows how to enable trace-level debug logging for scripted policy conditions, so that logger output from the default policy condition script is recorded.

  1. Ensure that the script containing the debug output you want to capture has executed at least once.

    This will create the required logger that can be configured in the next steps.

  2. Log in as the AM administrator, amAdmin.

  3. Visit the Logback.jsp page, for example: https://tenant-name.forgeblocks.com/am/Logback.jsp.

  4. In the Add logger drop-down list, select the scripts.POLICY_CONDITION class, and then click Add.

  5. Locate the newly added scripts.POLICY_CONDITION class in the Logger list, and then click Edit.

    • From the Level drop-down list, choose the debug level required. In this example, select Trace.

    • From the Appender list, choose the location for the debug output. In this example, select Policy.

    Enabling debug logging for a scripted conditions.
  6. At the bottom of the Logback.jsp page, click Save.

    Trace-level debug logging is now enabled for scripted policy conditions, with script output appearing in the /path/to/openam/var/debug/Policy debug log file.

    Changes made in the Logback.jsp page are not persisted after rebooting AM or the container in which it runs. Repeat the steps above to debug scripted decision nodes.

    For more information on configuring debug logging, see maintenance-guide:debug-logging.adoc.

Trying the Default Policy Condition Script

To evaluate against a policy, you must first obtain an SSO token for the subject performing the evaluation, in this case the demo user. 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.

To 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 iPlanetDirectoryPro 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 "iPlanetDirectoryPro: 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 "iPlanetDirectoryPro: 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": {}
    }