Scripted policy conditions

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

AM includes a sample policy condition script^ that lets users in their country of residence access resources there.

You can view the script in the AM admin UI. Go to Realms > Realm Name > Scripts, and select Scripted Policy Condition.

The sample script is a legacy script, but you can also create a next-generation policy condition script. Find information about the available bindings for legacy and next-generation policy condition scripts in the Policy condition scripting API.

Prepare a demonstration

To demonstrate the sample policy condition script:

Create a policy administrator user.
Create an end user.
Create a policy that uses the script.

Policy administrator account

This account represents the policy enforcement point (PEP) account. It has the Entitlement Rest Access privilege required to request AM policy decisions over HTTP using the REST API. In a production deployment, use a PEP like PingGateway or an AM agent in this role.

Create a policy administrator.

In the AM admin UI, select Realms > Realm Name > Identities > + Add Identity and fill the required fields.

Record the username and password.
Create a group that grants the Entitlement Rest Access privilege to the policy administrator.

Select Realms > alpha > Identities > Groups > + Add Group to create a group with the following settings:

Group ID

am-policy-evaluation

Members

The policy administrator whose username you recorded

Privileges

Entitlement Rest Access

End user account

This account represents the end user who tries to access online resources.

Create a user.

In the AM admin UI, select Realms > Realm Name > Identities > + Add Identity and fill the required fields.

Record the username and password.
In the Home Address field of the user profile, enter an address in the US such as the following and save the change:
```
201 Mission St, Suite 2900, San Francisco, CA 94105
```

Sample policy

The policy references the script through environmental conditions.

Create a policy set for policies regarding URLs.

In the AM admin UI, select Realms > Realm Name > Authorization > Policy Sets > + New Policy Set to create a policy set with the following settings:

Id

am-policy-set

Resource Types

URL
Create a policy in the policy set.

Select Realms > Realm Name > Authorization > Policy Sets > am-policy-set > + Add a Policy to create a policy with the following settings:

Name

Scripted policy example

Resource Types

URL

Resources

*://*:*/*, *://*:*/*?*
In the new policy, update the settings.

Allow HTTP GET access by all authenticated users when permitted by the script:

Actions

GET: Allow

Subjects

Type: Authenticated Users

Environments

Type: Script, Script Name: Scripted Policy Condition

When modifying settings in the policy editor, select the edit icon to begin changing the setting, the check icon to confirm the change, then Save Changes to commit the change.
Verify the policy settings.

Try the demonstration

The AM policies?_action=evaluate endpoint lets a policy administrator make a REST call over HTTP to get a policy decision from AM. AM policy decisions for URL policies show at least the HTTP actions the user can perform. For details, refer to Request policy decisions over REST.

Here, when AM grants the user access to complete an HTTP GET request to the resource, the decision includes "actions":{"GET":true}. When AM denies access, the decision includes "actions":{}.

The REST call to the policies?_action=evaluate endpoint requires:

An SSO token ID for the policy administrator making the request.
An SSO token ID for the end user attempting to access the resource.

A request body that specifies who is attempting to access what in what way under what conditions.

Obtain an SSO token for the policy administrator:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <policy-admin-username>' \
--header 'X-OpenAM-Password: <policy-admin-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<policy-admin-tokenId>","successUrl":"/am/console","realm":"/alpha"}

bash

Obtain an SSO token for the end user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <end-user-username>' \
--header 'X-OpenAM-Password: <end-user-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<end-user-tokenId>","successUrl":"/am/console","realm":"/alpha"}

bash

Request evaluation for a request by a US end user in the US to access a resource located in the United States.

The script lets users in their country of residence access resources there. The user’s home country and IP address match the resource location; AM grants access.

$ curl \
--header 'iPlanetDirectoryPro: <policy-admin-tokenId>' \
--request POST \
--header 'Content-Type: application/json' \
--header "Accept-API-Version: resource=2.1" \
--data '{
  "resources": ["https://www.whitehouse.gov:443/about-the-white-house/"],
  "actions": {"GET": true},
  "application": "iPlanetAMWebAgentService",
  "subject": {
    "ssoToken": "<end-user-tokenId>"
  },
  "environment": {
    "IP": ["8.8.8.8"]
  }
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/policies?_action=evaluate'
[{
  "resource": "https://www.whitehouse.gov:443/about-the-white-house/",
  "actions": {
    "GET": true
  },
  "attributes": {
    "countryOfOrigin": ["US"]
  },
  "advices": {},
  "ttl": <ttl>
}]

bash

The script adds "attributes":{"countryOfOrigin":["US"]} to the result when AM grants access.

Request evaluation for a request by a US end user outside the US to access a resource located in the United States.

The user’s IP address does not match the home country or the resource location; no actions are returned:

$ curl \
--header 'iPlanetDirectoryPro: <policy-admin-tokenId>' \
--request POST \
--header 'Content-Type: application/json' \
--header "Accept-API-Version: resource=2.1" \
--data '{
  "resources": ["https://www.whitehouse.gov:443/about-the-white-house/"],
  "actions": {"GET": true},
  "application": "iPlanetAMWebAgentService",
  "subject": {
    "ssoToken": "<end-user-tokenId>"
  },
  "environment": {
    "IP": ["88.174.153.24"]
  }
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/policies?_action=evaluate'
[{
  "resource": "https://www.whitehouse.gov:443/about-the-white-house/",
  "actions": {},
  "attributes": {},
  "advices": {},
  "ttl": <ttl>
}]

bash

Notice "actions":{} in the response.

OAuth 2.0 scopes policy script API

To customize OAuth 2.0 scope decisions, configure the oauth2Scopes policy with an environment script condition that references an OAuth 2.0 policy condition script.

The following JavaScript writes the ID of the OAuth 2.0 client to the debug log and then authorizes the request:

logger.message("Client ID: " + environment.get("clientId"));
authorized=true;

javascript

OAuth 2.0 policy condition scripts can access the bindings available to the policy condition script API, except for the environment object. Instead of an IP property, this object returns the ID for the client making the authorization request.

For example, the following shows an environment map with a single entry:

"environment": {
    "clientId": [
        "MyOAuth2Client"
    ]
}

PingAM 8.0.1

Scripted policy conditions

Prepare a demonstration

Policy administrator account

End user account

Sample policy

Try the demonstration

OAuth 2.0 scopes policy script API