Policy Sets (REST)

AM provides the applications REST endpoint for the following:

Policy sets are realm-specific, hence, the URI for the policy set API can contain a realm component, such as /json{/realm}/applications. If the realm is not specified in the URI, the top level realm is used.

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

{
    "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 Policy Agents.",
    "realm": "/",
    "name": "iPlanetAMWebAgentService"
}

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

"conditions"

Condition types allowed in the context of this policy set.

For information on condition types, see "Policies (REST)" and "Managing Environment Condition Types".

"applicationType"

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

"subjects"

Subject types allowed in the context of this policy set.

For information on subject types, see "Policies (REST)" and "Managing Subject Condition Types".

"entitlementCombiner"

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

For more on decision combiners, see "Managing Decision Combiners".

"saveIndex"

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

"searchIndex"

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

"resourceComparator"

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

The following implementations are available:

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

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

"attributeNames"

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

"description"

String describing the policy set.

"realm"

Name of the realm where 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 "Using the Session Token After Authentication".

Querying Policy Sets

To list all the policy sets in a realm, perform an HTTP GET to the /json{/realm}/applications endpoint, with a _queryFilter parameter set to true.

Note

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

FieldSupported Operators

name

Equals (eq)

description

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.

Reading a Specific Policy Set

To read an individual policy set in a realm, perform an HTTP GET to the /json{/realm}/applications endpoint, and specify the policy set 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..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/applications/mypolicyset
{
    "creationDate":1431360678810,
    "lastModifiedDate":1431360678810,
    "conditions":[
        "AuthenticateToService",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "SessionProperty",
        "AuthLevel",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType":"iPlanetAMWebAgentService",
    "subjects":[
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner":"DenyOverride",
    "saveIndex":null,
    "searchIndex":null,
    "resourceComparator":"com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids":[
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "attributeNames":[

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

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

Creating Policy Sets

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

Note

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 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=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/applications/?_action=create

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 Policy Sets

To update an individual policy set in a realm, perform an HTTP PUT to the /json{/realm}/applications endpoint, and specify the policy set name in the URL. Include a JSON representation of the updated policy set 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: 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/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.

Deleting Policy Sets

To delete an individual policy set in a realm, perform an HTTP DELETE to the /json{/realm}/applications endpoint, and specify the policy set 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 \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=2.1" \
https://openam.example.com:8443/openam/json/realms/root/applications/myupdatedpolicyset
Read a different version of :