AM 7.2.2

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 Name/applications. If the realm is not specified in the URI, the top level realm is used.

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 Manage 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 Manage subject condition types.

entitlementCombiner

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

For more on decision combiners, see Manage 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 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 policy sets

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

If the realm is not specified in the URL, AM returns policy sets 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: AQIC5…​" \
--header "Accept-API-Version: resource=1.0" \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/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 Name/applications endpoint, specifying the policy set 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…​" \
--header "Accept-API-Version: resource=1.0" \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/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 Name/applications endpoint, with _action=create. Include a JSON representation of the policy set in the POST data.

If the realm is not specified in the URL, AM creates the policy set 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.

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=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://openam.example.com:8443/openam/json/realms/root/realms/alpha/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 Name/applications endpoint, specifying the policy set name in the URL. Include a JSON representation of the updated policy set 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: 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://openam.example.com:8443/openam/json/realms/root/realms/alpha/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 Name/applications endpoint, specifying the policy set 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 \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Accept-API-Version: resource=2.1" \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/myupdatedpolicyset"
Copyright © 2010-2024 ForgeRock, all rights reserved.