--- title: Policy sets over REST description: "You can manage policy sets over REST at the applications endpoint. (\"Application\" is the internal name for a policy set.)" component: pingoneaic page_id: pingoneaic:am-authorization:rest-api-authz-applications canonical_url: https://docs.pingidentity.com/pingoneaic/am-authorization/rest-api-authz-applications.html keywords: ["Authorization", "Policy", "Resource", "Configuration", "REST API"] page_aliases: ["authorization-guide:rest-api-authz-applications.adoc"] section_ids: access_the_endpoint: Access the endpoint rest-api-authz-applications-query: Query policy sets rest-api-authz-applications-read: Read a policy set rest-api-authz-applications-create: Create a policy set rest-api-authz-applications-update: Update a policy set rest-api-authz-applications-delete: Delete a policy set --- # Policy sets over REST You can manage policy sets over REST at the `applications` endpoint. ("Application" is the internal name for a policy set.) 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 | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_id`, `name` | A unique string identifying the policy set.Don't 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`(1) | 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 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`(1) | A string indicating who created the policy set. | | `creationDate`(1) | An integer containing the creation time in milliseconds since January 1, 1970. | | `lastModifiedBy`(1) | A string indicating who last changed the policy set. | | `lastModifiedDate`(1) | An integer containing the last modified time in milliseconds since January 1, 1970. | (1) 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: 1. Create a policy set administrator. In the Advanced Identity Cloud admin console, select Identities > Manage > *Realm Name* Realm - Users > + New *Realm Name* Realm - User and fill the required fields. Record the username and password. 2. 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 3. Before making REST calls to manage policy sets, authenticate as the policy set administrator: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "tokenId": "", "successUrl": "/enduser/?realm=/alpha", "realm": "/alpha" } ``` For additional details, refer to [Session tokens after authentication](../am-authentication/rest-using-ssotokens.html). Use the `` as the value of the `` 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. ```bash $ curl \ --header ": " \ --header "Accept-API-Version: resource=1.0" \ 'https:///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](../developer-docs/crest/query.html) to refine the results. | Field | Supported `_queryFilter` operators | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | `name` | Equals (`eq`) | | `description` | | | `createdBy` | | | `lastModifiedBy` | | | `creationDate` | Equals (`eq`)(1) Greater than or equal to (`ge`) Greater than (`gt`) Less than or equal to (`le`) Less than (`lt`) | | `lastModifiedDate` | | (1) 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. ```bash $ curl \ --header ": " \ --header "Accept-API-Version: resource=1.0" \ 'https:///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. ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header ": " \ --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:///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. ```bash $ curl \ --request PUT \ --header "Content-Type: application/json" \ --header ": " \ --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:///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. ```bash $ curl \ --request DELETE \ --header ": " \ --header "Accept-API-Version: resource=1.0" \ 'https:///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, Advanced Identity Cloud returns an HTTP 409 Conflict status code and a message like the one in the following example: ```bash $ curl \ --request DELETE \ --header ": " \ --header "Accept-API-Version: resource=1.0" \ 'https:///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.