--- title: Policies over REST description: Policies are realm-specific, so the URI for the policies API can contain a realm component, such as /json/realms/root/realms/Realm Name/policies. If the realm is not specified in the URI, the top level realm is used. component: pingam version: 7.2 page_id: pingam:authorization-guide:rest-api-authz-policies canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authorization/rest-api-authz-policies.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authorization/rest-api-authz-policies.html section_ids: rest-api-authz-policies-query: Query policies proc-query-all-policies: List all policies in a realm proc-query-user-or-group-policies: Query policies in a realm by user or group rest-api-authz-policies-read: Read a specific policy rest-api-authz-policies-create: Create policies rest-api-authz-policies-update: Update policies rest-api-authz-policies-delete: Delete policies rest-api-authz-policies-copy-move-policies: Copy and move policies rest-api-authz-condition-types: Manage environment condition types rest-api-authz-condition-types-query: Query environment condition types rest-api-authz-condition-types-read: Read a specific environment condition type rest-api-authz-subject-types: Manage subject condition types rest-api-authz-subject-types-query: Query subject condition types rest-api-authz-subject-types-read: Read a specific subject condition types rest-api-authz-subject-attributes: Manage subject attributes rest-api-authz-subject-attributes-query: Query subject attributes rest-api-authz-decision-combiners: Manage decision combiners rest-api-authz-decision-combiner-query: Query decision combiners rest-api-authz-decision-combiner-read: Read a specific decision combiner --- # Policies over REST Policies are realm-specific, so the URI for the policies API can contain a realm component, such as `/json/realms/root/realms/Realm Name/policies`. If the realm is not specified in the URI, the top level realm is used. Policy resources are built from standard JSON objects and values (strings, numbers, objects, arrays, `true`, `false`, and `null`). > **Collapse: Example** > > ```json > { > "name": "mypolicy", > "active": true, > "description": "My Policy.", > "applicationName": "iPlanetAMWebAgentService", > "actionValues": { > "POST": true, > "GET": true > }, > "resources": [ > "http://www.example.com:80/*", > "http://www.example.com:80/*?*" > ], > "subject": { > "type": "AuthenticatedUsers" > }, > "condition": { > "type": "SimpleTime", > "startTime": "09:00", > "endTime": "17:00", > "startDay": "mon", > "endDay": "fri", > "enforcementTimeZone": "GMT" > }, > "resourceTypeUuid": "76656a38-5f8e-401b-83aa-4ccb74ce88d2", > "resourceAttributes": [ > { > "type": "User", > "propertyName": "givenName", > "propertyValues": [ ] > } > ], > "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", > "lastModifiedDate": "2015-05-11T17:39:09.393Z", > "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", > "creationDate": "2015-05-11T17:37:24.556Z" > } > ``` > > The values for the fields shown in the example are explained below: > > * `name` > > String matching the name in the URL (when creating the policy using HTTP PUT) or in the body (when creating the policy using HTTP POST). > > * `active` > > Boolean indicating whether AM considers the policy active for evaluation purposes, defaults to `false`. > > * `description` > > String describing the policy. > > * `resources` > > List of the resource name pattern strings to which the policy applies. Must conform to the pattern templates provided by the associated [resource type](rest-api-authz-resource-types.html). > > * `applicationName` > > String containing the policy set name, such as `"iPlanetAMWebAgentService"`, or `"mypolicyset"`. > > * `actionValues` > > Set of string action names, each set to a boolean indicating whether the action is allowed. Chosen from the available actions provided by the associated [resource type](rest-api-authz-resource-types.html). > > | | | > | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | Action values can also be expressed as numeric values. When using numeric values, use the value `0` for `false` and use any non-zero numeric value for `true`. | > > * `subject` > > Specifies the subject conditions to which the policy applies, where subjects can be combined by using the built-in types `"AND"`, `"OR"`, and `"NOT"`, and where subject implementations are pluggable. > > Subjects are shown as JSON objects with `type` set to the name of the implementation (using a short name for all registered subject implementations), and other fields, depending on the implementation. The subject types registered by default include the following: > > * `"AuthenticatedUsers"`, meaning any user that has successfully authenticated to AM. > > ```json > { > "type": "AuthenticatedUsers" > } > ``` > > | | | > | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | The `AuthenticatedUsers` subject condition does not take into account the realm to which a user authenticated. Any user that has authenticated successfully to any realm passes this subject condition.To test whether a user has authenticated successfully to a specific realm, add the `AuthenticateToRealm` environment condition. | > > * `"Identity"` to specify one or more users from an AM identity repository: > > ```json > { > "type": "Identity", > "subjectValues": [ > "uid=scarter,ou=People,dc=example,dc=com", > "uid=ahall,ou=People,dc=example,dc=com" > ] > } > ``` > > You can also use the `"Identity"` subject type to specify one or more groups from an identity repository: > > ```json > { > "type": "Identity", > "subjectValues": [ > "cn=HR Managers,ou=Groups,dc=example,dc=com" > ] > } > ``` > > * `"JwtClaim"` to specify a claim in a user's JSON web token (JWT). > > ```json > { > "type": "JwtClaim", > "claimName": "sub", > "claimValue": "scarter" > } > ``` > > * `"NONE"`, meaning never match any subject. The result is not that access is denied, but rather that the policy itself does not match and therefore cannot be evaluated in order to allow access. > > The following example defines the subject either as the user Sam Carter from an AM identity repository, or as a user with a JWT claim with a subject claim with the value `scarter`: > > ```json > { > "subject": { > "type": "OR", > "subjects": [{ > "type": "Identity", > "subjectValues": [ > "uid=scarter,ou=People,dc=example,dc=com" > ] > }, > { > "type": "JwtClaim", > "claimName": "sub", > "claimValue": "scarter" > } > ] > } > } > ``` > > To read a single subject type description, or to list all the available subject types, see [Manage subject condition types](#rest-api-authz-subject-types). > > * `condition` > > Conditions are shown as JSON objects with `"type"` set to the name of the implementation (using a short name for all registered condition implementations), and other fields depending on the implementation. The condition types registered by default include the following. > > * `"AMIdentityMembership"` to specify a list of AM users and groups. > > ```json > { > "type": "AMIdentityMembership", > "amIdentityName": [ > "id=scarter,ou=People,dc=example,dc=com" > ] > } > ``` > > | | | > | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | > | | Java agents and web agents do not support the `AMIdentityMembership` environment condition. Instead, use the equivalent `Identity` subject condition. | > > * `"AuthLevel"` to specify the authentication level. > > ```json > { > "type": "AuthLevel", > "authLevel": 2 > } > ``` > > * `"AuthScheme"` to specify the authentication module used to authenticate, the policy set name, and a timeout for authentication. > > ```json > { > "type": "AuthScheme", > "authScheme": [ > "DataStore" > ], > "applicationName": "iPlanetAMWebAgentService", > "applicationIdleTimeout": 10 > } > ``` > > * `"AuthenticateToRealm"` to specify the realm to which the user authenticated. > > ```json > { > "type": "AuthenticateToRealm", > "authenticateToRealm": "MyRealm" > } > ``` > > * `"AuthenticateToService"` to specify the authentication tree or chain that was used to authenticate. > > ```json > { > "type": "AuthenticateToService", > "authenticateToService": "MyAuthnTree" > } > ``` > > * `"IPv4"` or `"IPv6"` to specify an IP address range from which the request originated. > > ```json > { > "type": "IPv4", > "startIp": "127.0.0.1", > "endIp": "127.0.0.255" > } > ``` > > You can also use the `"IPv4"` and `"IPv6"` conditions with the `"dnsName"` field to specify domain names from which the request originated. Omit `"startIp"` and `"endIp"` when using `"dnsName"`. > > ```json > { > "type": "IPv4", > "dnsName": [ > "*.example.com" > ] > } > ``` > > * `"LDAPFilter"` to specify an LDAP search filter. The user's entry is tested against the search filter in the directory configured in the Policy Configuration Service. > > ```json > { > "type": "LDAPFilter", > "ldapFilter": "(&(c=US)(preferredLanguage=en-us))" > } > ``` > > * `"LEAuthLevel"` to specify a maximum acceptable authentication level. > > ```json > { > "type": "LEAuthLevel", > "authLevel": 2 > } > ``` > > * `"OAuth2Scope"` to specify a list of attributes that must be present in the user profile. > > ```json > { > "type": "OAuth2Scope", > "requiredScopes": [ > "name", > "address", > "email" > ] > } > ``` > > * `"ResourceEnvIP"` to specify a complex condition such as whether the user is making a request from a given host and has authenticated with a given authentication level. For example: > > ```json > { > "type": "ResourceEnvIP", > "resourceEnvIPConditionValue": [ > "IF IP=[127.168.10.*] THEN authlevel=4" > ] > } > ``` > > Entries must take the form of one or more IF…​ELSE statements. If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. The IF statement can specify an IP to match the user's IP address, or a dnsName to match their DNS name. The IP address can be IPv4 or IPv6 format, or a hybrid of the two, and can include wildcard characters. > > The available parameters for the THEN statement are as follows: > > | | | > | ------------- | ------------------------------------------------------------------- | > | `module` | The module used to authenticate the user. For example, `DataStore`. | > | `service` | The service that was used to authenticate the user. | > | `authlevel` | The minimum required authentication level. | > | `role` | The role of the authenticated user. | > | `user` | The name of the authenticated user. | > | `redirectURL` | The URL the user was redirected from. | > | `realm` | The realm that was used to authenticate the user. | > > * `"Session"` to specify how long the user's session has been active, and to terminate the session if it is too old, forcing the user to reauthenticate. > > Note that AM terminates client-side sessions only if session denylisting is in effect. For more information about session denylisting, see [Session termination](../security-guide/session-state-session-termination.html). > > ```json > { > "type": "Session", > "maxSessionTime": "10", > "terminateSession": false > } > ``` > > * `"SessionProperty"` to specify attributes set in the user's session. > > ```json > { > "type": "SessionProperty", > "ignoreValueCase": true, > "properties": { > "CharSet": [ > "UTF-8" > ], > "clientType": [ > "genericHTML" > ] > } > } > ``` > > * `"SimpleTime"` to specify a time range, where `"type"` is the only required field. > > ```json > { > "type": "SimpleTime", > "startTime": "07:00", > "endTime": "19:00", > "startDay": "mon", > "endDay": "fri", > "startDate": "2015:01:01", > "endDate": "2015:12:31", > "enforcementTimeZone": "GMT+0:00" > } > ``` > > The following example defines the condition as neither Saturday or Sunday, nor certain client IP addresses. > > ```json > { > "type": "NOT", > "condition": { > "type": "OR", > "conditions": [ > { > "type": "SimpleTime", > "startDay": "sat", > "endDay": "sun", > "enforcementTimeZone": "GMT+8:00" > }, > { > "type": "IPv4", > "startIp": "192.168.0.1", > "endIp": "192.168.0.255" > } > ] > } > } > ``` > > To read a single condition type description, or to list all the available condition types, see [Manage environment condition types](#rest-api-authz-condition-types). > > * `resourceTypeUuid` > > The UUIDs of the resource type associated with the policy. > > * `resourceAttributes` > > List of attributes to return, with decisions. These attributes are known as *response attributes*, and do not apply to `OAuth2 Scope` resource types. > > The response attribute provider is pluggable. The default implementation provides for statically defined attributes and for attributes retrieved from user profiles. > > Attributes are shown as JSON objects: **`type` is set to the name of the implementation (by default `"Static"` for statically defined attributes or `"User"` for attributes from the user profile) **`propertyName` is set to the attribute names. For static attributes, `"propertyValues"` holds the attribute values. For user attributes, `"propertyValues"` is not used; the property values are determined at evaluation time. > > * `createdBy` > > A string containing the universal identifier DN of the subject that created the policy. > > * `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. > > If the policy 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 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](../authentication-guide/rest-using-ssotokens.html). ## Query policies Use REST calls to list all the policies in a realm, or to find policies that explicitly apply to a given user or group. ### List all policies in a realm 1. To list all the policies in a realm, send an HTTP GET request to the `/json/realms/root/realms/Realm Name/policies` endpoint, with a `_queryFilter` parameter set to `true`. | | | | - | ------------------------------------------------------------------------------------- | | | If the realm is not specified in the URL, AM returns policies 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_queryFilter=true" { "result":[ { "name":"example", "active":true, "description":"Example Policy", "applicationName":"iPlanetAMWebAgentService", "actionValues":{ "POST":false, "GET":true }, "resources":[ "http://www.example.com:80/", "http://www.example.com:80/?*" ], "subject":{ "type":"Identity", "subjectValues":[ "uid=demo,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4", "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":"2015-05-11T14:48:08.711Z", "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":"2015-05-11T14:48:08.711Z" } ], "resultCount":1, "pagedResultsCookie":null, "remainingPagedResults":0 } ``` Additional query strings can be specified to alter the returned results. For more information, see [Query](../REST-guide/rest-intro.html#about-crest-query). > **Collapse: Supported \_queryFilter fields and operators** > > | Field | Supported operators | > | --------------------- | ------------------------------------------------------------------------------------------------------------------- | > | `name` | Equals (`eq`) | > | `description` | Equals (`eq`) | > | `applicationName` | 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. ### Query policies in a realm by user or group You can query policies that explicitly reference a given subject by providing the universal ID (UID) of either a user or group. AM returns any policies that explicitly apply to the user or group as part of a subject condition. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can obtain the universal ID for a user or group by using REST.See [Read an identity](../setup-guide/sec-rest-realm-rest.html#rest-api-read-identity). | The following caveats apply to querying policies by user or group: * Group membership is not considered. For example, querying policies for a specific user will not return policies that only use groups in their subject conditions, even if the user is a member of any of those groups. * Wildcards are not supported, only exact matches. * Only policies with a subject condition type of `Identity` are queried—environment conditions are not queried. The `Identity` subject condition type is labeled as *Users & Groups* in the policy editor in the AM admin UI. * Policies with subject conditions that only contain the user or group in a logical *NOT* operator are not returned. To query policies by user or group: 1. Send an HTTP GET request to the `/json/realms/root/realms/Realm Name/policies` endpoint, with a `_queryId` parameter set to `queryByIdentityUid`, and a `uid` parameter containing the universal ID of the user or group: ```bash $ curl \ --get \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=1.0" \ --data "_queryId=queryByIdentityUid" \ --data "uid=id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org" \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies" { "result":[ { "name":"mySubRealmPolicy", "active":true, "description":"", "resources":[ "://:*/?", "://:*/*" ], "applicationName":"iPlanetAMWebAgentService", "actionValues":{ "POST":true, "PATCH":true, "GET":true, "DELETE":true, "OPTIONS":true, "PUT":true, "HEAD":true }, "subject":{ "type":"Identity", "subjectValues":[ "id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org" ] }, "resourceTypeUuid":"76656a38-5f8e-401b-83aa-4ccb74ce88d2", "lastModifiedBy":"id=amAdmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":"2016-05-05T08:45:35.716Z", "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":"2016-05-03T13:45:38.137Z" } ], "resultCount":1, "pagedResultsCookie":null, "totalPagedResultsPolicy":"NONE", "totalPagedResults":-1, "remainingPagedResults":0 } ``` | | | | - | -------------------------------------------------------------------------- | | | If the realm is not specified in the URL, AM searches 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. ## Read a specific policy To read an individual policy in a realm, send an HTTP GET request to the `/json/realms/root/realms/Realm Name/policies` endpoint, and specify the policy 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/example" { "result": [ { "name": "example", "active": true, "description": "Example Policy", "applicationName": "iPlanetAMWebAgentService", "actionValues": { "POST": false, "GET": true }, "resources": [ "http://www.example.com:80/", "http://www.example.com:80/?*" ], "subject": { "type": "Identity", "subjectValues": [ "uid=demo,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4", "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate": "2015-05-11T14:48:08.711Z", "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate": "2015-05-11T14:48:08.711Z" } ], "resultCount": 1, "pagedResultsCookie": null, "remainingPagedResults": 0 } ``` 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 policies To create a policy in a realm, send an HTTP POST request to the `/json/realms/root/realms/Realm Name/policies` endpoint, with an `_action` parameter set to `create`. Include a JSON representation of the policy in the POST 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. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before testing your OAuth 2.0 policies, ensure your OAuth 2.0 service is configured to interact with AM's authorization service. Perform the following steps:- Go to Realms > *Realm Name* > Services > OAuth2 Provider. - Ensure that Use Policy Engine for Scope decisions is enabled.For more information about testing OAuth 2.0 policies, see [Dynamic OAuth 2.0 authorization](oauth2-authorization.html). | 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`). ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ --data '{ "name": "mypolicy", "active": true, "description": "My Policy.", "applicationName": "iPlanetAMWebAgentService", "actionValues": { "POST": false, "GET": true }, "resources": [ "http://www.example.com:80/", "http://www.example.com:80/?" ], "subject": { "type": "Identity", "subjectValues": [ "uid=demo,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4" }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_action=create" { "name":"mypolicy", "active":true, "description":"My Policy.", "applicationName":"iPlanetAMWebAgentService", "actionValues":{ "POST":false, "GET":true }, "resources":[ "http://www.example.com:80/", "http://www.example.com:80/?" ], "subject":{ "type":"Identity", "subjectValues":[ "uid=demo,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4", "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":"2015-05-11T14:48:08.711Z", "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":"2015-05-11T14:48:08.711Z" } ``` 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 policies To update an individual policy in a realm, send an HTTP PUT request to the `/json/realms/root/realms/Realm Name/policies` endpoint, and specify the policy name in the URL. Include a JSON representation of the updated policy 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`). ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --data '{ "name": "myupdatedpolicy", "active": true, "description": "My Updated Policy.", "resources": [ "http://www.example.com:80/", "http://www.example.com:80/?*" ], "actionValues": { "POST": true, "GET": true }, "subject": { "type": "Identity", "subjectValues": [ "uid=scarter,ou=People,dc=example,dc=com", "uid=bjenson,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4" }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/mypolicy" ``` 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 policies To delete an individual policy in a realm, send an HTTP DELETE request to the `/json/realms/root/realms/Realm Name/policies` endpoint, and specify the policy 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=2.1" \ --request DELETE \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/myupdatedpolicy" ``` ## Copy and move policies To copy or move an individual policy, send an HTTP POST request to the `/json/realms/root/realms/Realm Name/policies/policyName` endpoint as follows: * Specify the `_action=copy` or `_action=move` URL parameter. * Specify the realm in which the input policy resides in the URL. If the realm is not specified in the URL, AM copies or moves a policy from the top level realm. * Specify the policy to be copied or moved in the URL. * Specify the SSO token of an administrative user who has access to perform the operation in the `iPlanetDirectoryPro` header. > **Collapse: JSON input data for copying or moving individual policies** > > | Object | Property | Description | > | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `to` | `name` | The name of the output policy.Required unless you are copying or moving a policy to a different realm and you want the output policy to have the same name as the input policy. | > | `to` | `application` | The policy set in which to place the output policy.Required when copying or moving a policy to a different policy set. | > | `to` | `realm` | The realm in which to place the output policy. If not specified, AM copies or moves the policy within the realm identified in the URL.Required when copying or moving a policy to a different realm. | > | `to` | `resourceType` | The UUID of the output policy's resource type.Required when copying or moving a policy to a different realm. | The follow example copies the policy `myPolicy` to `myNewPolicy`. The output policy is placed in the `alpha` realm, in the same policy set as the input policy: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=2.1" \ --request DELETE \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/myupdatedpolicy" {} ``` The following example moves a policy named `myPolicy` in the `myRealm` realm to `myMovedPolicy` in the `myOtherRealm` realm. The output policy is placed in the `iPlanetAMWebAgentService` policy set, which is the policy set in which the input policy is located. The realm `myOtherRealm` must be configured as follows for the example to run successfully: * It must have a resource type that has the same resources as the resource type configured for the `myPolicy` policy. * It must have a policy set named `iPlanetAMWebAgentService`. ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=2.1" \ --data '{ "to": { "name": "myMovedPolicy", "realm": "/myOtherRealm", "resourceType: "616b3d02-7a8d-4422-b6a7-174f62afd065" } }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/myPolicy?_action=move" { "name":"myMovedPolicy", "active":true, "description":"", "actionValues":{}, "applicationName":"iPlanetAMWebAgentService", "resources":["://:*/*"], "subject":{"type":"NONE"}, "resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065", "lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com", "lastModifiedDate":"2015-12-21T19:32:59.502Z", "createdBy":"id=amadmin,ou=user,dc=example,dc=com", "creationDate":"2015-12-21T19:32:59.502Z" } ``` To copy and move multiple policies—all the policies in a policy set—in a single operation, send an HTTP POST request to the `/json/realms/root/realms/Realm Name/policies` endpoint as follows: * Specify the `_action=copy` or `_action=move` URL parameter. * Specify the realm in which the input policies reside as part of the URL. If no realm is specified in the URL, AM copies or moves policies within the top level realm. * Specify the SSO token of an administrative user who has access to perform the operation in the `iPlanetDirectoryPro` header. > **Collapse: JSON input data for copying or moving multiple policies** > > | Object | Property | Description | > | --------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `from` | `application` | The policy set in which the input policies are located.Required. | > | `to` | `application` | The policy set in which to store output policies.Required when copying or moving policies to a different policy set. | > | `to` | `realm` | The realm in which to store output policies.Required when copying or moving policies to a different realm. | > | `to` | `namePostfix` | A value appended to output policy names in order to prevent name clashes.Required. | > | `resourceTypeMapping` | Varies | One or more resource types mappings, where the left side of the mapping specifies the UUID of a resource type used by the input policies, and the right side of the mapping specifies the UUID of a resource type used by the output policies. The two resource types should have the same resource patterns.Required when copying or moving policies to a different realm. | The following example copies all the policies in the `iPlanetAMWebAgentService` policy set in the `myRealm` realm to the `iPlanetAMWebAgentService` policy set in the `myOtherRealm` realm, appending the string `-copy` to the output policy names. The realm `myOtherRealm` must be configured as follows for the example to run successfully: * It must have a resource type that maps to the `ccb50c1a-206d-4946-9106-4164e8f2b35b` resource type. The two resource types should have the same resource patterns. * It must have a policy set named `iPlanetAMWebAgentService`. The JSON output shows that a single policy is copied. The policy `myNewPolicy` is copied to realm `myOtherRealm`. The copied policy receives the name `myOtherRealm-copy`: ```bash $ url \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5w…​" \ --header "Accept-API-Version: resource=2.1" \ --data '{ "from":{ "application":"iPlanetAMWebAgentService" }, "to":{ "realm":"/myOtherRealm", "namePostfix":"-copy" }, "resourceTypeMapping":{ "ccb50c1a-206d-4946-9106-4164e8f2b35b":"616b3d02-7a8d-4422-b6a7-174f62afd065" } }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_action=copy" { "name":"myNewPolicy-copy", "active":true, "description":"", "actionValues":{}, "applicationName":"iPlanetAMWebAgentService", "resources":["://:*/*"],"subject":{"type":"NONE"}, "resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065", "lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com", "lastModifiedDate":"2015-12-21T20:01:42.410Z", "createdBy":"id=amadmin,ou=user,dc=example,dc=com", "creationDate":"2015-12-21T20:01:42.410Z" } ``` ## Manage environment condition types Environment condition types describe the JSON representation of environment conditions that you can use in policy definitions. AM provides the `conditiontypes` REST endpoint for the following: * [Query environment condition types](#rest-api-authz-condition-types-query) * [Read a specific environment condition type](#rest-api-authz-condition-types-read) Environment condition types are server-wide, and do not differ by realm. Hence the URI for the condition types API does not contain a realm component, but is `/json/conditiontypes`. `Script` is the only environmental condition available for OAuth 2.0 policies. Use scripts to capture the `ClientId` environmental attribute. Environment condition types are represented in JSON and take the following form. Environment condition types are built from standard JSON objects and values (strings, numbers, objects, arrays, `true`, `false`, and `null`). ```json { "title": "IPv4", "logical": false, "config": { "type": "object", "properties": { "startIp": { "type": "string" }, "endIp": { "type": "string" }, "dnsName": { "type": "array", "items": { "type": "string" } } } } } ``` Notice that the environment condition type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an IPv4 environment condition has two properties, "startIp" and "endIp", that each take a single string value, and a third property, "dnsName," that takes an array of string values. In other words, a concrete IP environment condition specification without a DNS name constraint could be represented in a policy definition as in the following example: ```json { "type": "IPv4", "startIp": "127.0.0.1", "endIp": "127.0.0.255" } ``` The configuration is what differs the most across environment condition types. The NOT condition, for example, takes a single condition object as the body of its configuration. ```json { "title" : "NOT", "logical" : true, "config" : { "type" : "object", "properties" : { "condition" : { "type" : "object", "properties" : { } } } } } ``` The concrete NOT condition therefore takes the following form. ```json { "type": "NOT", "condition": { ... } } ``` The OR condition takes an array of conditions. ```json { "title" : "OR", "logical" : true, "config" : { "type" : "object", "properties" : { "conditions" : { "type" : "array", "items" : { "type" : "any" } } } } } ``` A corresponding concrete OR condition thus takes the following form. ```json { "type": "OR", "conditions": [ { ... }, { ... }, ... ] } ``` ### Query environment condition types To list all environment condition types, send an HTTP GET request to the `/json/conditiontypes` endpoint, with a `_queryFilter` parameter set to `true`. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ https://openam.example.com:8443/openam/json/realms/root/conditiontypes?_queryFilter=true { "result" : [ { "title": "IPv4", } "logical": false, "config": { "type": "object", "properties": { "startIp": { "type": "string" }, "endIp": { "type": "string" }, "dnsName": { "type": "array", "items": { "type": "string" } } } } }, { "title": "NOT", "logical": true, "config": { "type": "object", "properties": { "condition": { "type": "object", "properties": { } } } } }, {…​}, {…​}, {…​} ], "resultCount" : 18, "pagedResultsCookie" : null, "remainingPagedResults" : 0 } ``` Additional query strings can be specified to alter the returned results. For more information, see [Query](../REST-guide/rest-intro.html#about-crest-query). ### Read a specific environment condition type To read an individual environment condition type, send an HTTP GET request to the `/json/conditiontypes` endpoint, and specify the environment condition type name in the URL. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/conditiontypes/IPv4 { "title":"IPv4", "logical":false, "config":{ "type":"object", "properties":{ "startIp":{ "type":"string" }, "endIp":{ "type":"string" }, "dnsName":{ "type":"array", "items":{ "type":"string" } } } } } ``` ## Manage subject condition types Subject condition types describe the JSON representation of subject conditions that you can use in policy definitions. AM provides the `subjecttypes` REST endpoint for the following: * [Query subject condition types](#rest-api-authz-subject-types-query) * [Read a specific subject condition types](#rest-api-authz-subject-types-read) Environment condition types are server-wide, and do not differ by realm. Hence the URI for the condition types API does not contain a realm component, but is `/json/subjecttypes`. Subject condition types are represented in JSON and take the following form. Subject condition types are built from standard JSON objects and values (strings, numbers, objects, arrays, `true`, `false`, and `null`). ```none { "title" : "Identity", "logical" : false, "config" : { "type" : "object", "properties" : { "subjectValues" : { "type" : "array", "items" : { "type" : "string" } } } } } ``` Notice that the subject type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an Identity subject condition has one property, "subjectValues", which takes an array of string values. In other words, a concrete Identity subject condition specification is represented in a policy definition as in the following example: ```json { "type": "Identity", "subjectValues": [ "uid=scarter,ou=People,dc=example,dc=com" ] } ``` The configuration is what differs the most across subject condition types. The AND condition, for example, takes an array of subject condition objects as the body of its configuration. ```json { "title" : "AND", "logical" : true, "config" : { "type" : "object", "properties" : { "subjects" : { "type" : "array", "items" : { "type" : "any" } } } } } ``` The concrete AND subject condition therefore takes the following form. ```json { "type": "AND", "subject": [ {...}, {...}, {...}, {...} ] } ``` ### Query subject condition types To list all environment condition types, send an HTTP GET request to the `/json/subjecttypes` endpoint, with a `_queryFilter` parameter set to `true`. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/subjecttypes?_queryFilter=true { "result" : [ { "title": "JwtClaim" } "logical": false, "config": { "type": "object", "properties": { "claimName": { "type": "string" }, "claimValue": { "type": "string" } } } }, { "title": "NOT", "logical": true, "config": { "type": "object", "properties": { "subject": { "type": "object", "properties": { } } } } }, {…​}, {…​}, {…​} ], "resultCount" : 5, "pagedResultsCookie" : null, "remainingPagedResults" : 0 } ``` Additional query strings can be specified to alter the returned results. For more information, see [Query](../REST-guide/rest-intro.html#about-crest-query). ### Read a specific subject condition types To read an individual subject condition type, send an HTTP GET request to the `/json/subjecttypes` endpoint, and specify the subject condition type name in the URL. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/subjecttypes/Identity { "title" : "Identity", "logical" : false, "config" : { "type" : "object", "properties" : { "subjectValues" : { "type" : "array", "items" : { "type" : "string" } } } } ``` ## Manage subject attributes When you define a policy subject condition, the condition can depend on values of subject attributes stored in a user's profile. The list of possible subject attributes that you can use depends on the LDAP User Attributes configured for the identity store where AM looks up the user's profile. AM provides the `subjectattributes` REST endpoint for [Query subject attributes](#rest-api-authz-subject-attributes-query). Subject attributes derive from the list of LDAP user attributes configured for the identity store. For more information, see [Identity stores](../setup-guide/setting-up-identity-stores.html). ### Query subject attributes To list all subject attributes, send an HTTP GET request to the `/json/subjectattributes` endpoint, with a `_queryFilter` parameter set to `true`. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/subjectattributes/?_queryFilter=true { "result" : [ "sunIdentityServerPPInformalName", "sunIdentityServerPPFacadeGreetSound", "uid", "manager", "sunIdentityServerPPCommonNameMN", "sunIdentityServerPPLegalIdentityGender", "preferredLocale", "…​", "…​", "…​" ], "resultCount": 87, "pagedResultsCookie": null, "remainingPagedResults": 0 } ``` Note that no pagination cookie is set and the subject attribute names are all returned as part of the "result" array. ## Manage decision combiners Decision combiners describe how to resolve policy decisions when multiple policies apply. AM provides the `decisioncombiners` REST endpoint for the following: * [Query decision combiners](#rest-api-authz-decision-combiner-query) * [Read a specific decision combiner](#rest-api-authz-decision-combiner-read) Decision combiners are server-wide, and do not differ by realm. Hence the URI for the condition types API does not contain a realm component, but is `/json/decisioncombiners`. ### Query decision combiners To list all decision combiners, send an HTTP GET request to the `/json/decisioncombiners` endpoint, with a `_queryFilter` parameter set to `true`. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ https://openam.example.com:8443/openam/json/realms/root/realms/alpha/decisioncombiners?_queryFilter=true { "result":[ { "title":"DenyOverride" } ], "resultCount":1, "pagedResultsCookie":null, "remainingPagedResults":0 } ``` Additional query strings can be specified to alter the returned results. For more information, see [Query](../REST-guide/rest-intro.html#about-crest-query). ### Read a specific decision combiner To view an individual decision combiner, send an HTTP GET on its resource. To read an individual decision combiner, send an HTTP GET request to the `/json/decisioncombiners` endpoint, and specify the decision combiner name in the URL. 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. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/realms/alpha/decisioncombiners/DenyOverride { "title" : "DenyOverride" } ```