Policies (REST)

AM provides REST APIs for the following:

Policies are realm specific, hence the URI for the policies API can contain a realm component, such as /json{/realm}/policies. If the realm is not specified in the URI, the top level realm is used.

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

{
    "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 used when creating the policy by HTTP PUT or in the body when creating the policy by 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.

Tip

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 also 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"
    }       

    Warning

    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, also 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 "Managing 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 also 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"
        ]
    }

    Note

    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 and the policy set name, and to set 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 chain that was used to authenticate.

    {
        "type": "AuthenticateToService",
        "authenticateToService": "MyAuthnChain"
    }
  • "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 either IP to match the user's IP address, or 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:

    module

    The module that was used to authenticate the user, for example DataStore.

    service

    The authentication chain 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 from which the user was redirected.

    realm

    The realm to which the user authenticated.

  • "Session" to specify how long the user's session has been active, and to terminate the session if deemed too old, such that the user must authenticate again. Note that AM terminates client-based sessions only if session blacklisting is in effect. For more information about session blacklisting, see "Understanding Session Termination".

    {
        "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 "Managing 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 with "type" set to the name of the implementation (by default either "Static" for statically defined attributes or "User" for attributes from the user profile), "propertyName" 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 specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

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

Querying 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, by using the procedures below:

To List All Policies in a Realm
  • To list all the policies in a realm, perform an HTTP GET to the /json{/realm}/policies endpoint, with an _queryFilter parameter set to true.

    Note

    If the realm is not specified in the URL, AM returns policies in the top level realm.

    The iPlanetDirectoryPro 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: AQIC5w..." \
    --header "Accept-API-Version: resource=1.0, protocol=2.1" \
    "https://openam.example.com:8443/openam/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".

    FieldSupported Operators

    name

    Equals (eq)

    description

    Equals (eq)

    applicationName

    Equals (eq)

    createdBy

    Equals (eq)

    creationDate

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

    Note

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

    lastModifiedBy

    Equals (eq)

    lastModifiedDate

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

    Note

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

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

Tip

You can obtain the universal ID for a user or group by using REST. See "Reading Identities".

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 labeled as Users & Groups in the policy editor in the AM console.

  • 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:

  • Perform an HTTP GET to the /json{/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 "iPlanetDirectoryPro: 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://openam.example.com:8443/openam/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
    }

    Note

    If the realm is not specified in the URL, AM searches the top level realm.

    The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Reading a Specific Policy

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

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro 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..." \
"https://openam.example.com:8443/openam/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.

Creating Policies

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

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Important

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the AM console or REST endpoints. Using the special characters listed below causes AM to return a 400 Bad Request error. The special characters are: 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 "iPlanetDirectoryPro: 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://openam.example.com:8443/openam/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.

Updating Policies

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

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro 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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the AM console or REST endpoints. Using the special characters listed below causes AM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: 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://openam.example.com:8443/openam/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.

Deleting Policies

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

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro 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: AQIC5w..." \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://openam.example.com:8443/openam/json/realms/root/policies/myupdatedpolicy"

Copying and Moving Policies

You can copy or move an individual policy by performing an HTTP POST to the /json{/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. If the realm is not specified in the URL, AM copies or moves a policy from the top level realm.

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

ObjectPropertyDescription
toname

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.

toapplication

The policy set in which to place the output policy.

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

torealm

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.

toresourceType

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 "iPlanetDirectoryPro: AQIC5w..." \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://openam.example.com:8443/openam/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 "iPlanetDirectoryPro: AQIC5w..." \
--header "Accept-API-Version: resource=2.1" \
--data '{
    "to": {
        "name": "myMovedPolicy",
        "realm": "/myOtherRealm",
        "resourceType: "616b3d02-7a8d-4422-b6a7-174f62afd065"
    }
}' \
"https://openam.example.com:8443/openam/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{/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.

ObjectPropertyDescription
fromapplication

The policy set in which the input policies are located.

Required.

toapplication

The policy set in which to store output policies.

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

torealm

The realm in which to store output policies.

Required when copying or moving policies to a different realm.

tonamePostfix

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

Required.

resourceTypeMappingVaries; see Description

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

Managing 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": [
        {
            ...
        },
        {
            ...
        },
        ...
    ]
}

Querying 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 iPlanetDirectoryPro 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, protocol=2.1" \
https://openam.example.com:8443/openam/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".

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

Managing 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": [
      {...},
      {...},
      {...},
      {...}
    ]
}

Querying 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 iPlanetDirectoryPro 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://openam.example.com:8443/openam/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".

Reading 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 iPlanetDirectoryPro 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://openam.example.com:8443/openam/json/realms/root/subjecttypes/Identity
{
    "title" : "Identity",
    "logical" : false,
    "config" : {
        "type" : "object",
        "properties" : {
            "subjectValues" : {
                "type" : "array",
                "items" : {
                    "type" : "string"
                }
            }
        }
    }

Managing 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 the following:

Subject attributes derive from the list of LDAP user attributes configured for the identity store. For more information, see Identity Stores.

Querying Subject Attributes

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

The iPlanetDirectoryPro 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://openam.example.com:8443/openam/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.

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

Querying Decision Combiners

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

The iPlanetDirectoryPro 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, protocol=2.1" \
https://openam.example.com:8443/openam/json/realms/root/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".

Reading 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 iPlanetDirectoryPro 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://openam.example.com:8443/openam/json/realms/root/decisioncombiners/DenyOverride
{
  "title" : "DenyOverride"
}
Read a different version of :