Identity Cloud

Scripted policy conditions

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

Identity Cloud provides a sample policy condition script^ that lets users in their country of residence access resources there.

You can view the script in the Identity Cloud admin UI. Go to Scripts > Auth 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 Identity Cloud policy decisions over HTTP using the REST API. In a production environment, use a PEP like IG or a web or Java agent in this role.

  1. Create a policy administrator.

    In the Identity Cloud admin UI, select Identities > Manage > Alpha Realm - Users > + New Alpha Realm - User 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.

    Under Native Consoles > Access Management, 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 Identity Cloud admin UI, select Identities > Manage > Alpha Realm - Users > + New Alpha Realm - User and fill the required fields.

    Record the username and password.

  2. In the Address 1 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.

    Under Native Consoles > Access Management, select Realms > alpha > 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 > alpha > 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 policies?_action=evaluate endpoint lets a policy administrator make a REST call over HTTP to get a policy decision from Identity Cloud. 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 Identity Cloud grants the user access to complete an HTTP GET request to the resource, the decision includes "actions":{"GET":true}. When Identity Cloud 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://<tenant-env-fqdn>/am/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://<tenant-env-fqdn>/am/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; Identity Cloud grants access.

      $ curl \
      --header '<session-cookie-name>: <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://<tenant-env-fqdn>/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>
      }]

      The script adds "attributes":{"countryOfOrigin":["US"]} to the result when Identity Cloud 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 '<session-cookie-name>: <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://<tenant-env-fqdn>/am/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.

Copyright © 2010-2024 ForgeRock, all rights reserved.