PingAM 7.5.1

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:

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.

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

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

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

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

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

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

    *://*:*/*, *://*:*/*?*

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

  4. Verify the policy settings.

    Policy settings for the Scripted policy example

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.

    1. 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"}

    2. 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"}

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

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

  1. Log in as the AM administrator, amAdmin.

  2. Go to the Logback.jsp page; for example, https://openam.example.com:8443/openam/Logback.jsp.

  3. In the Logger list, scroll to select the scripted policy decision logger; for example, scripts.POLICY_CONDITION.9de3eb62-f131-4fac-a294-7bd170fd4acb.

  4. From the Level list, choose the debug level required.

    In this example, select Trace.

  5. Click Apply.

    Enable debug logging for a scripted conditions.

    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

A policy condition script has access to the following specific bindings, predefined objects that AM injects into the script execution context.

Use these objects in a script to get information such as the authorization state of a request, session properties, and user profile 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.
Binding Description Further information

advice

Return the condition advice from the script.

Set authorization responses

authorized

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

The environment values passed from the client making the authorization request.

Access environment data

httpClient

Make outbound HTTP calls.

Access HTTP services

identity

Access the data stored in the user’s profile.

Access profile data

logger

Write a message to the AM debug log.

Log script messages

responseAttributes

Add an attribute to the response to the authorization request.

Set authorization responses

scriptName

Return the name of the running script.

Output script name.

session

Access the properties for the current session.

Access session data

ttl

The time-to-live value for the response to a successful authorization.

Set authorization responses

username

String identifying the user ID of the subject requesting authorization.

-

Access environment data

The environment binding holds data from the client making the authorization request as a Map of <String, Set<String>.

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

  • Policy condition script

  • OAuth 2.0 scopes policy script

"environment": {
    "IP": [
        "127.0.0.1"
    ]
}
"environment": {
    "clientId": [
        "MyOAuth2Client"
    ]
}
For information about scripting OAuth 2.0 policy conditions, refer to OAuth 2.0 scopes policy script API.

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.
Set identity.getAttribute(String attributeName)

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

For example:

var attribute = identity.getAttribute("attrName").iterator().next();
void identity.setAttribute(String attributeName, Array attributeValues)

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

For example:

identity.setAttribute("attrName", ["newValue"]);

// Explicitly persist data
identity.store();
void identity.addAttribute(String attributeName, String attributeValue)

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

For example:

identity.addAttribute("attrName", ["newValue"]);

// Explicitly persist data
identity.store();

You must call identity.store() to persist changes or they will be lost when the script completes.

Access session data

Server-side authorization scripts can access session data for 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.
String session.getProperty(String propertyName)

Retrieve properties from the session associated with the subject of the authorization request. Refer to the following table for example properties and their values.

Session properties and example 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 with the following methods:

void responseAttributes.put(String attributeName, Array attributeValue)

Add an attribute to the response to the authorization request.

void advice.put(String adviceKey, Array adviceValues

Add advice key-value pairs to the response to a failing authorization request.

void ttl(Integer ttlValue)

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.