AM 7.2.2

Policies over REST

Policies are realm-specific, so the URI for the policies API can contain a realm component, such as /json/realms/root/realms/Realm Name/policies. If the realm is not specified in the URI, the top level realm is used.

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:

    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.

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

    Note that AM terminates client-side sessions only if session denylisting is in effect. For more information about session denylisting, see 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 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 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 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, send an HTTP GET request to the /json/realms/root/realms/Realm Name/policies endpoint, with a _queryFilter parameter set to true.

    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/alpha/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.

See Read an identity.

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 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. Send an HTTP GET request to the /json/realms/root/realms/Realm Name/policies endpoint, with a _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/alpha/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
}
    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.

Read a specific policy

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

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/realms/alpha/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, send an HTTP POST request to the /json/realms/root/realms/Realm Name/policies endpoint, with an _action parameter set to create. Include a JSON representation of the policy in the POST data.

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.

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:

  • Go 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 "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/realms/alpha/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, send an HTTP PUT request to the /json/realms/root/realms/Realm Name/policies endpoint, and specify the policy name in the URL. Include a JSON representation of the updated policy in the PUT data.

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 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 "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/realms/alpha/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, send an HTTP DELETE request to the /json/realms/root/realms/Realm Name/policies endpoint, and specify the policy name in the URL.

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/realms/alpha/policies/myupdatedpolicy"

Copy and move policies

To copy or move an individual policy, send an HTTP POST request to the /json/realms/root/realms/Realm Name/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.

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 alpha 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/realms/alpha/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/alpha/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"
}

To copy and move multiple policies—all the policies in a policy set—in a single operation, send an HTTP POST request to the /json/realms/root/realms/Realm Name/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 "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/alpha/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, send an HTTP GET request 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.

Read a specific environment condition type

To read an individual environment condition type, send an HTTP GET request 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"
                }
            }
        }
    }
}

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, send an HTTP GET request 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.

Read a specific subject condition types

To read an individual subject condition type, send an HTTP GET request 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"
                }
            }
        }
    }

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. For more information, see Identity stores.

Query subject attributes

To list all subject attributes, send an HTTP GET request 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.

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, send an HTTP GET request 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/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, send an HTTP GET on its resource.

To read an individual decision combiner, send an HTTP GET request 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/realms/alpha/decisioncombiners/DenyOverride
{
  "title" : "DenyOverride"
}
Copyright © 2010-2024 ForgeRock, all rights reserved.