Policy sets over REST

You can manage policy sets over REST at the applications endpoint. ("Application" is the internal AM name for a policy set.)

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 you omit the realm path from the URL, AM uses the Top Level Realm.

AM stores policy sets as JSON objects. A policy set can include the following fields. The fields have JSON values—strings, numbers, objects, sets, arrays, true, false, and null.

Policy set field Description

Policy set field	Description
`_id`, `name`	A unique string identifying the policy set. Do not use any of the following characters in policy, policy set, or resource type names: Double quotes (`"`) Plus sign (`+`) Comma (`,`) Less than (`<`) Equals (`=`) Greater than (`>`) Backslash (`\`) Forward slash (`/`) Semicolon (`;`) Null (`\u0000`)
`_rev`⁽¹⁾	A system-generated revision string.
`actions`	An object where each field is an action name. The value for each action name field is a boolean indicating whether to allow the action by default.
`applicationType`	A string containing the application type name. For more information, refer to Policy set application types over REST.
`attributeNames`	An optional array of response attribute name strings restricting what policies in this set can return.
`conditions`	An array of environment condition identifier strings defining environment conditions allowed for policies in this set. For information, refer to Policies over REST and Manage environment condition types.
`description`	An optional text string to help identify the policy set.
`editable`	A boolean indicating whether you can edit this policy set definition after creation.
`entitlementCombiner`	An optional string identifying how AM evaluates multiple policies for a resource. For more information, refer to Manage decision combiners.
`realm`	A string identifying the realm for this policy set. 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.
`resources`	An array of resource pattern strings for resources governed by policies in this set.
`resourceComparator`	An optional string identifying the fully qualified class name of the implementation to match resources for policies. The following implementations are available: `"com.sun.identity.entitlement.ExactMatchResourceName"` `"com.sun.identity.entitlement.PrefixResourceName"` `"com.sun.identity.entitlement.RegExResourceName"` `"com.sun.identity.entitlement.URLResourceName"`
`saveIndex`	An optional string identifying the fully qualified class name of the implementation to save indexes for policies.
`searchIndex`	An optional string identifying the fully qualified class name of the implementation to index policies.
`subjects`	Array of subject type identifier strings defining subject types allowed for policies in this set. For more information, refer to Policies over REST and Subject conditions.
`createdBy`⁽¹⁾	A string indicating who created the policy set.
`creationDate`⁽¹⁾	An integer containing the creation time in milliseconds since January 1, 1970.
`lastModifiedBy`⁽¹⁾	A string indicating who last changed the policy set.
`lastModifiedDate`⁽¹⁾	An integer containing the last modified time in milliseconds since January 1, 1970.

_id, name

A unique string identifying the policy set.

Do not use any of the following characters in policy, policy set, or resource type names:

Double quotes (")
Plus sign (+)
Comma (,)
Less than (<)
Equals (=)
Greater than (>)
Backslash (\)
Forward slash (/)
Semicolon (;)
Null (\u0000)

_rev⁽¹⁾

A system-generated revision string.

actions

An object where each field is an action name.

The value for each action name field is a boolean indicating whether to allow the action by default.

applicationType

A string containing the application type name.

For more information, refer to Policy set application types over REST.

attributeNames

An optional array of response attribute name strings restricting what policies in this set can return.

conditions

An array of environment condition identifier strings defining environment conditions allowed for policies in this set.

For information, refer to Policies over REST and Manage environment condition types.

description

An optional text string to help identify the policy set.

editable

A boolean indicating whether you can edit this policy set definition after creation.

entitlementCombiner

An optional string identifying how AM evaluates multiple policies for a resource.

For more information, refer to Manage decision combiners.

realm

A string identifying the realm for this policy set.

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.

resources

An array of resource pattern strings for resources governed by policies in this set.

resourceComparator

An optional string identifying the fully qualified class name of the implementation to match resources for policies.

The following implementations are available:

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

saveIndex

An optional string identifying the fully qualified class name of the implementation to save indexes for policies.

searchIndex

An optional string identifying the fully qualified class name of the implementation to index policies.

subjects

Array of subject type identifier strings defining subject types allowed for policies in this set.

For more information, refer to Policies over REST and Subject conditions.

createdBy⁽¹⁾

A string indicating who created the policy set.

creationDate⁽¹⁾

An integer containing the creation time in milliseconds since January 1, 1970.

lastModifiedBy⁽¹⁾

A string indicating who last changed the policy set.

lastModifiedDate⁽¹⁾

An integer containing the last modified time in milliseconds since January 1, 1970.

⁽¹⁾ Do not change the value of this field.

Access the endpoint

The REST calls to manage policy sets rely on an account with the appropriate privileges:

Create a policy set administrator.

In the AM admin UI, select Realm > Realm Name > Identities > + Add Identity and fill the required fields.

Record the username and password.
Create a group that grants the privileges to the policy set administrator.

In the AM admin UI, select Realms > Realm Name > Identities > Groups > + Add Group to create a group with the following settings:

Group ID

am-policy-set-admins

Members

The policy set administrator whose username you recorded

Privileges

Policy Admin
Application Modify Access
Application Read Access

Before making REST calls to manage policy sets, authenticate as the policy set administrator.

For example:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <policy-set-admin-username>' \
--header 'X-OpenAM-Password: <policy-set-admin-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<policy-set-admin-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

For additional details, refer to Session token after authentication.

Use the <policy-set-admin-tokenId> as the value of the AM session cookie (default name: iPlanetDirectoryPro) to access the REST endpoints.

Query policy sets

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

If you omit the realm path from the URL, AM uses the Top Level Realm.

$ curl \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications?_queryFilter=true'
{
  "result": [{
    "_id": "oauth2Scopes",
    "name": "oauth2Scopes",
    "description": "A policy set for policies based on OAuth 2.0 scopes",
    "attributeNames": [],
    "createdBy": "id=dsameuser,ou=user,ou=am-config",
    "conditions": ["Script", "AMIdentityMembership", "IPv6", "SimpleTime", "IPv4", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "SessionProperty", "OAuth2Scope", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
    "lastModifiedBy": "id=dsameuser,ou=user,ou=am-config",
    "creationDate": 1578580064992,
    "lastModifiedDate": 1595479030629,
    "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "JwtClaim"],
    "saveIndex": null,
    "searchIndex": null,
    "entitlementCombiner": "DenyOverride",
    "resourceComparator": null,
    "editable": true,
    "applicationType": "iPlanetAMWebAgentService",
    "actions": {
      "GRANT": true
    },
    "resources": ["*://*:*/*", "*://*:*/*?*", "*"],
    "realm": "/alpha"
  }],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": 0
}

Adapt the query string parameters to refine the results.

Field Supported _queryFilter operators

Field	Supported `_queryFilter` operators
`name`	Equals (`eq`)
`description`
`createdBy`
`lastModifiedBy`
`creationDate`	Equals (`eq`)⁽¹⁾ Greater than or equal to (`ge`) Greater than (`gt`) Less than or equal to (`le`) Less than (`lt`)
`lastModifiedDate`

name

Equals (eq)

description

createdBy

lastModifiedBy

creationDate

Equals (eq)⁽¹⁾
Greater than or equal to (ge)
Greater than (gt)
Less than or equal to (le)
Less than (lt)

lastModifiedDate

⁽¹⁾ Do not use regular expression patterns with eq.

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/policy-set-name endpoint.

If you omit the realm path from the URL, AM uses the Top Level Realm.

$ curl \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/oauth2Scopes'
{
  "_id": "oauth2Scopes",
  "_rev": "1595479030629",
  "name": "oauth2Scopes",
  "description": "A policy set for policies based on OAuth 2.0 scopes",
  "attributeNames": [],
  "createdBy": "id=dsameuser,ou=user,ou=am-config",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "SimpleTime", "IPv4", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "SessionProperty", "OAuth2Scope", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "lastModifiedBy": "id=dsameuser,ou=user,ou=am-config",
  "creationDate": 1578580064992,
  "lastModifiedDate": 1595479030629,
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "JwtClaim"],
  "saveIndex": null,
  "searchIndex": null,
  "entitlementCombiner": "DenyOverride",
  "resourceComparator": null,
  "editable": true,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "GRANT": true
  },
  "resources": ["*://*:*/*", "*://*:*/*?*", "*"],
  "realm": "/alpha"
}

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 as the query string parameter and a JSON representation of the policy set as the POST data.

If you omit the realm path from the URL, AM uses the Top Level Realm.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "samplePolicySet",
  "description": "Sample policy set",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "IPv4", "SimpleTime", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "Policy", "OAuth2Scope", "SessionProperty", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "Policy", "JwtClaim"],
  "entitlementCombiner": "DenyOverride",
  "attributeNames": [],
  "saveIndex": null,
  "searchIndex": null,
  "resourceComparator": null,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "HEAD": true,
    "DELETE": true,
    "POST": true,
    "GET": true,
    "OPTIONS": true,
    "PUT": true,
    "PATCH": true
  },
  "resources": ["*://*:*/*", "*://*:*/*?*"],
  "realm": "/alpha"
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/?_action=create'
{
  "_id": "samplePolicySet",
  "_rev": "1669134131264",
  "name": "samplePolicySet",
  "description": "Sample policy set",
  "attributeNames": [],
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "IPv4", "SimpleTime", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "Policy", "OAuth2Scope", "SessionProperty", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669134131264,
  "lastModifiedDate": 1669134131264,
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "Policy", "JwtClaim"],
  "saveIndex": null,
  "searchIndex": null,
  "entitlementCombiner": "DenyOverride",
  "resourceComparator": null,
  "editable": true,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "HEAD": true,
    "DELETE": true,
    "POST": true,
    "GET": true,
    "OPTIONS": true,
    "PUT": true,
    "PATCH": true
  },
  "resources": ["*://*:*/*", "*://*:*/*?*"],
  "realm": "/alpha"
}

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/policy-set-name endpoint with a JSON representation of the updated policy set as the PUT data.

If you omit the realm path from the URL, AM uses the Top Level Realm.

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "samplePolicySet",
  "description": "Sample policy set",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "IPv4", "SimpleTime", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "Policy", "OAuth2Scope", "SessionProperty", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "Policy", "JwtClaim"],
  "entitlementCombiner": "DenyOverride",
  "attributeNames": [],
  "saveIndex": null,
  "searchIndex": null,
  "resourceComparator": null,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "HEAD": true,
    "DELETE": false,
    "POST": true,
    "GET": true,
    "OPTIONS": true,
    "PUT": false,
    "PATCH": false
  },
  "resources": ["*://*:*/*", "*://*:*/*?*"],
  "realm": "/alpha"
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/samplePolicySet'
{
  "_id": "samplePolicySet",
  "_rev": "1669134221194",
  "name": "samplePolicySet",
  "description": "Sample policy set",
  "attributeNames": [],
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "IPv4", "SimpleTime", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "Policy", "OAuth2Scope", "SessionProperty", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669134131264,
  "lastModifiedDate": 1669134221194,
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "Policy", "JwtClaim"],
  "saveIndex": null,
  "searchIndex": null,
  "entitlementCombiner": "DenyOverride",
  "resourceComparator": null,
  "editable": true,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "HEAD": true,
    "DELETE": false,
    "POST": true,
    "GET": true,
    "OPTIONS": true,
    "PATCH": false,
    "PUT": false
  },
  "resources": ["*://*:*/*", "*://*:*/*?*"],
  "realm": "/alpha"
}

Delete a policy set

To delete a policy set in a realm, send an HTTP DELETE request to the /json/realms/root/realms/Realm Name/applications/policy-set-name endpoint.

If you omit the realm path from the URL, AM uses the Top Level Realm.

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/samplePolicySet'
{"_id":"samplePolicySet","_rev":"0"}

AM does not permit deletion of a policy set containing policies. If you attempt to delete the policy set, AM returns an HTTP 409 Conflict status code and a message like the one in the following example:

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/applications/oauth2Scopes'
{
  "code": 409,
  "reason": "Conflict",
  "message": "Application cannot be altered because policies exist within the Application. Remove all policies from the Application before attempting to delete the Application."
}

Remove the policies from the set before you delete it.

PingAM 7.5.0

Policy sets over REST

Access the endpoint

Query policy sets

Read a policy set

Create a policy set

Update a policy set

Delete a policy set