Policy sets over REST

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

PingOne Advanced Identity Cloud 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. Use `"iPlanetAMWebAgentService"`.
`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.
`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 PingOne Advanced Identity Cloud evaluates multiple policies for a resource. Use `"DenyOverride"`.
`realm`	A string identifying the realm for this 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.
`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.
`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.

Use "iPlanetAMWebAgentService".

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.

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 PingOne Advanced Identity Cloud evaluates multiple policies for a resource.

Use "DenyOverride".

realm

A string identifying the realm for this 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.

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.

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 Advanced Identity Cloud admin UI, select Identities > Manage > Realm Name Realm - Users > + New Realm Name Realm - User and fill the required fields.

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

Under Native Consoles > Access Management, select Realms > Realm Name > Identities > Groups > + Add Group. 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:

$ 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://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<policy-set-admin-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

For additional details, refer to Session tokens after authentication.

Use the <policy-set-admin-tokenId> as the value of the <session-cookie-name> header 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.

$ curl \
--header "<session-cookie-name>: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/applications?_queryFilter=true'
{
  "result": [{
    "_id": "oauth2Scopes",
    "name": "oauth2Scopes",
    "description": "The built-in Application used by the OAuth2 scope authorization process.",
    "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.

$ curl \
--header "<session-cookie-name>: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/applications/oauth2Scopes'
{
  "_id": "oauth2Scopes",
  "_rev": "1595479030629",
  "name": "oauth2Scopes",
  "description": "The built-in Application used by the OAuth2 scope authorization process.",
  "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.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <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://<tenant-env-fqdn>/am/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.

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <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://<tenant-env-fqdn>/am/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.

$ curl \
--request DELETE \
--header "<session-cookie-name>: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/applications/samplePolicySet'
{"_id":"samplePolicySet","_rev":"0"}

You cannot delete a policy set that contains policies. If you attempt to delete the policy set, PingOne Advanced Identity Cloud returns an HTTP 409 Conflict status code and a message like the one in the following example:

$ curl \
--request DELETE \
--header "<session-cookie-name>: <policy-set-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/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.