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
).
Example
{
"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.
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.
Action values can also be expressed as numeric values. When using numeric values, use the value
0
forfalse
and use any non-zero numeric value fortrue
. 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.{ "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:{ "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:{ "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).{ "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
: -
{
"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.
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.{ "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 equivalentIdentity
subject condition. -
"AuthLevel"
to specify the authentication level.{ "type": "AuthLevel", "authLevel": 2 }
-
"AuthScheme"
to specify the authentication module used to authenticate, the policy set name, and a timeout for authentication.{ "type": "AuthScheme", "authScheme": [ "DataStore" ], "applicationName": "iPlanetAMWebAgentService", "applicationIdleTimeout": 10 }
-
"AuthenticateToRealm"
to specify the realm to which the user authenticated.{ "type": "AuthenticateToRealm", "authenticateToRealm": "MyRealm" }
-
"AuthenticateToService"
to specify the authentication tree or chain that was used to authenticate.{ "type": "AuthenticateToService", "authenticateToService": "MyAuthnTree" }
-
"IPv4"
or"IPv6"
to specify an IP address range from which the request originated.{ "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"
.{ "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.{ "type": "LDAPFilter", "ldapFilter": "(&(c=US)(preferredLanguage=en-us))" }
-
"LEAuthLevel"
to specify a maximum acceptable authentication level.{ "type": "LEAuthLevel", "authLevel": 2 }
-
"OAuth2Scope"
to specify a list of attributes that must be present in the user profile.{ "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:{ "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.
{ "type": "Session", "maxSessionTime": "10", "terminateSession": false }
-
"SessionProperty"
to specify attributes set in the user’s session.{ "type": "SessionProperty", "ignoreValueCase": true, "properties": { "CharSet": [ "UTF-8" ], "clientType": [ "genericHTML" ] } }
-
"SimpleTime"
to specify a time range, where"type"
is the only required field.{ "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.
{ "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.
-
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.
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
-
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 totrue
.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 asamAdmin
, who has access to perform the operation.$ 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.
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. |
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. TheIdentity
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:
-
Send an HTTP GET request to the
/json/realms/root/realms/Realm Name/policies
endpoint, with a_queryId
parameter set toqueryByIdentityUid
, and auid
parameter containing the universal ID of the user or group:$ 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 asamAdmin
, 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.
$ 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:
For more information about testing OAuth 2.0 policies, see Dynamic OAuth 2.0 authorization. |
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
).
$ 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
).
$ 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.
$ 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.
JSON input data for copying or moving individual policies
Object | Property | Description |
---|---|---|
|
|
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. |
|
|
The policy set in which to place the output policy. Required when copying or moving a policy to a different policy set. |
|
|
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. |
|
|
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:
$ 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
.
$ 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.
JSON input data for copying or moving multiple policies
Object | Property | Description |
---|---|---|
|
|
The policy set in which the input policies are located. Required. |
|
|
The policy set in which to store output policies. Required when copying or moving policies to a different policy set. |
|
|
The realm in which to store output policies. Required when copying or moving policies to a different realm. |
|
|
A value appended to output policy names in order to prevent name clashes. Required. |
|
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
:
$ 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:
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
).
{
"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:
{
"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.
{
"title" : "NOT",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"condition" : {
"type" : "object",
"properties" : {
}
}
}
}
}
The concrete NOT condition therefore takes the following form.
{
"type": "NOT",
"condition": {
...
}
}
The OR condition takes an array of conditions.
{
"title" : "OR",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"conditions" : {
"type" : "array",
"items" : {
"type" : "any"
}
}
}
}
}
A corresponding concrete OR condition thus takes the following form.
{
"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.
$ 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.
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.
$ 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:
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
).
{
"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:
{
"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.
{
"title" : "AND",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"subjects" : {
"type" : "array",
"items" : {
"type" : "any"
}
}
}
}
}
The concrete AND subject condition therefore takes the following form.
{
"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.
$ 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.
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.
$ 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.
Subject attributes derive from the list of LDAP user attributes configured for the identity store. For more information, see Identity stores.
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.
$ 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:
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.
$ 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.
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.
$ 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"
}