Identity Cloud

Authorization

This guide covers concepts, implementation procedures, and customization techniques for working with the authorization features of ForgeRock Access Management.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Authorization and policy decisions

AM provides access management, which consists of:

  • Authentication: determining who is trying to access a resource

  • Authorization: determining whether to grant or deny access to the resource

The decision to grant access depends on a number of factors:

  • the policies governing access

  • who is trying to gain access

  • possible additional conditions, such as whether the access needs to happen over a secure channel or what time of day it is.

AM relies on policies to reach authorization decisions, such as whether to grant or deny access to a resource, or to grant or deny OAuth 2.0 scopes.

Related Information: Dynamic OAuth 2.0 authorization

Protect resources

When you configure policy sets to protect resources, AM acts as the policy decision point (PDP), whereas AM web and Java agents act as policy enforcement points (PEP). In other words, an agent or other PEP takes responsibility only for enforcing a policy decision rendered by AM. When you configured applications and their policies in AM, you used AM as a policy administration point (PAP).

Concretely speaking, when a PEP requests a policy decision from AM, it specifies the target resource(s), the policy set (default: iPlanetAMWebAgentService), and information about the subject and the environment. AM as the PDP retrieves policies within the specified policy set that apply to the target resource(s). AM then evaluates those policies to make a decision based on the conditions matching those of the subject and environment. When multiple policies apply for a particular resource, the default logic for combining decisions is that the first evaluation resulting in a decision to deny access takes precedence over all other evaluations. AM only allows access if all applicable policies evaluate to a decision to allow access.

AM communicates the policy decision to the PEP. The concrete decision, applying policy for a subject under the specified conditions, is called an entitlement.

The entitlement indicates the resource(s) it applies to, the actions permitted and denied for each resource, and optionally, response attributes and advice.

Shows the relationship between realms, policies, and policy sets.
Figure 1. Protecting Pages or Applications

When AM denies a request due to a failed condition, AM can send advice to the PEP, and the PEP can then take remedial action. For instance, suppose a user comes to a website after authenticating with an email address and password, which is configured as authentication level 0. Had the user authenticated using a one-time password, the user would have had authentication level 1 in their session. Yet, because they have authentication level 0, they currently cannot access the desired page, as the policy governing access requires authentication level 1. AM sends advice, prompting the PEP to have the user re-authenticate using a one-time password, gaining authentication level 1, and thus having AM grant access to the protected page.

Policy decisions

AM has to match policies to resources to take policy decisions. For a policy to match, the resource has to match one of the resource patterns defined in the policy. The user making the request has to match a subject. Furthermore, at least one condition for each condition type has to be satisfied.

If more than one policy matches, AM has to reconcile differences. When multiple policies match, the order in which AM uses them to make a policy decision is not deterministic. However, a deny decision overrides an allow decision and so, by default, once AM reaches a deny decision, it stops checking further policies.

Example

Consider the case where AM protects a user profile web page. An AM web agent installed in the web server intercepts client requests to enforce policy. The policy says that only authenticated users can access the page to view and to update their profiles.

When a user browses to the profile page, the AM agent intercepts the request. The web agent notices that the request is to access a protected resource, but the request is coming from a user who has not yet logged in and consequently has no authorization to visit the page. The web agent therefore redirects the user’s browser to AM to authenticate.

AM receives the redirected user, serving a login page that collects the user’s email and password. With the email and password credentials, AM authenticates the user, and creates a session for the user. AM then redirects the user to the web agent, which gets the policy decision from AM for the page to access, and grants access to the page.

While the user has a valid session with AM, the user can go away to another page in the browser, come back to the profile page, and gain access without having to enter their email and password again.

Notice how AM and the web agent handle the access in the example. The website developer can offer a profile page, but the website developer never has to manage login, or handle who can access a page. As AM administrator, you can change authentication and authorization independently of updates to the website. You might need to agree with website developers on how AM identifies users, so web developers can identify users by their own names when they log in. By using AM and web or Java agents for authentication and authorization, your organization no longer needs to update web applications when you want to add external access to your Intranet for roaming users, open some of your sites to partners, only let managers access certain pages of your HR website, or allow users already logged in to their desktops to visit protected sites without having to type their credentials again.

Policies

Authorization policies let AM determine whether to grant a subject access to a resource.

A policy defines the following:

resources

The resource to which access is restricted, such as a web page, a mobile app, or a boarding area in an airport.

actions

The verbs that describe what users can do to the resource, such as read a web page, submit a web form, or access a boarding area.

subject conditions

Who the policy applies to, such as all authenticated users, only administrators, or only passengers with valid tickets for planes leaving soon.

environment conditions

The circumstances under which the policy applies, such as only during work hours, only when accessing from a specific IP address, or only when the flight is scheduled to leave within the next four hours.

response attributes

Information that AM attaches to a response following a policy decision, such as a name, email address, or frequent flyer status.

Policies in the UI

  1. In the AM admin UI, go to Realms > Realm Name > Authorization > Policy Sets, and select the name of the policy set in which to configure a policy:

  2. To create a new policy, select Add a Policy.

  3. In the Name field, enter a descriptive name for the policy.

    Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

  4. To define resources that the policy applies to, follow the steps below:

    • Select a resource type from the Resource Type drop-down list.

      The set of resource patterns within the selected resource type will populate the Resources drop-down list. For information on configuring resource types, see Resource types.

    • Select a resource pattern from the Resources drop-down list.

    • Replace the asterisks with values to define the resources that the policy applies to.

      For information on specifying patterns for matching resources, see Specifying resource patterns with wildcards.

      Optionally, edit the resource pattern.
      Figure 2. Editing Resource Patterns

      The OAuth2 Scope resource type has the same resource patterns as the URL resource type, and also the * pattern. Use the resource patterns that are most relevant for the scopes in your environment.

      Optionally, edit the resource pattern.
      Figure 3. Editing OAuth2 Scope Resource Type Resource Patterns

      Before testing your OAuth 2.0 policies, ensure your OAuth 2.0 service is configured to interact with AM’s authorization service. Perform the following steps:

      1. Go to Realms > Realm Name > Services > OAuth2 Provider.

      2. Ensure that Use Policy Engine for Scope decisions is enabled.

      For more information about testing OAuth 2.0 policies, see Dynamic OAuth 2.0 authorization.

    • Select Add to save the resource.

      The AM admin UI displays a page for your new policy. The tab pages let you modify the policy’s properties.

      To remove a resource, select Delete.
  5. Repeat these steps to add all the resources to which your policy applies, and then select Create.

  6. To configure the policy’s actions, select the Actions tab and perform the following:

    • Select an action that the policy applies to by selecting them from the Add an Action drop-down list.

    • Select whether to allow or deny the action on the resources specified earlier.

      Select the actions and whether to allow or deny the action for the resources specified.
      Figure 4. Allowing or Denying the Action for the Resource
    • Repeat these steps to add all the appropriate actions, and then select Save Changes.

  7. Define conditions in the AM admin UI by combining logical operators with blocks of configured parameters to create a rule set that the policy uses to filter requests for resources.

    Use drag and drop to nest logical operators at multiple levels to create complex rule sets.

    Valid drop points in which to drop a block are displayed with a grey horizontal bar.

    Drop blocks into drop points, which are shown as a grey horizontal band.
    Figure 5. Valid Drop Point
    • To define the subjects that the policy applies to, complete the following steps on the Subjects tab:

      • Select Add a Subject Condition, choose the type from the drop-down menu, specify any required subject values, select the checkmark to the right when done, and then drag the block into a valid drop point in the rule set above.

        Creating subject conditions in the policy editor.
        Figure 6. Nesting subject conditions
        Subject condition types
        Authenticated Users

        Any user that has successfully authenticated with AM.

        Users & Groups

        A user or group as defined in the realm containing the policy. To manage the identities and groups in a realm, go to Realms > Realm Name > Identities.

        Select one or more users or groups from the Identities or Groups tabs, which display the identities and groups available within the realm.

        To remove an entry, select the value, and then press kbd:[Delete] (Windows/GNU/Linux) or kbd:[Backspace] (Mac OS X).

        OpenID Connect/Jwt Claim

        Validate a claim within a JSON Web Token (JWT).

        Type the name of the claim to validate in the Claim Name field, for example, sub, and the required value in the Claim Value field, and then select the checkmark.

        Repeat the step to enter additional claims.

        The claim(s) will be part of the JWT payload together with the JWT header and signature. The JWT is sent in the authorization header of the bearer token.

        This condition type only supports string equality comparisons, and is case-sensitive.

        Never Match

        Never match any subject. Has the effect of disabling the policy, as it will never match a subject.

        If you do not set a subject condition, "Never Match" is the default. In other words, you must set a subject condition for the policy to apply.

        To match regardless of the subject, configure a subject condition that is "Never Match" inside a logical Not block.

      • To add a logical operator, select the Add a Logical Operator button, choose between All Of, Not, and Any Of from the drop-down list, and then drag the block into a valid drop point in the rule set above.

      • Continue combining logical operators and subject conditions. To edit an item, select the Edit button. To remove an item, select the Delete button. When complete, select Save Changes.

    • To configure environment conditions in the policy, complete the following steps on the Environments tab:

      • To add an environment condition, select the Environment Condition button, choose the type from the drop-down list, specify any required parameters, and then drag the block into a drop point in a logical block above.

        Script is the only environmental condition available for OAuth 2.0 policies.
        Environment condition types
        Active Session Time

        Make the policy test how long the user’s session has been active, as specified in Max Session Time. To terminate the session if it has been active for longer than the specified time, set Terminate Sessions to True. The user will need to reauthenticate.

        Authentication by Module Chain

        Make the policy test the service that was used to authenticate the user.

        Authentication by Module Instance

        Make the policy test the authentication module used to authenticate, specified in Authentication Scheme. Specify a timeout for application authentication in Application Idle Timeout Scheme, and the name of the application in Application Name.

        Authentication Level (greater than or equal to)

        Make the policy test the minimum acceptable authentication level specified in Authentication Level.

        Authentication Level (less than or equal to)

        Make the policy test the maximum acceptable authentication level specified in Authentication Level.

        Authentication to a Realm

        Make the policy test the realm to which the user authenticated.

        A session can only belong to one realm, and session upgrade between realms is not allowed.

        Current Session Properties

        Make the policy test property values set in the user’s session.

        Set Ignore Value Case to True to make the test case-insensitive.

        Specify one or more pairs of session properties and values using the format property:value. For example, specify clientType:genericHTML to test whether the value of the clientType property is equal to genericHTML.

        Identity Membership

        Make the policy apply if the UUID of the invocator is a member of at least one of the AMIdentity objects specified in AM Identity Name.

        Often used to filter requests on the identity of a Web Service Client (WSC).

        Java agents and web agents do not support the Identity Membership environment condition. Instead, use the equivalent Users & Groups subject condition.

        IPv4 Address/DNS Name

        Make the policy test the IP version 4 address that the request originated from.

        The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.

        Specify a range of addresses to test against by entering four sets of up to three digits, separated by periods (kbd:[.]) in both Start IP and End IP.

        If only one of these values is provided, it is used as a single IP address to match.

        Optionally, specify a DNS name in DNS Name to filter requests to that domain.

        IPv6 Address/DNS Name

        Make the policy test the IP version 6 address that the request originated from.

        The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.

        Specify a range of addresses to test against by entering eight sets of four hexadecimal characters, separated by a colon (kbd:[:]) in both Start IP and End IP.

        If only one of these values is provided, it is used as a single IP address to match.

        Optionally, specify a DNS name in DNS Name to filter requests to those coming from the specified domain.

        Use an asterisk (kbd:[*]) in the DNS name to match multiple subdomains. For example, *.example.com applies to requests coming from www.example.com, secure.example.com, or any other subdomain of example.com.

        LDAP Filter Condition

        Make the policy test whether the user’s entry can be found using the LDAP search filter you specify in the directory configured for the policy service. By default, this is the identity repository defined during setup.

        If you define a filter condition that uses LDAP accounts or groups in a different identity repository, you must configure the LDAP settings:

        1. Go to Realms > Realm Name > Services.

        2. Select Policy Configuration to view and edit the LDAP configuration.

        OAuth2 Scope

        Make the policy test whether an authorization request includes all of the specified OAuth 2.0 scopes.

        Scope names must follow OAuth 2.0 scope syntax described in RFC 6749, Access Token Scope. As described in that section, separate multiple scope strings with spaces, such as openid profile.

        The scope strings match regardless of order in which they occur, so openid profile is equivalent to profile openid.

        The condition is also met when additional scope strings are provided beyond those required to match the specified list. For example, if the condition specifies openid profile, then openid profile email also matches.

        Resource/Environment/IP Address

        Make the policy apply to a complex condition, such as whether the user is making a request from the localhost, and has also authenticated in a particular way.

        Entries must take the form of an IF…​ELSE statement. The IF statement can specify either IP to match the user’s IP address, or dnsName to match their DNS name.

        If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. If not, relevant advice is returned in the policy evaluation request.

        The available parameters for the THEN statement are as follows:

        module

        The module used to authenticate the user. For example, DataStore.

        service

        The service that was used to authenticate the user.

        authlevel

        The minimum required authentication level.

        role

        The role of the authenticated user.

        user

        The name of the authenticated user.

        redirectURL

        The URL the user was redirected from.

        realm

        The realm that was used to authenticate the user.

        The IP address can be IPv4, IPv6, or a hybrid of the two. Example: IF IP=[127.0.0.1] THEN role=admins.

        Script

        Make the policy depend on the outcome of a JavaScript or Groovy script executed at the time of the policy evaluation.

        For information on scripting policy conditions, see Scripted policy conditions.

        Script is the only environmental condition available for OAuth 2.0 policies. Use scripts to capture the ClientId environmental attribute.

        Time (day, date, time, and timezone)

        Make the policy test when the policy is evaluated.

        The values for day, date and time must be set in pairs that comprise a start and an end.

        Day, date and time conditions in policies must consist of a start and an end value.
        Figure 7. Create conditions that apply between a start and end date andtime.
        Transaction

        Make the policy depend on the successful completion of a transaction performed by the user.

        Configure a transaction with an authentication strategy that asks the user to reauthenticate before being allowed access to the resource.

        Transactions support the following authentication strategies:

        • Authenticate to Chain: Specify the name of an authentication chain the user must successfully complete to access the protected resource.

        • Authenticate to Realm: Specify the full path of a realm in which the user must successfully authenticate to access the protected resource.

          For example, /sales/internal.

        • Authenticate to Tree: Specify the name of an authentication tree the user must successfully traverse to access the protected resource.

        • Authenticate to Module: Specify the name of an authentication module the user must successfully authenticate against to access the protected resource.

        • Auth Level: Specify the minimum authentication level the user must achieve to access the protected resource.

          If you specify a minimum, you must ensure there are methods available to users to reach that level. If none are found, the policy will return a 400 Bad request error when attempting to complete the transaction.

        For more information on transactional authorization, see Transactional authorization.

      • To add a logical operator, select the Logical button, choose between All Of, Not, and Any Of from the drop-down list, and drag the block into a valid drop point in the rule set above.

      • Continue combining logical operators and environment conditions, and when finished, click Save Changes.

  8. You can add response attributes, retrieved from the user entry in the identity repository, into the headers of the request at policy decision time (not available for the OAuth2 Scope resource type). The web or Java agent for the protected resources/applications or the protected resources/applications themselves retrieve the policy response attributes to customize or personalize the application. Policy response attributes come in two formats: subject attributes and static attributes.

    To configure response attributes in the policy, complete the following steps on the Response attributes tab:

    • To add subject attributes, select them from the Subject attributes drop-down list.

      To remove an entry, select the value, and click Delete (Windows/GNU/Linux) or kbd:[Backspace] (Mac OS X).

    • To add a static attribute, specify the key-value pair for each static attribute. Enter the Property Name and its corresponding Property Value in the fields, and select the Add (kbd:[+]) icon.

      To edit an entry, select the Edit icon in the row containing the attribute, or select the row itself. To remove an entry, select the Delete icon in the row containing the attribute.

    • Continue adding subject and static attributes, and when finished, click Save Changes.

Policies over REST

Policies are realm-specific, so the URI for the policies API can contain a realm component, such as /json/realm/policies.

Policy resources are built from standard JSON objects and values (strings, numbers, objects, arrays, true, false, and null).

Example
{
    "name": "mypolicy",
    "active": true,
    "description": "My Policy.",
    "applicationName": "iPlanetAMWebAgentService",
    "actionValues": {
        "POST": true,
        "GET": true
    },
    "resources": [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "subject": {
        "type": "AuthenticatedUsers"
    },
    "condition": {
        "type": "SimpleTime",
        "startTime": "09:00",
        "endTime": "17:00",
        "startDay": "mon",
        "endDay": "fri",
        "enforcementTimeZone": "GMT"
    },
    "resourceTypeUuid": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
    "resourceAttributes": [
        {
            "type": "User",
            "propertyName": "givenName",
            "propertyValues": [ ]
        }
    ],
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": "2015-05-11T17:39:09.393Z",
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": "2015-05-11T17:37:24.556Z"
}

The values for the fields shown in the example are explained below:

name

String matching the name in the URL (when creating the policy using HTTP PUT) or in the body (when creating the policy using HTTP POST).

active

Boolean indicating whether AM considers the policy active for evaluation purposes, defaults to false.

description

String describing the policy.

resources

List of the resource name pattern strings to which the policy applies. Must conform to the pattern templates provided by the associated resource type.

applicationName

String containing the policy set name, such as "iPlanetAMWebAgentService", or "mypolicyset".

actionValues

Set of string action names, each set to a boolean indicating whether the action is allowed. Chosen from the available actions provided by the associated resource type.

Action values can also be expressed as numeric values. When using numeric values, use the value 0 for false and use any non-zero numeric value for true.

subject

Specifies the subject conditions to which the policy applies, where subjects can be combined by using the built-in types "AND", "OR", and "NOT", and where subject implementations are pluggable.

Subjects are shown as JSON objects with type set to the name of the implementation (using a short name for all registered subject implementations), and other fields, depending on the implementation. The subject types registered by default include the following:

  • "AuthenticatedUsers", meaning any user that has successfully authenticated to AM.

    {
        "type": "AuthenticatedUsers"
    }

    The AuthenticatedUsers subject condition does not take into account the realm to which a user authenticated. Any user that has authenticated successfully to any realm passes this subject condition.

    To test whether a user has authenticated successfully to a specific realm, add the AuthenticateToRealm environment condition.

  • "Identity" to specify one or more users from an AM identity repository:

    {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com",
            "uid=ahall,ou=People,dc=example,dc=com"
        ]
    }

    You can also use the "Identity" subject type to specify one or more groups from an identity repository:

    {
        "type": "Identity",
        "subjectValues": [
            "cn=HR Managers,ou=Groups,dc=example,dc=com"
        ]
    }
  • "JwtClaim" to specify a claim in a user’s JSON web token (JWT).

    {
        "type": "JwtClaim",
        "claimName": "sub",
        "claimValue": "scarter"
    }
  • "NONE", meaning never match any subject. The result is not that access is denied, but rather that the policy itself does not match and therefore cannot be evaluated in order to allow access.

The following example defines the subject either as the user Sam Carter from an AM identity repository, or as a user with a JWT claim with a subject claim with the value scarter:

{
    "subject": {
        "type": "OR",
        "subjects": [{
                "type": "Identity",
                "subjectValues": [
                    "uid=scarter,ou=People,dc=example,dc=com"
                ]
            },
            {
                "type": "JwtClaim",
                "claimName": "sub",
                "claimValue": "scarter"
            }
        ]
    }
}

To read a single subject type description, or to list all the available subject types, see Manage subject condition types.

condition

Conditions are shown as JSON objects with "type" set to the name of the implementation (using a short name for all registered condition implementations), and other fields depending on the implementation. The condition types registered by default include the following.

  • "AMIdentityMembership" to specify a list of AM users and groups.

    {
        "type": "AMIdentityMembership",
        "amIdentityName": [
            "id=scarter,ou=People,dc=example,dc=com"
        ]
    }

    Java Agents and Web Agents do not support the AMIdentityMembership environment condition. Instead, use the equivalent Identity subject condition.

  • "AuthLevel" to specify the authentication level.

    {
        "type": "AuthLevel",
        "authLevel": 2
    }
  • "AuthScheme" to specify the authentication module used to authenticate, the policy set name, and a timeout for authentication.

    {
        "type": "AuthScheme",
        "authScheme": [
            "DataStore"
        ],
        "applicationName": "iPlanetAMWebAgentService",
        "applicationIdleTimeout": 10
    }
  • "AuthenticateToRealm" to specify the realm to which the user authenticated.

    {
        "type": "AuthenticateToRealm",
        "authenticateToRealm": "MyRealm"
    }
  • "AuthenticateToService" to specify the authentication tree or chain that was used to authenticate.

    {
        "type": "AuthenticateToService",
        "authenticateToService": "MyAuthnTree"
    }
  • "IPv4" or "IPv6" to specify an IP address range from which the request originated.

    {
        "type": "IPv4",
        "startIp": "127.0.0.1",
        "endIp": "127.0.0.255"
    }

    You can also use the "IPv4" and "IPv6" conditions with the "dnsName" field to specify domain names from which the request originated. Omit "startIp" and "endIp" when using "dnsName".

    {
        "type": "IPv4",
        "dnsName": [
            "*.example.com"
        ]
    }
  • "LDAPFilter" to specify an LDAP search filter. The user’s entry is tested against the search filter in the directory configured in the Policy Configuration Service.

    {
        "type": "LDAPFilter",
        "ldapFilter": "(&(c=US)(preferredLanguage=en-us))"
    }
  • "LEAuthLevel" to specify a maximum acceptable authentication level.

    {
        "type": "LEAuthLevel",
        "authLevel": 2
    }
  • "OAuth2Scope" to specify a list of attributes that must be present in the user profile.

    {
        "type": "OAuth2Scope",
        "requiredScopes": [
            "name",
            "address",
            "email"
        ]
    }
  • "ResourceEnvIP" to specify a complex condition such as whether the user is making a request from a given host and has authenticated with a given authentication level. For example:

    {
        "type": "ResourceEnvIP",
        "resourceEnvIPConditionValue": [
            "IF IP=[127.168.10.*] THEN authlevel=4"
        ]
    }

    Entries must take the form of one or more IF…​ELSE statements. If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. The IF statement can specify an IP to match the user’s IP address, or a dnsName to match their DNS name. The IP address can be IPv4 or IPv6 format, or a hybrid of the two, and can include wildcard characters.

    The available parameters for the THEN statement are as follows:

    service

    The service that was used to authenticate the user.

    authlevel

    The minimum required authentication level.

    role

    The role of the authenticated user.

    user

    The name of the authenticated user.

    redirectURL

    The URL the user was redirected from.

    realm

    The realm that was used to authenticate the user.

  • "Session" to specify how long the user’s session has been active, and to terminate the session if it is too old, forcing the user to reauthenticate.

    {
        "type": "Session",
        "maxSessionTime": "10",
        "terminateSession": false
    }
  • "SessionProperty" to specify attributes set in the user’s session.

    {
        "type": "SessionProperty",
        "ignoreValueCase": true,
        "properties": {
            "CharSet": [
                "UTF-8"
            ],
            "clientType": [
                "genericHTML"
            ]
        }
    }
  • "SimpleTime" to specify a time range, where "type" is the only required field.

    {
        "type": "SimpleTime",
        "startTime": "07:00",
        "endTime": "19:00",
        "startDay": "mon",
        "endDay": "fri",
        "startDate": "2015:01:01",
        "endDate": "2015:12:31",
        "enforcementTimeZone": "GMT+0:00"
    }

    The following example defines the condition as neither Saturday or Sunday, nor certain client IP addresses.

    {
        "type": "NOT",
        "condition": {
            "type": "OR",
            "conditions": [
                {
                    "type": "SimpleTime",
                    "startDay": "sat",
                    "endDay": "sun",
                    "enforcementTimeZone": "GMT+8:00"
                },
                {
                    "type": "IPv4",
                    "startIp": "192.168.0.1",
                    "endIp": "192.168.0.255"
                }
            ]
        }
    }

    To read a single condition type description, or to list all the available condition types, see Manage environment condition types.

resourceTypeUuid

The UUIDs of the resource type associated with the policy.

resourceAttributes

List of attributes to return, with decisions. These attributes are known as response attributes, and do not apply to OAuth2 Scope resource types.

The response attribute provider is pluggable. The default implementation provides for statically defined attributes and for attributes retrieved from user profiles.

Attributes are shown as JSON objects: type is set to the name of the implementation (by default "Static" for statically defined attributes or "User" for attributes from the user profile) propertyName is set to the attribute names. For static attributes, "propertyValues" holds the attribute values. For user attributes, "propertyValues" is not used; the property values are determined at evaluation time.

createdBy

A string containing the universal identifier DN of the subject that created the policy.

creationDate

An integer containing the creation date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).

lastModifiedBy

A string containing the universal identifier DN of the subject that most recently updated the policy.

If the policy has not been modified since it was created, this will be the same value as createdBy.

lastModifiedDate

An integer containing the last modified date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).

If the policy has not been modified since it was created, this will be the same value as creationDate.

Before making a REST API call to request manage a policy component, make sure that you have:

  • Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.

  • Obtained the session token returned after successful authentication.

When making a REST API call, specify the realm in the path component of the endpoint.

You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.

Query policies

Use REST calls to list all the policies in a realm, or to find policies that explicitly apply to a given user or group.

List all policies in a realm

  1. To list all the policies in a realm, perform an HTTP GET to the /json/realms/root/realms/realm/policies endpoint, with an _queryFilter parameter set to true.

    The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

    $ curl \
    --header "<session-cookie-name>: AQIC5w…​" \
    --header "Accept-API-Version: resource=1.0, protocol=2.1" \
    "https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/policies?_queryFilter=true"
    {
        "result":[
            {
                "name":"example",
                "active":true,
                "description":"Example Policy",
                "applicationName":"iPlanetAMWebAgentService",
                "actionValues":{
                    "POST":false,
                    "GET":true
                },
                "resources":[
                    "http://www.example.com:80/",
                    "http://www.example.com:80/?*"
                ],
                "subject":{
                    "type":"Identity",
                    "subjectValues":[
                        "uid=demo,ou=People,dc=example,dc=com"
                    ]
                },
                "resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
                "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
                "lastModifiedDate":"2015-05-11T14:48:08.711Z",
                "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
                "creationDate":"2015-05-11T14:48:08.711Z"
            }
        ],
        "resultCount":1,
        "pagedResultsCookie":null,
        "remainingPagedResults":0
    }

    Additional query strings can be specified to alter the returned results. For more information, see Query.

    Supported _queryFilter Fields and Operators
    Field Supported Operators

    name

    Equals (eq)

    description

    Equals (eq)

    applicationName

    Equals (eq)

    createdBy

    Equals (eq)

    creationDate(1)

    Equals (eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)

    lastModifiedBy

    Equals (eq)

    lastModifiedDate(1)

    Equals (eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)

    (1) The implementation of eq for this date field does not use regular expression pattern matching.

Query policies in a realm by user or group

You can query policies that explicitly reference a given subject by providing the universal ID (UID) of either a user or group. AM returns any policies that explicitly apply to the user or group as part of a subject condition.

You can obtain the universal ID for a user or group by using REST.

The following caveats apply to querying policies by user or group:

  • Group membership is not considered. For example, querying policies for a specific user will not return policies that only use groups in their subject conditions, even if the user is a member of any of those groups.

  • Wildcards are not supported, only exact matches.

  • Only policies with a subject condition type of Identity are queried—environment conditions are not queried. The Identity subject condition type is labelled as Users & Groups in the policy editor in the AM admin UI.

  • Policies with subject conditions that only contain the user or group in a logical NOT operator are not returned.

To query policies by user or group:

  1. Perform an HTTP GET to the /json/realms/root/realms/realm/policies endpoint, with an _queryId parameter set to queryByIdentityUid, and a uid parameter containing the universal ID of the user or group:

    $ curl \
    --get \
    --header "<session-cookie-name>: AQIC5w…​" \
    --header "Accept-API-Version: resource=1.0" \
    --data "_queryId=queryByIdentityUid" \
    --data "uid=id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org" \
    "https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/policies"
    {
        "result":[
            {
                "name":"mySubRealmPolicy",
                "active":true,
                "description":"",
                "resources":[
                    "://:*/?",
                    "://:*/*"
                ],
                "applicationName":"iPlanetAMWebAgentService",
                "actionValues":{
                    "POST":true,
                    "PATCH":true,
                    "GET":true,
                    "DELETE":true,
                    "OPTIONS":true,
                    "PUT":true,
                    "HEAD":true
                },
                "subject":{
                    "type":"Identity",
                    "subjectValues":[
                        "id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org"
                    ]
                },
                "resourceTypeUuid":"76656a38-5f8e-401b-83aa-4ccb74ce88d2",
                "lastModifiedBy":"id=amAdmin,ou=user,dc=openam,dc=forgerock,dc=org",
                "lastModifiedDate":"2016-05-05T08:45:35.716Z",
                "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
                "creationDate":"2016-05-03T13:45:38.137Z"
            }
        ],
        "resultCount":1,
        "pagedResultsCookie":null,
        "totalPagedResultsPolicy":"NONE",
        "totalPagedResults":-1,
        "remainingPagedResults":0
    }

    The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Read a specific policy

To read an individual policy in a realm, perform an HTTP GET to the /json/realms/root/realms/realm/policies endpoint, and specify the policy name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/example"
{
    "result": [
        {
            "name": "example",
            "active": true,
            "description": "Example Policy",
            "applicationName": "iPlanetAMWebAgentService",
            "actionValues": {
                "POST": false,
                "GET": true
            },
            "resources": [
                "http://www.example.com:80/",
                "http://www.example.com:80/?*"
            ],
            "subject": {
                "type": "Identity",
                "subjectValues": [
                    "uid=demo,ou=People,dc=example,dc=com"
                ]
            },
            "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4",
            "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "lastModifiedDate": "2015-05-11T14:48:08.711Z",
            "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "creationDate": "2015-05-11T14:48:08.711Z"
        }
    ],
    "resultCount": 1,
    "pagedResultsCookie": null,
    "remainingPagedResults": 0
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Create policies

To create a policy in a realm, perform an HTTP POST to the /json/realms/root/realms/realm/policies endpoint, with an _action parameter set to create. Include a JSON representation of the policy in the POST data.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Configure the OAuth2 Scope resource type only in the Default OAuth2 Scopes Policy Set. Any policy configured for the OAuth2 Scope resource type outside the default policy set will not be evaluated.

Before testing your OAuth 2.0 policies, ensure your OAuth 2.0 service is configured to interact with AM’s Authorization Service. Perform the following steps:

  • Navigate to Realms > Realm Name > Services > OAuth2 Provider

  • Ensure that Use Policy Engine for Scope decisions is enabled.

For more information about testing OAuth 2.0 policies, see Dynamic OAuth 2.0 authorization.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "name": "mypolicy",
    "active": true,
    "description": "My Policy.",
    "applicationName": "iPlanetAMWebAgentService",
    "actionValues": {
        "POST": false,
        "GET": true
    },
    "resources": [
        "http://www.example.com:80/",
        "http://www.example.com:80/?"
    ],
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=demo,ou=People,dc=example,dc=com"
        ]
    },
    "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=create"
{
    "name":"mypolicy",
    "active":true,
    "description":"My Policy.",
    "applicationName":"iPlanetAMWebAgentService",
    "actionValues":{
        "POST":false,
        "GET":true
    },
    "resources":[
        "http://www.example.com:80/",
        "http://www.example.com:80/?"
    ],
    "subject":{
        "type":"Identity",
        "subjectValues":[
            "uid=demo,ou=People,dc=example,dc=com"
        ]
    },
    "resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":"2015-05-11T14:48:08.711Z",
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":"2015-05-11T14:48:08.711Z"
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Update policies

To update an individual policy in a realm, perform an HTTP PUT to the /json/realms/root/realms/realm/policies endpoint, and specify the policy name in the URL. Include a JSON representation of the updated policy in the PUT data.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
 --request PUT \
 --header "<session-cookie-name>: AQIC5w…​" \
 --header "Content-Type: application/json" \
 --header "Accept-API-Version: resource=1.0" \
 --data '{
    "name": "myupdatedpolicy",
    "active": true,
    "description": "My Updated Policy.",
    "resources": [
        "http://www.example.com:80/",
        "http://www.example.com:80/?*"
    ],
    "actionValues": {
        "POST": true,
        "GET": true
    },
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com",
            "uid=bjenson,ou=People,dc=example,dc=com"
        ]
    },
    "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/mypolicy"

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Delete policies

To delete an individual policy in a realm, perform an HTTP DELETE to the /json/realms/root/realms/realm/policies endpoint, and specify the policy name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5w…​" \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/myupdatedpolicy"

Copy and move policies

You can copy or move an individual policy by performing an HTTP POST to the /json/realms/root/realms/realm/policies/policyName endpoint as follows:

  • Specify the _action=copy or _action=move URL parameter.

  • Specify the realm in which the input policy resides in the URL.

  • Specify the policy to be copied or moved in the URL.

  • Specify the SSO token of an administrative user who has access to perform the operation in the iPlanetDirectoryPro header.

JSON input data for copying or moving individual policies
Object Property Description

to

name

The name of the output policy.

Required unless you are copying or moving a policy to a different realm and you want the output policy to have the same name as the input policy.

to

application

The policy set in which to place the output policy.

Required when copying or moving a policy to a different policy set.

to

realm

The realm in which to place the output policy. If not specified, AM copies or moves the policy within the realm identified in the URL.

Required when copying or moving a policy to a different realm.

to

resourceType

The UUID of the output policy’s resource type.

Required when copying or moving a policy to a different realm.

The follow example copies the policy myPolicy to myNewPolicy. The output policy is placed in the myRealm realm, in the same policy set as the input policy:

$ curl \
--header "<session-cookie-name>: AQIC5w…​" \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/myupdatedpolicy"
{}

The following example moves a policy named myPolicy in the myRealm realm to myMovedPolicy in the myOtherRealm realm. The output policy is placed in the iPlanetAMWebAgentService policy set, which is the policy set in which the input policy is located.

The realm myOtherRealm must be configured as follows for the example to run successfully:

  • It must have a resource type that has the same resources as the resource type configured for the myPolicy policy.

  • It must have a policy set named iPlanetAMWebAgentService.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w…​" \
--header "Accept-API-Version: resource=2.1" \
--data '{
    "to": {
        "name": "myMovedPolicy",
        "realm": "/myOtherRealm",
        "resourceType: "616b3d02-7a8d-4422-b6a7-174f62afd065"
    }
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myRealm/policies/myPolicy?_action=move"
{
    "name":"myMovedPolicy",
    "active":true,
    "description":"",
    "actionValues":{},
    "applicationName":"iPlanetAMWebAgentService",
    "resources":["://:*/*"],
    "subject":{"type":"NONE"},
    "resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065",
    "lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com",
    "lastModifiedDate":"2015-12-21T19:32:59.502Z",
    "createdBy":"id=amadmin,ou=user,dc=example,dc=com",
    "creationDate":"2015-12-21T19:32:59.502Z"
}

You can also copy and move multiple policies—all the policies in a policy set—in a single operation by performing an HTTP POST to the /json/realms/root/realms/realm/policies endpoint as follows:

  • Specify the _action=copy or _action=move URL parameter.

  • Specify the realm in which the input policies reside as part of the URL. If no realm is specified in the URL, AM copies or moves policies within the top level realm.

  • Specify the SSO token of an administrative user who has access to perform the operation in the iPlanetDirectoryPro header.

JSON input data for copying or moving multiple policies
Object Property Description

from

application

The policy set in which the input policies are located.

Required.

to

application

The policy set in which to store output policies.

Required when copying or moving policies to a different policy set.

to

realm

The realm in which to store output policies.

Required when copying or moving policies to a different realm.

to

namePostfix

A value appended to output policy names in order to prevent name clashes.

Required.

resourceTypeMapping

Varies

One or more resource types mappings, where the left side of the mapping specifies the UUID of a resource type used by the input policies, and the right side of the mapping specifies the UUID of a resource type used by the output policies. The two resource types should have the same resource patterns.

Required when copying or moving policies to a different realm.

The following example copies all the policies in the iPlanetAMWebAgentService policy set in the myRealm realm to the iPlanetAMWebAgentService policy set in the myOtherRealm realm, appending the string -copy to the output policy names.

The realm myOtherRealm must be configured as follows for the example to run successfully:

  • It must have a resource type that maps to the ccb50c1a-206d-4946-9106-4164e8f2b35b resource type. The two resource types should have the same resource patterns.

  • It must have a policy set named iPlanetAMWebAgentService.

The JSON output shows that a single policy is copied. The policy myNewPolicy is copied to realm myOtherRealm. The copied policy receives the name myOtherRealm-copy:

$ url \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w…​" \
--header "Accept-API-Version: resource=2.1" \
--data '{
    "from":{
        "application":"iPlanetAMWebAgentService"
    },
    "to":{
        "realm":"/myOtherRealm",
        "namePostfix":"-copy"
    },
    "resourceTypeMapping":{
        "ccb50c1a-206d-4946-9106-4164e8f2b35b":"616b3d02-7a8d-4422-b6a7-174f62afd065"
    }
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myRealm/policies?_action=copy"
{
    "name":"myNewPolicy-copy",
    "active":true,
    "description":"",
    "actionValues":{},
    "applicationName":"iPlanetAMWebAgentService",
    "resources":["://:*/*"],"subject":{"type":"NONE"},
    "resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065",
    "lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com",
    "lastModifiedDate":"2015-12-21T20:01:42.410Z",
    "createdBy":"id=amadmin,ou=user,dc=example,dc=com",
    "creationDate":"2015-12-21T20:01:42.410Z"
}

Manage environment condition types

Environment condition types describe the JSON representation of environment conditions that you can use in policy definitions.

AM provides the conditiontypes REST endpoint for the following:

Environment condition types are server-wide, and do not differ by realm. Hence the URI for the condition types API does not contain a realm component, but is /json/conditiontypes.

Script is the only environmental condition available for OAuth 2.0 policies. Use scripts to capture the ClientId environmental attribute.

Environment condition types are represented in JSON and take the following form. Environment condition types are built from standard JSON objects and values (strings, numbers, objects, arrays, true, false, and null).

{
    "title": "IPv4",
    "logical": false,
    "config": {
        "type": "object",
        "properties": {
            "startIp": {
                "type": "string"
            },
            "endIp": {
                "type": "string"
            },
            "dnsName": {
                "type": "array",
                "items": {
                    "type": "string"
                }
            }
        }
    }
}

Notice that the environment condition type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an IPv4 environment condition has two properties, "startIp" and "endIp", that each take a single string value, and a third property, "dnsName," that takes an array of string values. In other words, a concrete IP environment condition specification without a DNS name constraint could be represented in a policy definition as in the following example:

{
    "type": "IPv4",
    "startIp": "127.0.0.1",
    "endIp": "127.0.0.255"
}

The configuration is what differs the most across environment condition types. The NOT condition, for example, takes a single condition object as the body of its configuration.

{
    "title" : "NOT",
    "logical" : true,
    "config" : {
        "type" : "object",
        "properties" : {
            "condition" : {
                "type" : "object",
                    "properties" : {
                }
            }
        }
    }
}

The concrete NOT condition therefore takes the following form.

{
    "type": "NOT",
    "condition": {
        ...
    }
}

The OR condition takes an array of conditions.

{
    "title" : "OR",
    "logical" : true,
    "config" : {
        "type" : "object",
        "properties" : {
            "conditions" : {
                "type" : "array",
                "items" : {
                    "type" : "any"
                }
            }
        }
    }
}

A corresponding concrete OR condition thus takes the following form.

{
    "type": "OR",
    "conditions": [
        {
            ...
        },
        {
            ...
        },
        ...
    ]
}

Query environment condition types

To list all environment condition types, perform an HTTP GET to the /json/conditiontypes endpoint, with a _queryFilter parameter set to true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/conditiontypes?_queryFilter=true'
{
"result" : [
 {
     "title": "IPv4",
     }
     "logical": false,
     "config": {
         "type": "object",
         "properties": {
             "startIp": {
                 "type": "string"
             },
             "endIp": {
                 "type": "string"
             },
             "dnsName": {
                 "type": "array",
                 "items": {
                     "type": "string"
                 }
             }
         }
     }
 },
 {
     "title": "NOT",
     "logical": true,
     "config": {
         "type": "object",
         "properties": {
             "condition": {
                 "type": "object",
                 "properties": { }
             }
         }
     }
 },
 {…​},
 {…​},
 {…​}
],
"resultCount" : 18,
"pagedResultsCookie" : null,
"remainingPagedResults" : 0
}

Additional query strings can be specified to alter the returned results. For more information, see Query.

Read a specific environment condition type

To read an individual environment condition type, perform an HTTP GET to the /json/conditiontypes endpoint, and specify the environment condition type name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/conditiontypes/IPv4'
{
    "title":"IPv4",
    "logical":false,
    "config":{
        "type":"object",
        "properties":{
            "startIp":{
                "type":"string"
            },
            "endIp":{
                "type":"string"
            },
            "dnsName":{
                "type":"array",
                "items":{
                    "type":"string"
                }
            }
        }
    }
}

Manage subject condition types

Subject condition types describe the JSON representation of subject conditions that you can use in policy definitions.

AM provides the subjecttypes REST endpoint for the following:

Environment condition types are server-wide, and do not differ by realm. Hence the URI for the condition types API does not contain a realm component, but is /json/subjecttypes.

Subject condition types are represented in JSON and take the following form. Subject condition types are built from standard JSON objects and values (strings, numbers, objects, arrays, true, false, and null).

{
    "title" : "Identity",
    "logical" : false,
    "config" : {
        "type" : "object",
        "properties" : {
            "subjectValues" : {
                "type" : "array",
                "items" : {
                    "type" : "string"
                }
            }
        }
    }
}

Notice that the subject type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an Identity subject condition has one property, "subjectValues", which takes an array of string values. In other words, a concrete Identity subject condition specification is represented in a policy definition as in the following example:

{
    "type": "Identity",
    "subjectValues": [
        "uid=scarter,ou=People,dc=example,dc=com"
    ]
}

The configuration is what differs the most across subject condition types. The AND condition, for example, takes an array of subject condition objects as the body of its configuration.

{
    "title" : "AND",
    "logical" : true,
    "config" : {
        "type" : "object",
        "properties" : {
            "subjects" : {
                "type" : "array",
                "items" : {
                    "type" : "any"
                }
            }
        }
    }
}

The concrete AND subject condition therefore takes the following form.

{
    "type": "AND",
    "subject": [
        {...},
        {...},
        {...},
        {...}
    ]
}

Query subject condition types

To list all environment condition types, perform an HTTP GET to the /json/subjecttypes endpoint, with a _queryFilter parameter set to true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjecttypes?_queryFilter=true'
{
    "result" : [
        {
            "title": "JwtClaim"
            }
            "logical": false,
            "config": {
                "type": "object",
                "properties": {
                    "claimName": {
                        "type": "string"
                    },
                    "claimValue": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "title": "NOT",
            "logical": true,
            "config": {
                "type": "object",
                "properties": {
                    "subject": {
                        "type": "object",
                        "properties": { }
                    }
                }
            }
        },
        {…​},
        {…​},
        {…​}
    ],
    "resultCount" : 5,
    "pagedResultsCookie" : null,
    "remainingPagedResults" : 0
}

Additional query strings can be specified to alter the returned results. For more information, see Query.

Read a specific subject condition type

To read an individual subject condition type, perform an HTTP GET to the /json/subjecttypes endpoint, and specify the subject condition type name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjecttypes/Identity'
{
    "title" : "Identity",
    "logical" : false,
    "config" : {
        "type" : "object",
        "properties" : {
            "subjectValues" : {
                "type" : "array",
                "items" : {
                    "type" : "string"
                }
            }
        }
    }

Manage subject attributes

When you define a policy subject condition, the condition can depend on values of subject attributes stored in a user’s profile. The list of possible subject attributes that you can use depends on the LDAP User Attributes configured for the identity store where AM looks up the user’s profile.

AM provides the subjectattributes REST endpoint for Query subject attributes.

Subject attributes derive from the list of LDAP user attributes configured for the identity store.

Query subject attributes

To list all subject attributes, perform an HTTP GET to the /json/subjectattributes endpoint, with a _queryFilter parameter set to true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjectattributes/?_queryFilter=true'
{
  "result" : [
      "sunIdentityServerPPInformalName",
      "sunIdentityServerPPFacadeGreetSound",
      "uid",
      "manager",
      "sunIdentityServerPPCommonNameMN",
      "sunIdentityServerPPLegalIdentityGender",
      "preferredLocale",
      "…​",
      "…​",
      "…​"
  ],
  "resultCount": 87,
  "pagedResultsCookie": null,
  "remainingPagedResults": 0
}

Note that no pagination cookie is set and the subject attribute names are all returned as part of the "result" array.

Manage decision combiners

Decision combiners describe how to resolve policy decisions when multiple policies apply.

AM provides the decisioncombiners REST endpoint for the following:

Decision combiners are server-wide, and do not differ by realm. Hence, the URI for the condition types API does not contain a realm component, but is /json/decisioncombiners.

Query decision combiners

To list all decision combiners, perform an HTTP GET to the /json/decisioncombiners endpoint, with a _queryFilter parameter set to true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/decisioncombiners?_queryFilter=true'
{
    "result":[
        {
            "title":"DenyOverride"
        }
    ],
    "resultCount":1,
    "pagedResultsCookie":null,
    "remainingPagedResults":0
}

Additional query strings can be specified to alter the returned results. For more information, see Query.

Read a specific decision combiner

To view an individual decision combiner, perform an HTTP GET on its resource.

To read an individual decision combiner, perform an HTTP GET to the /json/decisioncombiners endpoint, and specify the decision combiner name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/decisioncombiners/DenyOverride'
{
  "title" : "DenyOverride"
}

Resource types

Resource types define a template for the resources that policies apply to, and the actions that can be performed on those resources.

AM needs a policy to decide whether a user can access a resource. When you configure a policy, you also configure a resource (or a pattern to match several resources) that the policy applies to, and the actions that the policy allows or denies.

Resource types are templates that you can define once and reuse in several policies. For example, you could create a template that always allows PUT and POST operations from your internal network.

Default resource types

AM includes two resource types by default: URL and OAuth2 Scope. These default resource types are sufficient for most environments.

URL resource type

The URL resource type acts as a template for protecting web pages or applications. It contains resource patterns, such as *://*:*/*?*, that can be more specific when used in the policy.

This resource type supports the following actions:

GET
POST
PUT
HEAD
PATCH
DELETE
OPTIONS

For example, an application for Example.com’s HR service might contain resource types that constrain all policies to apply to URL resource types under http*://example.com/hr* and http*://example.com/hr*?*, and only allow HTTP GET and POST actions.

AM also includes a resource type to protect REST endpoints, with patterns including https://*:*/*?* and the CRUDPAQ actions:

CREATE
READ
UPDATE
DELETE
PATCH
ACTION
QUERY

OAuth2 Scope resource type

The OAuth2 Scope resource type acts as a template for granting or denying OAuth 2.0 scopes. It contains a string-based scope pattern, *, and two URL-based scope patterns, such as *://*:*/*?*. The resource supports the GRANT action, which can be allowed or denied.

Resource types in the UI

  1. In the AM admin UI, go to Realms > Realm Name > Authorization > Resource Types.

    • To create a new resource type, click New Resource Type.

    • To modify an existing resource type, select the resource type name.

    • To delete an existing resource type, click Delete in the row containing the resource type.

      You can only delete resource types that are not being used by policy sets or policies. Trying to delete a resource type that is in use returns an HTTP 409 Conflict status code.

      Remove the resource type from any associated policy sets or policies to be able to delete it.

  2. Provide a name for the resource type, and optionally, a description.

    Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

  3. To define resource patterns that policies using this resource type can expand upon, follow the steps below:

    • In the Add a new pattern…​ box, enter a pattern with optional wildcards that the policies will use as a template.

      Specify resource patterns with wildcards

      Resource patterns can specify an individual URL or resource name to protect. Alternatively, a resource pattern can match URLs or resource names by using wildcards.

      • The wildcards you can use are * and -*-.

        These wildcards can be used throughout resource patterns to match URLs or resource names. For a resource pattern used to match URLs, wildcards can be employed to match the scheme, host, port, path, and query string of a resource.

        • When used within the path segment of a resource, the wildcard * matches multiple path segments.

          For example, http://www.example.com/* matches http://www.example.com/, http://www.example.com/index.html, and also http://www.example.com/company/images/logo.png.

        • When used within the path segment of a resource, the wildcard -*- will only match a single path segment.

          For example, http://www.example.com/-*- matches http://www.example.com/index.html, but does not match http://www.example.com/company/resource.html or http://www.example.com/company/images/logo.png.

      • Wildcards do not match ?. You must explicitly add patterns to match URLs with query strings.

        • When matching URLs sent from a web or Java agent, an asterisk (*) used at the end of a pattern after a ? character matches one or more characters, not zero or more characters.

          For example, http://www.example.com/*?* matches http://www.example.com/users?_action=create, but not http://www.example.com/users?.

          To match everything under http://www.example.com/ specify three patterns, one for http://www.example.com/*, one for http://www.example.com/*?, and one for http://www.example.com/*?*.

        • When matching resources by using the policies?_action=evaluate REST endpoint, an asterisk (kbd:[*]) used at the end of a pattern after a ? character matches zero or more characters.

          For example, http://www.example.com/*?* matches http://www.example.com/users?_action=create, as well as http://www.example.com/users?.

          To match everything under http://www.example.com/ specify two patterns, one for http://www.example.com/*, one for http://www.example.com/*?*.

      • When defining patterns to match URLs with query strings, AM sorts the query string field-value pairs alphabetically by field name when normalizing URLs before checking whether a policy matches. Therefore, the query string ?subject=SPBnfm+t5PlP+ISyQhVlplE22A8=&action=get is equivalent to the query string ?action=get&subject=SPBnfm+t5PlP+ISyQhVlplE22A8=.

      • Duplicate slashes (/) are not considered part of the resource name to match. A trailing slash is considered by AM as part of the resource name.

        For example, http://www.example.com//path/, and http://www.example.com/path// are treated in the same way.

        http://www.example.com/path, and http://www.example.com/path/ are considered two distinct resources.

      • Wildcards can be used to match protocols, host names, and port numbers.

        For example, *://*:*/* matches http://www.example.com:80/index.html, https://www.example.com:443/index.html, and http://www.example.net:8080/index.html.

        When a port number is not explicitly specified, then the default port number is implied. Therefore http://www.example.com/* is the same as http://www.example.com:80/*, and https://www.example.com/* is the same as https://www.example.com:443/*.

      • Wildcards cannot be escaped.

      • Do not mix * and -*- in the same pattern.

      • To match a resource that uses non-ASCII characters, percent-encode the resource when creating the rule.

        For example, to match resources under an Internationalized Resource Identifier (IRI), such as http://www.example.com/forstå, specify the following percent-encoded pattern:

        http://www.example.com:80/forst%C3%A5/*
      • By default, comparisons are not case-sensitive. The delimiter, wildcards and case-sensitivity are configurable.

    • Click +Add Pattern to confirm the pattern.

      To remove a pattern, select the Delete icon.
  4. To define the actions that policies using this resource type can allow or deny, follow the steps below:

    • In the Add a new action…​ box, enter an action related to the types of resources being described, and click +Add Action.

    • Select either Allow or Deny as the default state for the action.

    To remove an action, select the Delete icon.

  5. Continue adding the patterns and actions that your resource type requires.

    Add the patterns and actions that policies using this resource type can make use of.
    Figure 8. Configuring Resource Types in the UI
  6. Select Create to save a new resource type or Save Changes to save modifications to an existing resource type.

Resource types over REST

You can manage resource types over REST at the resourcetypes endpoint.

Resource types are realm-specific. The URI for the resource types API can therefore contain a realm component, for example, json/realms/root/realms/myRealm/resourcetypes.

Resource types take the form of standard JSON objects and values (strings, numbers, objects, sets, arrays, true, false, and null). Each resource type has a unique, system-generated UUID, which must be used when modifying existing resource types. Renaming a resource type does not affect the UUID.

Example
{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e2",
    "name": "URL",
    "description": "The built-in URL Resource Type available to OpenAM Policies.",
    "patterns": [
        "*://*:*/*?*",
        "*://*:*/*"
    ],
    "actions": {
        "POST": true,
        "PATCH": true,
        "GET": true,
        "DELETE": true,
        "OPTIONS": true,
        "HEAD": true,
        "PUT": true
    },
    "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": 1422892465848,
    "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": 1422892465848
}

A resource type object can include the following fields:

uuid

String matching the unique identifier AM generated for the resource type when created.

name

The name provided for the resource type.

description

An optional text string to help identify the resource type.

patterns

An array of resource patterns specifying individual URLs or resource names to protect.

For more information on patterns in resource types and policies, see Specifying Resource Patterns with Wildcards.

actions

Set of string action names, each set to a boolean indicating whether the action is allowed.

createdBy

A string containing the universal identifier DN of the subject that created the resource type.

creationDate

An integer containing the creation date and time, in ISO 8601 format.

lastModifiedBy

A string containing the universal identifier DN of the subject that most recently updated the resource type.

If the resource type has not been modified since it was created, this will be the same value as createdBy.

lastModifiedDate

An string containing the last modified date and time, in ISO 8601 format.

If the resource type has not been modified since it was created, this will be the same value as creationDate.

Before making a REST API call to manage a resource type, make sure that you have:

  • Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.

  • Obtained the session token returned after successful authentication.

When making a REST API call, specify the realm in the path component of the endpoint.

You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.

Query resource types

To list all the resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes endpoint, with _queryFilter=true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes?_queryFilter=true'
{
    "result":[
        {
            "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
            "name":"LIGHTS",
            "description":"",
            "patterns":[
                "light:///"
            ],
            "actions":{
                "switch_off":true,
                "switch_on":true
            },
            "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "creationDate":1431013059131,
            "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "lastModifiedDate":1431013069803
        }
    ],
    "resultCount":1,
    "pagedResultsCookie":null,
    "remainingPagedResults":0
}

Additional query strings can be specified to alter the returned results. For more information, see Query.

Supported _queryFilter Fields and Operators
Field Supported Operators

uuid

Equals (eq), Contains (co), Starts with (sw)

name

Equals (eq), Contains (co), Starts with (sw)

description

Equals (eq), Contains (co), Starts with (sw)

patterns

Equals (eq), Contains (co), Starts with (sw)

actions

Equals (eq), Contains (co), Starts with (sw)

Read a resource type

To read a specific resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e3'
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
    "name":"LIGHTS",
    "description":"",
    "patterns":[
        "light:///"
    ],
    "actions":{
        "switch_off":true,
        "switch_on":true
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431013059131,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1431013069803
}

Create a resource type

To create a resource type in a realm, send an HTTP POST request to the /json/realms/root/realms/realm/resourcetypes endpoint, with _action=create. Include a JSON representation of the resource type in the POST data.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "name":"My Resource Type",
    "actions":{
        "LEFT":true,
        "RIGHT":true,
        "UP":true,
        "DOWN":true
    },
    "patterns":[
        "http://device/location/"
    ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/?_action=create'
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name":"My Resource Type",
    "description":null,
    "patterns":[
        "http://device/location/"
    ],
    "actions":{
        "RIGHT":true,
        "DOWN":true,
        "UP":true,
        "LEFT":true
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431099940616,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1431099940616
}

Update a resource type

To update a specific resource type in a realm, send an HTTP PUT request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in both the URL and the PUT body. Include a JSON representation of the updated resource type in the PUT data, alongside the UUID.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "name":"My Resource Type",
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4"
    "actions":{
        "LEFT":true,
        "RIGHT":true,
        "UP":false,
        "DOWN":false
    },
    "patterns":[
        "http://device/location/"
    ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name":"My Resource Type",
    "description":null,
    "patterns":[
        "http://device/location/"
    ],
    "actions":{
        "RIGHT":true,
        "DOWN":true,
        "UP":false,
        "LEFT":false
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431099940616,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1637667798885
}

Delete a resource type

To delete a specific resource types in a realm, send an HTTP DELETE request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--request DELETE \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{}

You can only delete resource types that are not being used by a policy set or policy. If you attempt to delete a resource type that is in use, AM returns an HTTP 409 Conflict status code, with a message such as:

{
    "code": 409,
    "reason": "Conflict",
    "message": "Unable to remove resource type 12345a67-8f0b-123c-45de-6fab78cd01e4 because it is
                referenced in the policy model."
}

Remove the resource type from any associated policy sets or policies before you delete it.

Policy sets

Policy sets are associated with a set of resource types, and contain one or more policies based upon the template it provides. They are used as templates for policies protecting websites, web applications, or other resources.

For AM to decide if a user can access a resource, it requires a policy.

Policy sets are a way to group policies that protect applications or sites that have similar characteristics. For example, they all use the same resource type. This means that you do not need to configure the same set of parameters in each policy.

AM includes two policy sets that are used for web and Java agents, and for dynamic OAuth 2.0 policies.

Policy sets have templates, called application types. There are two application types defined by default, which correspond to the default policy sets. You can only configure these using REST, but for most use cases, you can use the default application types.

Default policy sets

AM includes the following default policy sets:

  • The Default Policy Set, iPlanetAMWebAgentService is the policy set configured by default for web and Java agents. You can create new policy sets for agents and configure them in the agent profile.

  • The Default OAuth2 Scopes Policy Set, oauth2Scopes, is the policy set configured for the OAuth 2.0 service on the realm.

    The OAuth 2.0 service cannot be configured to use a different policy set. Configure all policies required for your OAuth 2.0 service in the Default OAuth2 Scopes Policy Set.

When creating or editing policy sets, consider the following points:

  • When the realm and policy set differ for your web or Java agent, you can specify the realm and policy set in the agent profile. AM then directs requests from the agent to the specified realm and policy set, so this is backwards compatible with existing web and Java agents.

    You can configure the realm and policy set the agent uses in the agent profile. See the ForgeRock web agents documentation, or the ForgeRock Java agents documentation for more information.

  • AM only honors OAuth2 Scope resource type policies configured in the Default OAuth2 Scopes Policy Set. Configure all policies required for your OAuth 2.0 service in the Default OAuth2 Scopes Policy Set.

  • AM creates a policy set containing a policy representing the resources and identities specified by a resource owner using UMA 2.0 to share their registered resources.

    These policies appear in the AM admin UI as read-only, and cannot be edited by administrative users such as amAdmin. They can, however, be viewed and deleted.

Manage policy sets using the AM admin UI or the REST API:

Policy sets in the UI

  1. In the AM admin UI, go to Realms > Realm Name > Authorization > Policy Sets.

    • To create a new policy set, select New Policy Set.

    • To modify an existing policy set, select it from the table.

  2. If creating a new policy, enter an ID for the policy set. This is a required parameter.

    Once a policy set is created, you cannot change its ID.

  3. If creating a new policy, enter a name for the policy set. The name is optional and is for display purposes only.

    Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

  4. From the Resource Types drop-down list, select one or more resource types that policies in this policy set will use.

    To remove a resource type from the policy set, select the label, and then press kbd:[Delete] or kbd:[Backspace].

    Configure the OAuth2 Scope resource type only in the Default OAuth2 Scopes Policy Set. Any policy configured for the OAuth2 Scope resource type outside the default policy set will not be evaluated.

  5. Select Create to save the new policy set, or Save Changes to save modifications to an existing policy set.

Policy sets over REST

You can manage policy sets over REST at the applications endpoint.

Policy sets are realm-specific. The URI for the policy set API can therefore contain a realm component, for example, /json/realms/root/realms/realm/applications.

Policy sets take the form of standard JSON objects and values (strings, numbers, objects, sets, arrays, true, false, and null).

Example
{
    "creationDate": 1431351677264,
    "lastModifiedDate": 1431351677264,
    "conditions": [
        "AuthenticateToService",
        "Script",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "AuthLevel",
        "SessionProperty",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType": "iPlanetAMWebAgentService",
    "subjects": [
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "NONE",
        "OR"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "resourceComparator": null,
    "resourceTypeUuids": [
        "12345a67-8f0b-123c-45de-6fab78cd01e4"
    ],
    "attributeNames": [ ],
    "editable": true,
    "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "description": "The built-in Application used by {am_abbr} Policy Agents.",
    "realm": "/",
    "name": "iPlanetAMWebAgentService"
}

A policy set object can include the following fields:

conditions

Condition types allowed in the context of this policy set.

For information on condition types, see Policies over REST and Managing Environment Condition Types.

applicationType

Name of the application type used as a template for this policy set.

subjects

Subject types allowed in the context of this policy set.

For information on subject types, see Policies over REST and Managing Subject Condition Types.

entitlementCombiner

Name of the decision combiner, such as "DenyOverride".

For more on decision combiners, see Managing Decision Combiners.

saveIndex

Class name of the implementation for creating indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameIndexGenerator", for URL resource names.

searchIndex

Class name of the implementation for searching indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameSplitter", for URL resource names.

resourceComparator

Class name of the resource comparator implementation used in the context of this policy set.

The following implementations are available:

"com.sun.identity.entitlement.ExactMatchResourceName"
"com.sun.identity.entitlement.PrefixResourceName"
"com.sun.identity.entitlement.RegExResourceName"
"com.sun.identity.entitlement.URLResourceName"

resourceTypeUuids

A list of the UUIDs of the resource types associated with the policy set.

attributeNames

A list of attribute names such as cn. The list is used to aid policy indexing and lookup.

description

String describing the policy set.

realm

Name of the realm in which this policy set is defined. You must specify the realm in the policy set JSON, even though it can be derived from the URL that is used when creating the policy set.

name

String matching the name in the URL used when creating the policy set by HTTP PUT, or in the body when creating the policy set by HTTP POST.

createdBy

A string containing the universal identifier DN of the subject that created the policy set.

creationDate

An integer containing the creation date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).

lastModifiedBy

A string containing the universal identifier DN of the subject that most recently updated the policy set.

If the policy set has not been modified since it was created, this will be the same value as createdBy.

lastModifiedDate

An integer containing the last modified date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).

If the policy set has not been modified since it was created, this will be the same value as creationDate.

Before making a REST API call to request manage a policy component, make sure that you have:

  • Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.

  • Obtained the session token returned after successful authentication.

When making a REST API call, specify the realm in the path component of the endpoint.

You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.

Query policy sets

To list all the policy sets in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/applications endpoint, with _queryFilter=true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications?_queryFilter=true'
{
   "result": [
     {
       "resourceComparator": null,
       "saveIndex": null,
       "searchIndex": null,
       "applicationType": "iPlanetAMWebAgentService",
       "entitlementCombiner": "DenyOverride",
       "subjects": [
         "AuthenticatedUsers",
         "NOT",
         "Identity",
         "OR",
         "AND",
         "NONE",
         "JwtClaim"
       ],
       "attributeNames": [],
       "editable": true,
       "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "name": "iPlanetAMWebAgentService",
       "description": "The built-in Application used by OpenAM Policy Agents.",
       "conditions": [
         "Script",
         "AMIdentityMembership",
         "IPv6",
         "IPv4",
         "SimpleTime",
         "LEAuthLevel",
         "LDAPFilter",
         "AuthScheme",
         "Session",
         "AND",
         "AuthenticateToRealm",
         "ResourceEnvIP",
         "OAuth2Scope",
         "SessionProperty",
         "OR",
         "Transaction",
         "NOT",
         "AuthLevel",
         "AuthenticateToService"
       ],
       "creationDate": 1637661939155,
       "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "lastModifiedDate": 1637661939155,
       "actions": {
         "HEAD": true,
         "DELETE": true,
         "POST": true,
         "GET": true,
         "OPTIONS": true,
         "PUT": true,
         "PATCH": true
       },
       "resources": [
         "://:*/",
         "://:/?"
       ],
       "realm": "/"
     },
     {
       "resourceComparator": null,
       "saveIndex": null,
       "searchIndex": null,
       "applicationType": "sunAMDelegationService",
       "entitlementCombiner": "DenyOverride",
       "subjects": [
         "OR",
         "AND",
         "AuthenticatedUsers",
         "NOT",
         "Identity"
       ],
       "attributeNames": [],
       "editable": true,
       "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "name": "sunAMDelegationService",
       "description": null,
       "conditions": [],
       "creationDate": 1637661944233,
       "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "lastModifiedDate": 1637661944233,
       "actions": {
         "READ": true,
         "MODIFY": true,
         "DELEGATE": true
       },
       "resources": [
         "sms://:/",
         "sms://:*/?"
       ],
       "realm": "/"
     },
     {
       "resourceComparator": null,
       "saveIndex": null,
       "searchIndex": null,
       "applicationType": "iPlanetAMWebAgentService",
       "entitlementCombiner": "DenyOverride",
       "subjects": [
         "AuthenticatedUsers",
         "NOT",
         "Identity",
         "OR",
         "AND",
         "NONE",
         "JwtClaim"
       ],
       "attributeNames": [],
       "editable": true,
       "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "name": "oauth2Scopes",
       "description": "The built-in Application used by the OAuth2 scope authorization process.",
       "conditions": [
         "Script",
         "AMIdentityMembership",
         "IPv6",
         "IPv4",
         "SimpleTime",
         "LEAuthLevel",
         "LDAPFilter",
         "AuthScheme",
         "Session",
         "AND",
         "AuthenticateToRealm",
         "ResourceEnvIP",
         "OAuth2Scope",
         "SessionProperty",
         "OR",
         "Transaction",
         "NOT",
         "AuthLevel",
         "AuthenticateToService"
       ],
       "creationDate": 1637661944239,
       "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
       "lastModifiedDate": 1637661944239,
       "actions": {
         "GRANT": true
       },
       "resources": [
         "://:*/",
         "://:/?",
         "*"
       ],
       "realm": "/"
     }
   ],
   "resultCount": 3,
   "pagedResultsCookie": null,
   "totalPagedResultsPolicy": "NONE",
   "totalPagedResults": -1,
   "remainingPagedResults": 0
 }

Additional query strings can be specified to alter the returned results. For more information, see Query.

Supported _queryFilter Fields and Operators
Field Supported Operators

name

Equals (eq)

description

Equals (eq)

createdBy

Equals (eq)

creationDate(1)

Equals (eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)

lastModifiedBy

Equals (eq)

lastModifiedDate(1)

Equals (eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)

(1) The implementation of eq for this date field does not use regular expression pattern matching.

Read a policy set

To read a specific policy set in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/applications endpoint, specifying the policy set name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/mypolicyset'
{
    "creationDate":1431360678810,
    "lastModifiedDate":1431360678810,
    "conditions":[
        "AuthenticateToService",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "SessionProperty",
        "AuthLevel",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType":"iPlanetAMWebAgentService",
    "subjects":[
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner":"DenyOverride",
    "saveIndex":null,
    "searchIndex":null,
    "resourceComparator":"com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids":[
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "attributeNames":[

    ],
    "editable":true,
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "description":"My example policy set.",
    "realm":"/",
    "name":"mypolicyset"
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Create a policy set

To create a policy set in a realm, send an HTTP POST request to the /json/realms/root/realms/realm/applications endpoint, with _action=create. Include a JSON representation of the policy set in the POST data.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=2.1" \
--data '{
    "name":"mypolicyset",
    "resourceTypeUuids":[
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "realm":"/",
    "conditions":[
        "AND",
        "OR",
        "NOT",
        "AMIdentityMembership",
        "AuthLevel",
        "AuthScheme",
        "AuthenticateToRealm",
        "AuthenticateToService",
        "IPv4",
        "IPv6",
        "LDAPFilter",
        "LEAuthLevel",
        "OAuth2Scope",
        "ResourceEnvIP",
        "Session",
        "SessionProperty",
        "SimpleTime"
    ],
    "applicationType":"iPlanetAMWebAgentService",
    "description":"My example policy set.",
    "resourceComparator":"com.sun.identity.entitlement.URLResourceName",
    "subjects":[
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity",
        "JwtClaim"
    ],
    "entitlementCombiner":"DenyOverride",
    "saveIndex":null,
    "searchIndex":null,
    "attributeNames":[

    ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/?_action=create'
{
    "creationDate":1431360678810,
    "lastModifiedDate":1431360678810,
    "conditions":[
        "AuthenticateToService",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "SessionProperty",
        "AuthLevel",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType":"iPlanetAMWebAgentService",
    "subjects":[
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner":"DenyOverride",
    "saveIndex":null,
    "searchIndex":null,
    "resourceComparator":"com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids":[
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "attributeNames":[],
    "editable":true,
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "description":"My example policy set.",
    "realm":"/",
    "name":"mypolicyset"
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Update a policy set

To update a specific policy set in a realm, send an HTTP PUT request to the /json/realms/root/realms/realm/applications endpoint, specifying the policy set name in the URL. Include a JSON representation of the updated policy set in the PUT data.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request PUT \
--header "<session-cookie-name>: AQIC5…​" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.1" \
--data '{
    "name":"myupdatedpolicyset",
    "description":"My updated policy set - new name and fewer allowable conditions/subjects.",
    "conditions":[
        "NOT",
        "SimpleTime"
    ],
    "subjects":[
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity"
    ],
    "applicationType":"iPlanetAMWebAgentService",
    "entitlementCombiner":"DenyOverride",
    "resourceTypeUuids":[
        "76656a38-5f8e-401b-83aa-4ccb74ce88d2"
    ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/mypolicyset'
{
    "creationDate":1431362370739,
    "lastModifiedDate":1431362390817,
    "conditions":[
        "NOT",
        "SimpleTime"
    ],
    "resourceComparator":"com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids":[
        "76656a38-5f8e-401b-83aa-4ccb74ce88d2"
    ],
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "applicationType":"iPlanetAMWebAgentService",
    "subjects":[
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner":"DenyOverride",
    "saveIndex":null,
    "searchIndex":null,
    "attributeNames":[

    ],
    "editable":true,
    "description":"My updated policy set - new name and fewer allowable conditions/subjects.",
    "realm":"/",
    "name":"myupdatedpolicyset"
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Delete a policy set

To delete a specific policy set in a realm, send an HTTP DELETE request to the /json/realms/root/realms/realm/applications endpoint, specifying the policy set name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--request DELETE \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/myupdatedpolicyset'

Policy set application types over REST

Application types act as templates for policy sets, and define how to compare resources and index policies. AM provides a default application type that represents web resources called iPlanetAMWebAgentService. AM web and Java agents use a default policy set that is based on this type, which is also called iPlanetAMWebAgentService.

AM provides the applicationtypes REST endpoint for the following:

Applications types are server-wide, and do not differ by realm. Hence the URI for the application types API does not contain a realm component, but is /json/applicationtypes.

Application type resources are represented in JSON and take the following form. Application type resources are built from standard JSON objects and values (strings, numbers, objects, arrays, true, false, and null).

Example
{
    "name": "iPlanetAMWebAgentService",
    "actions": {
        "POST": true,
        "PATCH": true,
        "GET": true,
        "DELETE": true,
        "OPTIONS": true,
        "PUT": true,
        "HEAD": true
    },
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "saveIndex": "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
    "searchIndex": "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
    "applicationClassName": "com.sun.identity.entitlement.Application"
}

The values for the fields shown in the description are explained below:

"name"

The name provided for the application type.

"actions"

Set of string action names, each set to a boolean indicating whether the action is allowed.

"resourceComparator"

Class name of the resource comparator implementation used in the context of this application type.

The following implementations are available:

"com.sun.identity.entitlement.ExactMatchResourceName"
"com.sun.identity.entitlement.PrefixResourceName"
"com.sun.identity.entitlement.RegExResourceName"
"com.sun.identity.entitlement.URLResourceName"

"saveIndex"

Class name of the implementation for creating indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameIndexGenerator", for URL resource names.

"searchIndex"

Class name of the implementation for searching indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameSplitter", for URL resource names.

"applicationClassName"

Class name of the application type implementation, such as "com.sun.identity.entitlement.Application".

Query application types

To list all application types, perform an HTTP GET to the /json/applicationtypes endpoint, with a _queryFilter parameter set to true.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applicationtypes?_queryFilter=true'
{
    "result" : [ …​ application types …​ ],
    "resultCount" : 8,
    "pagedResultsCookie" : null,
    "remainingPagedResults" : -1
}

Additional query strings can be specified to alter the returned results. For more information, see Query.

Read a specific application type

To read an individual application type, perform an HTTP GET to the /json/applicationtypes endpoint, and specify the application type name in the URL.

The <session-cookie-name> header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "<session-cookie-name>: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applicationtypes/iPlanetAMWebAgentService'
{
    "name": "iPlanetAMWebAgentService",
    "actions": {
        "POST": true,
        "PATCH": true,
        "GET": true,
        "DELETE": true,
        "OPTIONS": true,
        "PUT": true,
        "HEAD": true
    },
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "saveIndex": "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
    "searchIndex": "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
    "applicationClassName": "com.sun.identity.entitlement.Application"
}

Request authorization from AM

Once you have configured AM to determine whether to grant or deny access based on the policies you created, you must configure your policy enforcement points (PEP) to use AM.

The ForgeRock Identity Platform provides the following PEPs:

The ForgeRock Identity Platform PEP’s intercept inbound client requests to access a resource in your web site or application. Then, based on internal rules, they may defer the request to AM for policy evaluation. Since they are tightly integrated with AM, you do not need to add additional code to request policy evaluation or manage advices.

We recommend that you use the ForgeRock Identity Platform PEP’s. However, you can code your own and make REST calls to AM to request policy evaluation.

Related information: Request policy decisions over REST

Request policy decisions over REST

You can request policy decisions from AM by using the REST API described in this page. AM evaluates requests based on the context and the policies configured, and returns decisions that indicate what actions are allowed or denied, as well as any attributes or advice for the resources specified.

This section does not apply to OAuth 2.0 policies.

AM provides the /json/realms/root/policies endpoint to request policy evaluation.

When making a REST API call, specify the realm in the path component of the endpoint.

Before making a REST API call to request manage a policy component, make sure that you have:

  • Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.

  • Obtained the session token returned after successful authentication.

When making the REST API call, pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.

To request decisions for specific resources, see Request policy decisions for specific resources.

To request decisions for a resource and all resources beneath it, see Request policy decisions for a tree of resources.

Request policy decisions for specific resources

This section shows how you can request a policy decision over REST for specific resources.

When making a REST API call, specify the realm in the path component of the endpoint.

To request policy decisions for specific resources, perform an HTTP POST using the evaluation action to the appropriate path under the URI where AM is deployed, /json{/realm/root}/policies?_action=evaluate. The payload for the HTTP POST is a JSON object that specifies at least the resources, and takes the following form.

{
    "resources": [
        "resource1",
        "resource2",
        ...,
        "resourceN"
    ],
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The values for the fields shown above are explained below:

"resources"

This required field specifies the list of resources for which to return decisions.

For example, when using the default policy set, "iPlanetAMWebAgentService", you can request decisions for resource URLs.

{
    "resources": [
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ]
}
"application"

This field holds the name of the policy set, and defaults to "iPlanetAMWebAgentService" if not specified.

For more on policy sets, see Policy sets over REST.

"subject"

This optional field holds an object that represents the subject. You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.

"ssoToken"

The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.

You can use an OpenID Connect ID token if the client that the token has been issued for is authorized to use ID tokens as session tokens. For more information, see Using ID Tokens as Session Tokens.

"jwt"

The value is a JWT string.

"claims"

The value is an object (map) of JWT claims to their values. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.

"environment"

This optional field holds a map of keys to lists of values.

If you do not specify the environment, the default is an empty map.

The example below requests policy decisions for two URL resources. The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.1" \
--header "<session-cookie-name>: AQIC5…​" \
--data '{
    "resources":[
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ],
    "application":"iPlanetAMWebAgentService"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate"
[
    {
        "resource":"http://www.example.com/do?action=run",
        "actions":{

        },
        "attributes":{

        },
        "advices":{
            "AuthLevelConditionAdvice":[
                "3"
            ]
        }
    },
    {
        "resource":"http://www.example.com/index.html",
        "actions":{
            "POST":false,
            "GET":true
        },
        "attributes":{
            "cn":[
                "demo"
            ]
        },
        "advices":{

        }
    }
]

In the JSON list of decisions returned for each resource, AM includes these fields.

"resource"

A resource specified in the request.

The decisions returned are not guaranteed to be in the same order as the resources were requested.

"actions"

A map of action name keys to Boolean values that indicate whether the action is allowed (true) or denied (false) for the specified resource.

In the example, for resource http://www.example.com:80/index.html HTTP GET is allowed, whereas HTTP POST is denied.

"attributes"

A map of attribute names to their values, if any response attributes are returned according to applicable policies.

In the example, the policy that applies to http://www.example.com:80/index.html causes that the value of the subject’s "cn" profile attribute to be returned.

"advices"

A map of advice names to their values, if any advice is returned according to applicable policies.

The "advices" field can provide hints regarding what AM needs to take the authorization decision.

In the example, the policy that applies to http://www.example.com:80/do?action=run requests that the subject be authenticated at an authentication level of at least 3.

{
    "advices": {
        "AuthLevelConditionAdvice": [
            "3"
        ]
    }
}

See Policy decision advice for details.

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Policy decision advice

When AM returns a policy decision, the JSON for the decision can include an "advices" field. This field contains hints for the policy enforcement point.

{
    "advices": {
        "type": [
            "advice"
        ]
    }
}

The "advices" returned depend on policy conditions. For more information about AM policy conditions, see Policies over REST.

This section shows examples of the different types of policy decision advice and the conditions that cause AM to return the advice.

"AuthLevel" and "LEAuthLevel" condition failures can result in advice showing the expected or maximum possible authentication level. For example, failure against the following condition:

{
    "type": "AuthLevel",
    "authLevel": 2
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "2"
    ]
}

An "AuthenticateToRealm" condition failure can result in advice showing the name of the realm to which authentication is required. For example, failure against the following condition:

{
    "type": "AuthenticateToRealm",
    "authenticateToRealm": "MyRealm"
}

Leads to this advice:

{
    "AuthenticateToRealmConditionAdvice": [
        "/myRealm"
    ]
}

An "AuthenticateToService" condition failure can result in advice showing the name of the required authentication chain. For example, failure against the following condition:

{
    "type": "AuthenticateToService",
    "authenticateToService": "MyAuthnChain"
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A "ResourceEnvIP" condition failure can result in advice that indicates corrective action to be taken. The advice varies, depending on what the condition tests. For example, failure against the following condition:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.12] THEN authlevel=4"
    ]
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "4"
    ]
}

Failure against a different type of "ResourceEnvIP" condition such as the following:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.11] THEN service=MyAuthnChain"
    ]
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A "Session" condition failure can result in advice showing that access has been denied because the user’s session has been active longer than allowed by the condition. The advice will also show if the user’s session was terminated and reauthentication is required. For example, failure against the following condition:

{
    "type": "Session",
    "maxSessionTime": "10",
    "terminateSession": false
}

Leads to this advice:

{
    "SessionConditionAdvice": [
        "deny"
    ]
}

When policy evaluation denials occur against the following conditions, AM does not return any advice:

  • IPv4

  • IPv6

  • LDAPFilter

  • OAuth2Scope

  • SessionProperty

  • SimpleTime

When policy evaluation is requested for a nonexistent or inactive subject, AM returns an HTTP 200 code and a response that contains no actions or advice. Access to the resource is denied.

Request policy decisions for a tree of resources

This section shows how you can request policy decisions over REST for a resource and all other resources in the subtree beneath it.

When making a REST API call, specify the realm in the path component of the endpoint.

To request policy decisions for a tree of resources, perform an HTTP POST using the evaluation action to the appropriate path under the URI where AM is deployed, for example /json/realms/root/realms/myRealm/policies?_action=evaluateTree. The payload for the HTTP POST is a JSON object that specifies at least the root resource, and takes the following form.

{
    "resource": "resource string",
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The values for the fields shown above are explained below:

"resource"

This required field specifies the root resource for the decisions to return.

For example, when using the default policy set, "iPlanetAMWebAgentService", you can request decisions for resource URLs.

{
    "resource": "http://www.example.com/"
}
"application"

This field holds the name of the policy set, and defaults to "iPlanetAMWebAgentService" if not specified.

For more on policy sets, see Policy sets over REST.

"subject"

This optional field holds an object that represents the subject. You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.

"ssoToken"

The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.

"jwt"

The value is a JWT string.

"claims"

The value is an object (map) of JWT claims to their values. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.

"environment"

This optional field holds a map of keys to lists of values.

If you do not specify the environment, the default is an empty map.

The example below requests policy decisions for http://www.example.com/. The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation, and the subject takes the SSO token of the user who wants to access a resource.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…​NDU1*" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "resource": "http://www.example.com/",
    "subject": { "ssoToken": "AQIC5…​zE4*" }
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluateTree"
[
    {
        "resource":"http://www.example.com/",
        "actions":{
            "GET":true,
            "OPTIONS":true,
            "HEAD":true
        },
        "attributes":{

        },
        "advices":{

        }
    },
    {
        "resource":"http://www.example.com/",
        "actions":{
            "POST":false,
            "PATCH":false,
            "GET":true,
            "DELETE":true,
            "OPTIONS":true,
            "HEAD":true,
            "PUT":true
        },
        "attributes":{
            "myStaticAttr":[
                "myStaticValue"
            ]
        },
        "advices":{

        }
    },
    {
        "resource":"http://www.example.com/?*",
        "actions":{
            "POST":false,
            "PATCH":false,
            "GET":false,
            "DELETE":false,
            "OPTIONS":true,
            "HEAD":false,
            "PUT":false
        },
        "attributes":{

        },
        "advices":{
            "AuthLevelConditionAdvice":[
                "3"
            ]
        }
    }
]

Notice that AM returns decisions not only for the specified resource, but also for matching resource names in the tree whose root is the specified resource.

In the JSON list of decisions returned for each resource, AM includes these fields.

"resource"

A resource name whose root is the resource specified in the request.

The decisions returned are not guaranteed to be in the same order as the resources were requested.

"actions"

A map of action name keys to Boolean values that indicate whether the action is allowed (true) or denied (false) for the specified resource.

In the example, for matching resources with a query string only HTTP OPTIONS is allowed according to the policies configured.

"attributes"

A map of attribute names to their values, if any response attributes are returned according to applicable policies.

In the example, the policy that applies to http://www.example.com:80/* causes a static attribute to be returned.

"advices"

A map of advice names to their values, if any advice is returned according to applicable policies.

The "advices" field can provide hints regarding what AM needs to take the authorization decision.

In the example, the policy that applies to resources with a query string requests that the subject be authenticated at an authentication level of at least 3.

Notice that with the "advices" field present, no "advices" appear in the JSON response.

{
    "advices": {
        "AuthLevelConditionAdvice": [ "3" ]
    }
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name…​] to limit the fields returned in the output.

Transactional authorization

Transactional authorization improves security by requiring a user to perform additional actions when trying to access a resource protected by an AM policy. For example, they must re-authenticate, or respond to a push notification on their mobile device.

Performing the additional action successfully grants access to the protected resource, but only once. Additional attempts to access the resource will require the user to perform the configured actions again.

Transactional authorization is implemented as a environment condition type that can be added to authorization policies.

Example

The transactional authorization environment condition can be combined in policies with the other conditions. For example, only requiring a push notification response when access is attempted to the employees subrealm, but outside usual working hours, as shown below:

Combined with other environment conditions
Figure 9. Combining With Other Environment Conditions

Related information: Authorization and policy decisions

How does transactional authorization work?

The following diagram describes the sequence of events that occur when accessing a resource that is protected by a REST application, and an AM policy containing a transactional environment condition:

Access Resources with Transactional Authorization
Figure 10. Access Resources with Transactional Authorization

The sequence of events for a transaction authorization is as follows:

  1. An authenticated user attempts to access a resource that is protected by an AM server.

  2. The resource server contacts AM to evaluate the policies that apply.

    The resource server can be protected with ForgeRock’s Web or Java Agents, which support transactional authorization natively, or a custom application that uses ForgeRock’s REST API as per the diagram to manage the transactional authorization.

  3. As the policy contains a transaction environment condition, AM creates a transaction token in the Core Token Service (CTS) store. The initial transaction token state is set to CREATED.

    The transaction token contains information about the policy evaluation, including the:

    • Realm

    • Resource

    • Subject

    • Audit tracking ID

    • Authentication method

    To protect against tampering, AM verifies that these details do not change and match those in the incoming requests for the duration of the transaction.

    The transaction token has a time-to-live (default 180 seconds) defined in the Transaction Authentication Service. If the transaction is not completed in this time, the token is deleted, and the flow will need to be restarted. Alter the default if the transaction includes authentication actions that take more time to complete. For example, using HOTP authentication for a one-time password over email.

    The time-to-live can be configured per realm. See Transaction Authentication service.

  4. In the JSON response to the policy evaluation request, AM returns the transaction ID—the unique ID of the newly created transaction token—in the TransactionConditionAdvice array in the advices object:

    {
        "resource": "http://www.example.com:8000/index.html",
        "actions": {},
        "attributes": {},
        "advices": {
            "TransactionConditionAdvice": [
                "7b8bfd4c-60fe-4271-928d-d09b94496f84"
            ]
        },
        "ttl": 0
    }
  5. As the JSON response to the evaluation does not grant any actions but does contain advices, the REST application on the resource server extracts the transaction ID and returns it to the authentication service to commence the authentication.

    The transaction ID is included in the TransactionConditionAdvice attribute value pair in the composite advice query parameters sent as part of the request for actions.

    ForgeRock web and Java agents manage this interaction natively. For information on using the REST API to handle advices elements in policy evaluations, see Request policy decisions over REST.

  6. AM extracts the transaction ID from the composite advice, verifies the corresponding transaction token, and changes the state to IN_PROGRESS.

    If the transaction ID is not in the expected state or does not exist, a 401 Unauthorized error is returned. For example:

    {
        "code": 401,
        "reason": "Unauthorized",
        "message": "Unable to read transaction.",
        "detail": {
            "errorCode": "128"
        }
    }
  7. AM responds with the callbacks necessary to satisfy any environment conditions.

    The advices returned by transaction environment conditions have the lowest precedence when compared to the other condition advices. End users will have to complete the non-transactional condition advices before they can complete the transactional condition advices.

  8. The REST application renders the callbacks and presents them to the user.

  9. The user completes the required actions.

    For example, authenticates to the specified tree, or responds to the push notification on their registered mobile device.

    If the user is unable to complete the actions, AM returns an HTTP 200 message and the user is redirected to the protected resource. Policy evaluation will fail since the transactional authorization process has failed.

  10. The REST app completes the callbacks and returns the result to AM.

  11. AM verifies the transaction token, and changes the state to COMPLETED.

  12. With the transaction now complete, AM returns the original token.

    Note that the authentication performed as part of an authorization flow does not behave exactly the same as a standard authentication. The differences are:

    • The user’s original session is not upgraded or altered in any way.

    • Failing the authentication during the authorization flow does not increment account lockout counters.

  13. The web or Java agent or custom application on the resource server can reevaluate the policies applying to the protected resources again, but includes the ID of the completed transaction as a value in the TxId array in the environment object:

    {
        "resources" : ["http://www.example.com:8000/index.html"],
        "application" : "iPlanetAMWebAgentService",
        "subject" : {
            "ssoToken" : "AQIC5w....*AJTMQAA*"
        },
        "environment": {
            "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"]
        }
    }
  14. AM verifies the transaction was authorized and that the transaction token is in the COMPLETED state.

  15. If the transaction was completed successfully, authorization continues.

    The transaction token is marked for deletion, so that it cannot be used to grant more than a single access.

  16. As the authentication required to complete the transaction was successful, AM returns the result of the policy reevaluation.

    For example, the following response grants the POST and GET actions to the resource http://www.example.com:8000/index.html:

    {
        "resource": "http://www.example.com:8000/index.html",
        "actions": {
            "POST": true,
            "GET": true
        },
        "attributes": {},
        "advices": {},
        "ttl": 0
    }

    Successful transactional authorization responses set the time-to-live (ttl) value to zero to ensure that the policy decision is not cached and cannot be used more than once.

    ForgeRock agents prior to version 5 do not support a time-to-live value of zero and cannot be used for transactional authorization.

  17. The user is able to access the protected resource once.

    Additional attempts to access a resource protected with a policy containing a transactional environment condition require a new transaction to be completed.

To configure transactional authorization, first configure the trees you need for session upgrade, then configure your policies.

Dynamic OAuth 2.0 authorization

You can configure AM to grant scopes statically or dynamically:

  • Statically (Default). You configure several OAuth 2.0 clients with different subsets of scopes and resource owners are redirected to a specific client depending on the scopes required. As long as the resource owner can authenticate and the client can deliver the same or a subset of the requested scopes, AM issues the token with the scopes requested. Therefore, two different users requesting scopes A and B to the same client will always receive scopes A and B.

  • Dynamically. You configure an OAuth 2.0 client with a comprehensive list of scopes and resource owners authenticate against it. When AM receives a request for scopes, AM’s Authorization Service grants or denies access scopes dynamically by evaluating authorization policies at runtime. Therefore, two different users requesting scopes A and B to the same client can receive different scopes based on policy conditions.

Example use case

Consider the case of a company deployment that supports custom OAuth 2.0 clients and internal applications. The use of the internal application is bound by the terms and conditions specified by the company; therefore, the user does not need to consent to provide with their user profile information (for example, the profile scope).

To provide the internal application with the user profile automatically, the administrator creates a policy that grants the profile scope to all requests made by authenticated users using a particular OAuth 2.0 client.

How does dynamic OAuth 2.0 authorization work?
Shows the relationship between realms, policies, and policy sets when granting or denying OAuth 2.0 scopes.
Figure 11. Granting or Denying OAuth2 2.0 Scopes Dynamically

When issuing access tokens, AM deduces consent status based on a policy result: an allow policy result means consent is granted, while a deny result means it is denied.

If AM cannot deduce consent using a policy, for example, because none is defined, it is down to the resource owner to decide whether to grant consent. Note that this is only possible in flows where the resource owner interacts with the consent screen. If the resource owner cannot interact with the consent screen, for example, during the ROPC Grant flow, AM denies the scope.

Just like when granting scopes statically, AM only evaluates default scopes configured in the OAuth 2.0 client profile when no scope is requested. AM follows the same rules to deduce consent for both default and requested scopes.

When issuing refresh tokens, AM issues any scope that was previously consented to either by policy or by the resource owner on the consent screen, unless it is explicitly denied by a policy.

To understand which flows are interactive and which ones are not, see the examples in OAuth 2.0 grant flows and OpenID Connect grant flows.

OAuth 2.0 authorization is implemented by using the OAuth2 Scope resource type, which must always be configured in the Default OAuth2 Scopes policy set.

Related information: Policies.

Writing policies for OAuth 2.0 may not be straightforward if your environment requires complex conditions. The easiest way to test if your OAuth 2.0 policies are granting or denying the scopes you expect before setting them in production is to configure AM as an OAuth 2.0 client and authorization provider and request some tokens.

Configure Access Management for the examples

  1. Configure an instance of the OAuth 2.0 provider.

    Ensure that:

    • Use Policy Engine for Scope Decisions is enabled.

    • Response Type Plugins is configured for token and id_token.

    • Grant Types is configured for Resource Owner Password Credentials and Implicit.

  2. Go to Realms > Realm Name > Applications > OAuth 2.0 and add a client.

    Configure the client properties as follows:

    • Client ID: myClient

    • Client secret: forgerock

    • Redirection URIs: https://www.example.com:443/callback

    • Scope(s): profile email openid

    • Grant Types: Resource Owner Password Credentials

  3. Go to Realms > Realm Name > Authorization > Policy Sets, and select Default OAuth2 Scopes Policy Set.

  4. Create a new policy as follows:

    • Name: myOAuth2Policy

    • Resource Type: OAuth2 Scope

    • Resources: Select the * resource pattern and replace it with email.

      Once the policy is created, you will see the Summary tab.

  5. On the Actions tab, add the GRANT action, and set the default state to Allow. Save your changes.

  6. On the Subjects tab, specify the subject condition All of…​ Authenticated Users. Save your changes.

  7. If the demo user is not present in your environment, create it by performing the following step:

    • Go to Realms > Realm Name > Identities, and add a new user called demo with password Ch4ng31t.

Test OAuth 2.0 policies in a non-interactive flow

This procedure shows how to test OAuth 2.0 policies with the ROPC Grant flow. In this flow, the resource owner does not interact with the consent screen and cannot therefore grant scopes.

  1. Request an access token from AM by specifying:

    • The client name, myClient, and its password, forgerock.

    • The resource owner password credentials grant type, password.

    • The user and password to authenticate with, demo and Ch4ng31t.

    • The requested scopes, email and profile.

    $ curl --request POST \
    --data "grant_type=password" \
    --data "username=demo" \
    --data "password=Ch4ng31t" \
    --data "scope=profile email" \
    --data "client_id=myClient" \
    --data "client_secret=forgerock" \
    "https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token"
  2. Review the JSON response.

    It should be similar to the following:

    {
      "access_token":"B78LPVHaycIrObh12Qps0n9ynYM",
      "scope":"email",
      "token_type":"Bearer",
      "expires_in":3599
    }

    Note how the requested scopes were email and profile, but the scope granted was email, which matches the GRANT=Allow action defined in the policy.

Test OAuth 2.0 policies in an interactive OpenID Connect flow

This procedure shows how to test OAuth 2.0 policies with the OpenID Connect Implicit Grant flow. In this flow, the end user can interact with the consent screen, and can therefore grant scopes.

  1. In a web browser, make a call to the oauth2/authorize endpoint with the following parameters:

    • nonce=123

    • state=456

    • scope=openid+email+profile

    • response_type=id_token

    • client_id=myClient

    • redirect_uri=https://www.example.com:443/callback

    For example: https://<tenant-name>.forgeblocks.com/am/oauth2/authorize?nonce=123&state=456&scope=openid+email+profile&response_type=id_token&client_id=myClient&redirect_uri=https://www.example.com:443/callback. You will be prompted to log in to AM.

  2. Log in as the demo user.

    You will be prompted to provide consent for the profile scope:

    AM requests the user to consent to sharing the profile scope
    Figure 12. Requesting Consent for the Profile Scope

    Notice that you are not prompted to provide consent for the email scope.

  3. Allow the flow to continue.

  4. Review the URL of the browser.

    It should show something similar to: http://example.com/#scope=openid%20profile%20email&id_token=eyJ0eXJKV1Q…​8WK1eg&state=456.

    Notice that the email scope has been granted automatically.

    If the authorization policy had been configured as GRANT=Deny, you still would have not seen the email scope in the consent page, but the scope would not appear in the URL of the browser.

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 > realm name > Scripts, and select Scripted Policy Condition.

Test scripted policy conditions with the sample script

The sample policy condition script requires the subject of the policy to have 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 script also requires the user to have access to evaluate policies.

Add an address to a user profile

Add an address value to a user’s profile. The sample policy condition script uses the address when performing policy evaluation. This example assumes that the user you are updating exists and has the ID demo.

  1. In the AM admin UI, go to Realms > realm name > Identities.

  2. On the Identities tab, select (demo).

  3. In the Home Address field, enter a valid address.

    For example:

    201 Mission St, Suite 2900, San Francisco, CA 94105
  4. Click Save Changes.

Add a user who can evaluate policies

Add a user to a group and assign the privilege required to perform policy evaluations.

  1. In the AM admin UI, go to Realms > realm name > Identities.

  2. Click Add Identity, enter an ID for the identity, such as restPolicyUser, complete the required fields, and click Create.

  3. Return to Realms > realm name > Identities.

    On the Groups tab, click Add Group, enter an ID for the group, such as policyEval, and click Create.

  4. Return to Realms > realm name > Identities.

    • Select the user you created in step 2, for example, restPolicyUser.

    • On the Groups tab, in the Name field, select the group you created in step 3, for example policyEval.

    • Click Save Changes.

  5. Go to Realms > realm name > Identities > Groups.

  6. Select the group you created in step 3, for example policyEval.

  7. On the Privileges tab, select Policy Admin, then click Save Changes.

Create a policy that uses the sample policy condition script

Create a policy that uses the sample policy condition script. Policy evaluations can then be performed to test the script functionality.

  1. In the AM admin UI, go to Realms > realm name > Authorization > Policy Sets.

  2. On the Policy Sets page, select Default OAuth2 Scopes Policy Set.

  3. Click Add a Policy.

  4. Define the policy as follows:

    • Enter a name for the policy.

    • Define resources to which the policy applies:

      • Select URL from the Resource Type list.

      • Select the resource pattern *://*:*/* from the Resources list, then 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 list, then click Add.

        The *://*:*/*?* resource appears along with the *://*:*/* resource in the Resources field.

      • Click Create to create the policy.

        The Resources tab appears as follows:

        Configure resources to try out the default policy condition script.
    • Specify actions to which the policy applies:

      • On 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.

        The Actions tab appears as follows:

        Configure actions to try out the default policy condition script.
      • Click Save Changes.

    • Configure identities to which the policy applies:

      • On the Subjects tab, select the edit icon ().

      • Select Authenticated Users from the Type list.

      • Select the OK icon—the check mark.

        The Subjects tab appears as follows:

        Configure subjects to try out the default policy condition script.
      • Click Save Changes.

    • Configure environments in which the policy applies:

      • On 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.

        The Environments tab appears as follows:

        Configure environments to try out the default policy condition script.
      • Click Save Changes.

    • No additional configuration is required in the Response Attributes or Details tabs.

Test the sample policy condition script

To evaluate against a policy, you must first obtain an SSO token for the subject performing the evaluation, in this case demo. 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

  1. 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://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM…​TU3OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }
  2. 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://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC8aF…​TA1OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }
  3. Send an evaluation request to the policies endpoint, providing the SSO token of the restPolicyUser user as the value of the <session-cookie-name> 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 "<session-cookie-name>: 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://<tenant-name>.forgeblocks.com/am/json/realms/root/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 "<session-cookie-name>: 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://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate"
    {
        "advices": {},
        "ttl": 9223372036854775807,
        "resource": "https://www.france-site.com:8443/index.html",
        "actions": {},
        "attributes": {}
    }
Copyright © 2010-2022 ForgeRock, all rights reserved.