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

Related information:

Scripting
Policy condition script API

Prepare AM to use scripted policy conditions

AM requires a small amount of configuration before you can test 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 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 demo user also needs access to evaluate policies.

Add an address for the `demo` user

Add an address value to the demo user’s profile. The default policy condition script uses the address when performing policy evaluation.

Log in as an AM administrator, for example amAdmin.
Select Realms > Top Level Realm > Identities.
On the Identities tab, select the demo user.
In the Home Address field, enter a valid address.

For example:
```
201 Mission St, Suite 2900, San Francisco, CA 94105
```
Select Save Changes.

Let a user evaluate policies

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

Log in as an AM administrator, for example amAdmin.
Select Realms > Top Level Realm > Identities.
Select Add Identity, enter an ID for the identity, such as restPolicyUser, complete the required fields, and click Create.
Return to Realms > Top Level Realm > Identities.

On the Groups tab, select Add Group. Enter an ID for the group, such as policyEval, and click Create.
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 4, for example policyEval.
- Click Save Changes.
Select Realms > Top Level Realm > Identities > Groups.
Select the group created in step 4, for example policyEval.
On the Privileges tab, select Policy Admin.
Click Save Changes.

Create a policy that uses the default policy condition script

These steps create a policy that uses the default policy condition script. You can then perform policy evaluation to test the script.

Log in as an AM administrator, for example amAdmin.
Select Realms > Top Level Realm > Authorization > Policy Sets.
On the Policy Sets page, select Default Policy Set.
On the Default Policy Set page, select Add a Policy.
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.
  - 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 drop down list.
  - Click Add.
    
    The *://*:*/*?* resource appears along with the *://*:*/* resource in the Resources field.
  - Click Create to create the policy.
- Specify actions to which the policy applies:
  - Select 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.
  - Select Save Changes.
- Configure identities to which the policy applies:
  - Select the Subjects tab.
  - Select the edit icon ().
  - Select Authenticated Users from the Type list.
  - Select the OK icon—the check mark.
  - Click Save Changes.
- Configure environments in which the policy applies:
  - Select 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.
  - Click Save Changes.
- No additional configuration is required in the Response Attributes or Details tabs.

Test 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.

Evaluate a policy

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://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…TU3OQ*",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

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://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC8aF…TA1OQ*",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

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://openam.example.com:8443/openam/json/realms/root/realms/alpha/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://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_action=evaluate"
{
    "advices": {},
    "ttl": 9223372036854775807,
    "resource": "https://www.france-site.com:8443/index.html",
    "actions": {},
    "attributes": {}
}

Enable debug logging for scripted policy conditions

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

The script containing the debug output that you want to capture must have executed at least once to create the logger.

The name of the scripted policy decision logger has the format: scripts.POLICY_CONDITION.script-UUID.

Log in as the AM administrator, amAdmin.
Go to the Logback.jsp page, for example: https://openam.example.com:8443/openam/Logback.jsp.
In the Logger list, scroll to select the scripted policy decision logger; for example scripts.POLICY_CONDITION.9de3eb62-f131-4fac-a294-7bd170fd4acb.
From the Level list, choose the debug level required. In this example, select Trace.
Click Apply.

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.

For more information on configuring debug logging, see Debug logging.

Policy condition script API

In addition to the functionality provided by Accessing HTTP Services and Debug logging, scripted policy condition scripts can access the authorization state of a request, the information about a session, and the user profile’s data.

This information can be returned, in the response to an authorization request.

If you use static methods within policy scripts, you must allowlist those scripts. Otherwise, policy evaluation will fail with an exception (logged in the Entitlement debug file) similar to the following:

java.lang.SecurityException: Access to Java class script-name is prohibited.

Access authorization state

Server-side scripts can access the current authorization state through the following objects:

Authorization State Objects
Object	Type	Description
`authorized`	`Boolean`	Return `true` if the authorization is currently successful, or `false` if authorization has failed. Server-side scripts must set a value for `authorized` before completing.
`environment`	`Map<String, Set<String>>`	Describe the environment passed from the client making the authorization request. For example, the following shows a simple `environment` map with a single entry: `"environment": { "IP": [ "127.0.0.1" ] }`
`resourceURI`	`String`	Specify the URI of the resource to which authorization is being requested.
`username`	`String`	Specify the user ID of the subject that is requesting authorization.

Access profile data

Server-side authorization scripts can access the profile data of the subject of the authorization request, through the methods of the identity object.

To access a subject’s profile data, they must be logged in and their SSO token must be available.

Method Parameters Return Type Description

identity.getAttribute

Attribute Name (type: String)

Set

Return the values of the named attribute for the subject of the authorization request.

identity.setAttribute

Attribute Name (type: String)
Attribute Values (type: Array)

Void

Set the named attribute to the values specified by the attribute value for the subject of the authorization request.

identity.addAttribute

Attribute Name (type: String)
Attribute Value (type: String)

Void

Add an attribute value to the list of attribute values associated with the attribute name for the subject of the authorization request.

identity.store

None

Void

Commit any changes to the identity repository.

You must call store() otherwise changes will be lost when the script completes.

Access session data

Server-side authorization scripts can access session data of the subject of the authorization request through the methods of the session object.

To access the session data of the subject, they must be logged in and their SSO token must be available.

Authorization Script Session Methods
Method	Parameters	Return Type	Description
`session.getProperty`	`Property Name` (type: `String`)	`String`	Retrieve properties from the session associated with the subject of the authorization request. See the table below for example properties and their values.

The following table demonstrates some of the session properties available to the session.getProperty() method, and example values:

Get Session Data Example Keys and Values
Key	Sample value
`AMCtxId`	`e370cca2-02d6-41f9-a244-2b107206bd2a-122934`
`amlbcookie`	`01`
`authInstant`	`2018-04-04T09:19:05Z`
`AuthLevel`	`0`
`CharSet`	`UTF-8`
`clientType`	`genericHTML`
`FullLoginURL`	`/openam/XUI/?realm=alpha#login/`
`Host`	`198.51.100.1`
`HostName`	`openam.example.com`
`Locale`	`en_US`
`Organization`	`dc=openam,dc=forgerock,dc=org`
`Principal`	`uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org`
`Principals`	`amAdmin`
`Service`	`ldapService`
`successURL`	`/openam/console`
`sun.am.UniversalIdentifier`	`uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org`
`UserId`	`amAdmin`
`UserProfile`	`Required`
`UserToken`	`amAdmin`
`webhooks`	`myWebHook`

Set authorization responses

Server-side authorization scripts can return information in the response to an authorization request.

Authorization Script Response Methods
Method	Parameters	Return Type	Description
`responseAttributes.put`	`Attribute Name` (type: `String`) `Attribute Values` (type: `Array`)	`Void`	Add an attribute to the response to the authorization request.
`advice.put`	`Advice Key` (type: `String`) `Advice Values` (type: `Array`)	`Void`	Add advice key-value pairs to the response to a failing authorization request.
`ttl`	`TTL Value` (type: `Integer`)	`Void`	Add a time-to-live value, which is a timestamp in milliseconds to the response to a successful authorization. After the time-to-live value the decision is no longer valid. If no value is set, TTL Value defaults to `Long.MAX_VALUE` (9223372036854775807), which means the decision has no timeout, and can live for as long as the calling client holds on to it. In the case of policy enforcement points, they hold onto the decision for their configured cache timeout.

AM 7.2.2

Scripted policy conditions

Prepare AM to use scripted policy conditions

Add an address for the demo user

Let a user evaluate policies

Create a policy that uses the default policy condition script

Test the default policy condition script

Evaluate a policy

Enable debug logging for scripted policy conditions

Policy condition script API

Access authorization state

Access profile data

Access session data

Set authorization responses

Add an address for the `demo` user