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.

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 IG 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://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<policy-admin-tokenId>","successUrl":"/am/console","realm":"/alpha"}

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

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://openam.example.com:8443/openam/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>
}]

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://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_action=evaluate'
[{
  "resource": "https://www.whitehouse.gov:443/about-the-white-house/",
  "actions": {},
  "attributes": {},
  "advices": {},
  "ttl": <ttl>
}]

Notice "actions":{} in the response.

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 to capture must execute 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 to the Logback.jsp page do not persist when AM restarts.

For additional details, refer to Debug logging.

Policy condition script API

In addition to the functionality provided by Access 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.

AM can return the information in the response to an authorization request.

If you use static methods within policy scripts, you must allowlist those scripts. Otherwise, policy evaluation fails 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

attributeName (type: String)

Set

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

identity.setAttribute

attributeName (type: String)
attributeValues (type: Array)

void

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

identity.addAttribute

attributeName (type: String)
attributeValue (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 are 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`	`propertyName` (type: `String`)	`String`	Retrieve properties from the session associated with the subject of the authorization request. Refer to the following table for example properties and their values.

The following table lists session properties available to the session.getProperty() method with sample 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`	`attributeName` (type: `String`) `attributeValues` (type: `Array`)	`void`	Add an attribute to the response to the authorization request.
`advice.put`	`adviceKey` (type: `String`) `adviceValues` (type: `Array`)	`void`	Add advice key-value pairs to the response to a failing authorization request.
`ttl`	`ttlValue` (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, `ttlValue` 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.3.1

Scripted policy conditions

Prepare a demonstration

Policy administrator account

End user account

Sample policy

Try the demonstration

Enable debug logging for scripted policy conditions

Policy condition script API

Access authorization state

Access profile data

Access session data

Set authorization responses