This section shows how you can request a policy decision over REST for specific resources.

To request policy decisions for specific resources, perform an HTTP POST using the evaluation action to the appropriate path under the URI where OpenAM is deployed, /json{/realm}{/subrealm}/policies?_action=evaluate, where realm and subrealm optionally specifies the realm. The payload for the HTTP POST is a JSON object that specifies at least the resources, and takes the following form.

{
    "resources": [
        "resource1",
        "resource2",
        ...,
        "resourceN"
    ],
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The example below requests policy decisions for two URL resources. The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --data '{
    "resources": [
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ],
    "application": "iPlanetAMWebAgentService"
 }' \
 https://openam.example.com:8443/openam/json/policies?_action=evaluate
 [ {
  "resource" : "http://www.example.com/do?action=run",
  "actions" : {
  },
  "attributes" : {
  },
  "advices" : {
    "AuthLevelConditionAdvice" : [ "3" ]
  }
}, {
  "resource" : "http://www.example.com/index.html",
  "actions" : {
    "POST" : false,
    "GET" : true
  },
  "attributes" : {
    "cn" : [ "demo" ]
  },
  "advices" : {
  }
 }
]

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.

When OpenAM returns a policy decision, the JSON for the decision can include an "advices" field. This field contains hints for the policy enforcement point.

{
    "advices": {
        "type": [
            "advice"
        ]
    }
}

The "advices" returned depend on policy conditions. For more information about OpenAM policy conditions, see "Managing Policies".

This section shows examples of the different types of policy decision advice and the conditions that cause OpenAM to return the advice.

"AuthLevel" and "LEAuthLevel" condition failures can result in advice showing the expected or maximum possible authentication level. For example, failure against the following condition:

{
    "type": "AuthLevel",
    "authLevel": 2
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "2"
    ]
}

An "AuthScheme" condition failure can result in advice showing one or more required authentication modules. For example, failure against the following condition:

{
    "type": "AuthScheme",
    "authScheme": [
        "HOTP"
    ],
    "applicationName": "iPlanetAMWebAgentService",
    "applicationIdleTimeout": 10
}

Leads to this advice:

{
    "AuthSchemeConditionAdvice": [
        "HOTP"
    ]
}

An "AuthenticateToRealm" condition failure can result in advice showing the name of the realm to which authentication is required. For example, failure against the following condition:

{
    "type": "AuthenticateToRealm",
    "authenticateToRealm": "MyRealm"
}

Leads to this advice:

{
    "AuthenticateToRealmConditionAdvice": [
        "/myRealm"
    ]
}

An "AuthenticateToService" condition failure can result in advice showing the name of the required authentication chain. For example, failure against the following condition:

{
    "type": "AuthenticateToService",
    "authenticateToService": "MyAuthnChain"
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A "ResourceEnvIP" condition failure can result in advice showing that indicates corrective action to be taken to resolve the problem. The advice varies, depending on what the condition tests. For example, failure against the following condition:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.12] THEN authlevel=4"
    ]
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "4"
    ]
}

Failure against a different type of "ResourceEnvIP" condition such as the following:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.11] THEN service=MyAuthnChain"
    ]
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A "Session" condition failure can result in advice showing that access has been denied because the user's stateful or stateless session has been active longer than allowed by the condition. The advice will also show if the user's session was terminated and reauthentication is required. For example, failure against the following condition:

{
    "type": "Session",
    "maxSessionTime": "10",
    "terminateSession": false
}

Leads to this advice:

{
    "SessionConditionAdvice": [
        "deny"
    ]
}

When policy evaluation denials occur against the following conditions, OpenAM does not return any advice:

This section shows how you can request policy decisions over REST for a resource and all other resources in the subtree beneath it.

To request policy decisions for a tree of resources, perform an HTTP POST using the evaluation action to the appropriate path under the URI where OpenAM is deployed, /json{/realm}/policies?_action=evaluateTree, where realm optionally specifies the realm. The payload for the HTTP POST is a JSON object that specifies at least the root resource, and takes the following form.

{
    "resource": "resource string",
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The example below requests policy decisions for http://www.example.com/. The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation, and the subject takes the SSO token of the user who wants to access a resource.

 $ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iPlanetDirectoryPro: AQIC5...NDU1*" \
 --data '{
    "resource": "http://www.example.com/",
    "subject": { "ssoToken": "AQIC5...zE4*" }
 }' \
 https://openam.example.com:8443/openam/json/policies?_action=evaluateTree
 [ {
  "resource" : "http://www.example.com/",
  "actions" : {
    "GET" : true,
    "OPTIONS" : true,
    "HEAD" : true
  },
  "attributes" : {
  },
  "advices" : {
  }
}, {
  "resource" : "http://www.example.com/*",
  "actions" : {
    "POST" : false,
    "PATCH" : false,
    "GET" : true,
    "DELETE" : true,
    "OPTIONS" : true,
    "HEAD" : true,
    "PUT" : true
  },
  "attributes" : {
    "myStaticAttr" : [ "myStaticValue" ]
  },
  "advices" : {
  }
}, {
  "resource" : "http://www.example.com/*?*",
  "actions" : {
    "POST" : false,
    "PATCH" : false,
    "GET" : false,
    "DELETE" : false,
    "OPTIONS" : true,
    "HEAD" : false,
    "PUT" : false
  },
  "attributes" : {
  },
  "advices" : {
    "AuthLevelConditionAdvice" : [ "3" ]
  }
} ]

Notice that OpenAM returns decisions not only for the specified resource, but also for matching resource names in the tree whose root is the specified resource.

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.

To list all the resource types in a realm, perform an HTTP GET to the /json{/realm}/resourcetypes 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..." \
https://openam.example.com:8443/openam/json/myrealm/resourcetypes?_queryFilter=true
{
    "result": [
    {
        "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e3",
        "name": "LIGHTS",
        "description": "",
        "patterns": [
            "light://*/*"
        ],
        "actions": {
            "switch_off": true,
            "switch_on": true
        },
        "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
        "creationDate": 1431013059131,
        "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
        "lastModifiedDate": 1431013069803
    }
    ],
    "resultCount": 1,
    "pagedResultsCookie": null,
    "remainingPagedResults": 0
}

Additional query strings can be specified to alter the returned results. For more information, see "Filtering, Sorting, and Paging Results".

To read an individual resource types in a realm, perform an HTTP GET to the /json{/realm}/resourcetypes endpoint, and specify the UUID 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..." \
https://openam.example.com:8443/openam/json/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e3
{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e3",
    "name": "LIGHTS",
    "description": "",
    "patterns": [
        "light://*/*"
    ],
    "actions": {
        "switch_off": true,
        "switch_on": true
    },
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": 1431013059131,
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": 1431013069803
}

To create a resource type in a realm, perform an HTTP POST to the /json{/realm}/resourcetypes endpoint, with an _action parameter set to create. Include a JSON representation of the resource type in the POST data.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: 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..." \
--data '{
    "name": "My Resource Type",
    "actions": {
        "LEFT": true,
        "RIGHT": true,
        "UP": true,
        "DOWN": true
    },
    "patterns": [
        "http://device/location/*"
    ]
}' \
https://openam.example.com:8443/openam/json/myrealm/resourcetypes/?_action=create
{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name": "My Resource Type",
    "description": null,
    "patterns": [
        "http://device/location/*"
    ],
    "actions": {
        "RIGHT": true,
        "DOWN": true,
        "UP": true,
        "LEFT": true
    },
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": 1431099940616,
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": 1431099940616
}

To update an individual resource type in a realm, perform an HTTP PUT to the /json{/realm}/resourcetypes endpoint, and specify the UUID in both the URL and the PUT body. Include a JSON representation of the updated resource type in the PUT data, alongside the UUID.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--header "iPlanetDirectoryPro: AQIC5..." \
--request PUT \
--header "Content-Type: application/json" \
--data '{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name": "My Updated Resource Type",
    "actions": {
        "LEFT": false,
        "RIGHT": false,
        "UP": false,
        "DOWN": false
    },
    "patterns": [
        "http://device/location/*"
    ]
}' \
https://openam.example.com:8443/openam/json/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4
{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name": "My Updated Resource Type",
    "description": null,
    "patterns": [
        "http://device/location/*"
    ],
    "actions": {
        "RIGHT": false,
        "DOWN": false,
        "UP": false,
        "LEFT": false
    },
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": 1431099940616,
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": 1431101016427
}

To delete an individual resource types in a realm, perform an HTTP DELETE to the /json{/realm}/resourcetypes endpoint, and specify the UUID 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 \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/json/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4
{}

You can only delete resource types that are not being used by a policy set or policy. Trying to delete a resource type that is in use will return an HTTP 409 Conflict status code, with a message such as:

{
    "code": 409,
    "reason": "Conflict",
    "message": "Unable to remove resource type 12345a67-8f0b-123c-45de-6fab78cd01e4 because it is
                referenced in the policy model."
}

Remove the resource type from any associated policy sets or policies to be able to delete it.

To list all application types, perform an HTTP GET to the /json/applicationtypes 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..." \
https://openam.example.com:8443/openam/json/applicationtypes?_queryFilter=true
{
    "result" : [ ... application types ... ],
    "resultCount" : 8,
    "pagedResultsCookie" : null,
    "remainingPagedResults" : -1
}

Additional query strings can be specified to alter the returned results. For more information, see "Filtering, Sorting, and Paging Results".

To read an individual application type, perform an HTTP GET to the /json/applicationtypes endpoint, and specify the application 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..." \
https://openam.example.com:8443/openam/json/applicationtypes/iPlanetAMWebAgentService
{
    "name": "iPlanetAMWebAgentService",
    "actions": {
        "POST": true,
        "PATCH": true,
        "GET": true,
        "DELETE": true,
        "OPTIONS": true,
        "PUT": true,
        "HEAD": true
    },
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "saveIndex": "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
    "searchIndex": "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
    "applicationClassName": "com.sun.identity.entitlement.Application"
}

To list all the policy sets in a realm, perform an HTTP GET to the /json{/realm}/applications 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..." \
https://openam.example.com:8443/openam/json/applications?_queryFilter=true
{
 "result": [
 {
   "_id": "iPlanetAMWebAgentService",
   "name": "iPlanetAMWebAgentService",
   "displayName": "Default Policy Set",
   "subjects": [
     "NOT",
     "OR",
     "JwtClaim",
     "AuthenticatedUsers",
     "AND",
     "Identity",
     "NONE"
   ],
   "saveIndex": null,
   "searchIndex": null,
   "entitlementCombiner": "DenyOverride",
   "resourceComparator": null,
   "attributeNames": [
   ],
   "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
   "editable": true,
   "resourceTypeUuids": [
     "76656a38-5f8e-401b-83aa-4ccb74ce88d2"
   ],
   "creationDate": 1480651214923,
   "lastModifiedDate": 1480651214923,
   "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
   "description": "The built-in Application used by OpenAM Policy Agents.",
   "applicationType": "iPlanetAMWebAgentService",
   "conditions": [
     "LEAuthLevel",
     "Script",
     "AuthenticateToService",
     "SimpleTime",
     "AMIdentityMembership",
     "OR",
     "IPv6",
     "IPv4",
     "SessionProperty",
     "AuthScheme",
     "AuthLevel",
     "NOT",
     "AuthenticateToRealm",
     "AND",
     "ResourceEnvIP",
     "LDAPFilter",
     "OAuth2Scope",
     "Session"
   ]
 },
 {
   "_id": "sunAMDelegationService",
   "name": "sunAMDelegationService",
   "displayName": "Delegation Policy Set",
   "subjects": [
     "NOT",
     "OR",
     "AuthenticatedUsers",
     "AND",
     "Identity"
   ],
   "saveIndex": null,
   "searchIndex": null,
   "entitlementCombiner": "DenyOverride",
   "resourceComparator": null,
   "attributeNames": [
   ],
   "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
   "editable": true,
   "resourceTypeUuids": [
     "20a13582-1f32-4f83-905f-f71ff4e2e00d"
   ],
   "creationDate": 1480651214933,
   "lastModifiedDate": 1480651214933,
   "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
   "description": null,
   "applicationType": "sunAMDelegationService",
   "conditions": [
   ]
 }
 ],
 "resultCount": 2,
 "pagedResultsCookie": null,
 "totalPagedResultsPolicy": "NONE",
 "totalPagedResults": -1,
 "remainingPagedResults": 0
}

Additional query strings can be specified to alter the returned results. For more information, see "Filtering, Sorting, and Paging Results".

To read an individual policy set in a realm, perform an HTTP GET to the /json{/realm}/applications endpoint, and specify the policy set 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..." \
https://openam.example.com:8443/openam/json/applications/mypolicyset
{
    "creationDate": 1431360678810,
    "lastModifiedDate": 1431360678810,
    "conditions": [
        "AuthenticateToService",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "SessionProperty",
        "AuthLevel",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType": "iPlanetAMWebAgentService",
    "subjects": [
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids": [
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "attributeNames": [ ],
    "editable": true,
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "description": "My example policy set.",
    "realm": "/",
    "name": "mypolicyset"
}

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.

To create a policy set in a realm, perform an HTTP POST to the /json{/realm}/applications endpoint, with an _action parameter set to create. Include a JSON representation of the policy set in the POST data.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: 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..." \
--data '{
    "name": "mypolicyset",
    "resourceTypeUuids": [
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "realm": "/",
    "conditions": [
        "AND",
        "OR",
        "NOT",
        "AMIdentityMembership",
        "AuthLevel",
        "AuthScheme",
        "AuthenticateToRealm",
        "AuthenticateToService",
        "IPv4",
        "IPv6",
        "LDAPFilter",
        "LEAuthLevel",
        "OAuth2Scope",
        "ResourceEnvIP",
        "Session",
        "SessionProperty",
        "SimpleTime"
    ],
    "applicationType": "iPlanetAMWebAgentService",
    "description": "My example policy set.",
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "subjects": [
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity",
        "JwtClaim"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "attributeNames": []
}' \
https://openam.example.com:8443/openam/json/applications/?_action=create
{
    "creationDate": 1431360678810,
    "lastModifiedDate": 1431360678810,
    "conditions": [
        "AuthenticateToService",
        "AuthScheme",
        "IPv6",
        "SimpleTime",
        "OAuth2Scope",
        "IPv4",
        "AuthenticateToRealm",
        "OR",
        "AMIdentityMembership",
        "LDAPFilter",
        "SessionProperty",
        "AuthLevel",
        "LEAuthLevel",
        "Session",
        "NOT",
        "AND",
        "ResourceEnvIP"
    ],
    "applicationType": "iPlanetAMWebAgentService",
    "subjects": [
        "JwtClaim",
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids": [
        "12345a67-8f0b-123c-45de-6fab78cd01e2"
    ],
    "attributeNames": [ ],
    "editable": true,
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "description": "My example policy set.",
    "realm": "/",
    "name": "mypolicyset"
}

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.

To update an individual policy set in a realm, perform an HTTP PUT to the /json{/realm}/applications endpoint, and specify the policy set name in the URL. Include a JSON representation of the updated policy set in the PUT data.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request PUT \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Content-Type: application/json" \
--data '{
    "name": "myupdatedpolicyset",
    "description": "My updated policy set - new name and fewer allowable conditions/subjects.",
    "conditions": [
        "NOT",
        "SimpleTime"
    ],
    "subjects": [
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity"
    ],
    "applicationType": "iPlanetAMWebAgentService",
    "entitlementCombiner": "DenyOverride",
    "resourceTypeUuids": [
        "76656a38-5f8e-401b-83aa-4ccb74ce88d2"
    ]
}' \
https://openam.example.com:8443/openam/json/applications/mypolicyset
{
    "creationDate": 1431362370739,
    "lastModifiedDate": 1431362390817,
    "conditions": [
        "NOT",
        "SimpleTime"
    ],
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "resourceTypeUuids": [
        "76656a38-5f8e-401b-83aa-4ccb74ce88d2"
    ],
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "applicationType": "iPlanetAMWebAgentService",
    "subjects": [
        "AuthenticatedUsers",
        "Identity",
        "NOT",
        "AND",
        "OR"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "attributeNames": [ ],
    "editable": true,
    "description": "My updated policy set - new name and fewer allowable conditions/subjects.",
    "realm": "/",
    "name": "myupdatedpolicyset"
}

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.

To delete an individual policy set in a realm, perform an HTTP DELETE to the /json{/realm}/applications endpoint, and specify the policy set 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 \
  --request DELETE \
  --header "iPlanetDirectoryPro: AQIC5..." \
  https://openam.example.com:8443/openam/json/applications/myupdatedpolicyset
{}

Use REST calls to list all the policies in a realm, or to find policies that explicitly apply to a given user or group, by using the procedures below:

To read an individual policy in a realm, perform an HTTP GET to the /json{/realm}/policies endpoint, and specify the policy 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..." \
https://openam.example.com:8443/openam/json/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.

To create a policy in a realm, perform an HTTP POST to the /json{/realm}/policies endpoint, with an _action parameter set to create. Include a JSON representation of the policy in the POST data.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: 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..." \
 --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/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.

To update an individual policy in a realm, perform an HTTP PUT to the /json{/realm}/policies endpoint, and specify the policy name in the URL. Include a JSON representation of the updated policy in the PUT data.

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 within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: 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" \
 --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/policies/mypolicy
 {
    "name": "myupdatedpolicy",
    "active": true,
    "description": "My Updated Policy.",
    "applicationName": "iPlanetAMWebAgentService",
    "actionValues": {
        "POST": true,
        "GET": true
    },
    "resources": [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=bjenson,ou=People,dc=example,dc=com",
            "uid=scarter,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-11T17:26:59.116Z",
    "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": "2015-05-11T17:25:18.632Z"
}

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.

To delete an individual policy in a realm, perform an HTTP DELETE to the /json{/realm}/policies endpoint, and specify the policy 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: AQIC5w..." \
  --request DELETE \
  https://openam.example.com:8443/openam/json/policies/myupdatedpolicy
{}

You can copy or move an individual policy by performing an HTTP POST to the /json{/realm}/policies/policyName endpoint as follows:

Specify JSON input data as follows:

The follow example copies the policy myPolicy to myNewPolicy. The output policy is placed in the myRealm realm, in the same policy set as the input policy:

$ curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "iPlanetDirectoryPro: AQIC5w..." \
  --data '{
      "to": {
          "name": "myNewPolicy"
      }
  }' \
  https://openam.example.com:8443/openam/json/myRealm/policies/myPolicy?_action=copy
{
    "name":"myNewPolicy",
    "active":true,
    "description":"",
    "applicationName":"iPlanetAMWebAgentService",
    "actionValues":{},
    "resources":['"*://*:*/*"],
    "subject":{"type":"NONE"},
    "resourceTypeUuid":"d98e59c9-766a-4934-b5de-8a28a9edc158",
    "lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com",
    "lastModifiedDate":"2015-12-19T15:22:44.861Z",
    "createdBy":"id=amadmin,ou=user,dc=example,dc=com",
    "creationDate":"2015-12-19T15:22:44.861Z"
}

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:

$ curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "iPlanetDirectoryPro: AQIC5w..." \
  --data '{
      "to": {
          "name": "myMovedPolicy",
          "realm": "/myOtherRealm",
          "resourceType: "616b3d02-7a8d-4422-b6a7-174f62afd065"
      }
  }' \
  https://openam.example.com:8443/openam/json/myRealm/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"
 }

You can also copy and move multiple policies—all the policies in a policy set—in a single operation by performing an HTTP POST to the /json{/realm}/policies endpoint as follows:

Specify JSON input data as follows:

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:

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:

$ curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "iPlanetDirectoryPro: AQIC5w..." \
  --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/myRealm/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"
}

OpenAM supports exporting policies into XACML 3.0 format. OpenAM only exports a policy set that contains policy definitions. No other types can be included in the policy set, such as sub-policy sets or rules. The policy set mapping is as follows:

The export service is accessible at the /xacml/policies endpoint using a HTTP GET request at the following endpoint for the root realm or a specific realm:

http://openam.example.com:8080/openam/xacml/policies
http://openam.example.com:8080/openam/xacml/{realm}/policies

where {realm} is the name of a specific realm
   

You can filter your XACML exports using query search filters. Note the following points about the search filters:

OpenAM supports the import of XACML 3.0-based policy sets into OpenAM policies using the REST /xacml/policies endpoint. To test an import, OpenAM provides a dry-run feature that runs an import without saving the changes to the database. The dry-run feature provides a summary of the import so that you can troubleshoot any potential mismatches prior to the actual import.

You can import a XACML policy using an HTTP POST request for the root realm or a specific realm at the following endpoints:

http://openam.example.com:8080/openam/xacml/policies
http://openam.example.com:8080/openam/xacml/{realm}/policies

where {realm} is the name of a specific realm
   

$ curl \
  --request POST \
  --header "Content-Type: application/xml" \
  --header "iPlanetDirectoryPro: AQIC5..." \
  --data @xacml-policy.xml \
  http://openam.example.com:8080/openam/xacml/{realm}/policies

To list all environment condition types, perform an HTTP GET 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..." \
 https://openam.example.com:8443/openam/json/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 "Filtering, Sorting, and Paging Results".

To read an individual environment condition type, perform an HTTP GET 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..." \
 https://openam.example.com:8443/openam/json/conditiontypes/IPv4
{
  "title" : "IPv4",
  "logical" : false,
  "config" : {
    "type" : "object",
    "properties" : {
      "startIp" : {
        "type" : "string"
      },
      "endIp" : {
        "type" : "string"
      },
      "dnsName" : {
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      }
    }
  }
}

To list all environment condition types, perform an HTTP GET 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..." \
  https://openam.example.com:8443/openam/json/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 "Filtering, Sorting, and Paging Results".

To read an individual subject condition type, perform an HTTP GET 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..." \
 https://openam.example.com:8443/openam/json/subjecttypes/Identity
{
    "title" : "Identity",
    "logical" : false,
    "config" : {
        "type" : "object",
        "properties" : {
            "subjectValues" : {
                "type" : "array",
                "items" : {
                    "type" : "string"
                }
            }
        }
    }
}

To list all subject attributes, perform an HTTP GET 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..." \
https://openam.example.com:8443/openam/json/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.

To list all decision combiners, perform an HTTP GET 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..." \
 https://openam.example.com:8443/openam/json/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 "Filtering, Sorting, and Paging Results".

To view an individual decision combiner, perform an HTTP GET on its resource.

To read an individual decision combiner, perform an HTTP GET 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..." \
 https://openam.example.com:8443/openam/json/decisioncombiners/DenyOverride
{
  "title" : "DenyOverride"
}

OpenAM exposes REST endpoints for making calls to OpenAM acting as an authorization server, as described in "Managing OAuth 2.0 Authorization" in the Administration Guide.

If a client device has a limited user interface, it can obtain an OAuth 2.0 device code and ask a user to authorize the client on a more full-featured user agent, such as an Internet browser.

OpenAM provides the /oauth2/device/code, /oauth2/device/user, and /oauth2/access_token endpoints to support the OAuth 2.0 Device Flow.

The following procedures show how to use the OAuth 2.0 device flow endpoints:

234567ABCDEFGHIJKLMNOPQRSTVWXYZabcdefghijkmnopqrstvwxyz

OpenAM provides a read-only REST endpoint for viewing a resource set registered to a particular user. The endpoint is /json{/realm}/users/user/oauth2/resourcesets/resource_set_ID, so for example https://openam.example.com:8443/openam/json/myrealm/users/demo/oauth2/resourcesets/43225628-4c5b-4206-b7cc-5164da81decd0.

To read a resource set, either the resource set owner or an administrator such as amadmin must have logged in to OpenAM (the authorization server) and have been issued an SSO token.

The OpenAM-specific OAuth 2.0 token administration endpoint lets administrators read, list, and delete OAuth 2.0 tokens. OAuth 2.0 clients can also manage their own tokens.

OpenAM exposes the token administration endpoint at /frrest/oauth2/token, such as https://openam.example.com:8443/openam/frrest/oauth2/token.

To get a token, perform an HTTP GET on /frrest/oauth2/token/token-id, as in the following example:

$ curl \
 --request POST \
 --user "myClientID:password" \
 --data "grant_type=password&username=demo&password=changeit&scope=cn" \
 https://openam.example.com:8443/openam/oauth2/access_token
 {
    "scope": "cn",
    "expires_in": 60,
    "token_type": "Bearer",
    "access_token": "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
}

$ curl \
 --request GET \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \
 https://openam.example.com:8443/openam/frrest/oauth2/token/f5fb4833-ba3d-41c8-bba4-833b49c3fe2c
 {
    "expireTime": [
        "1418818601396"
    ],
    "tokenName": [
        "access_token"
    ],
    "scope": [
        "cn"
    ],
    "grant_type": [
        "password"
    ],
    "clientID": [
        "myClientID"
    ],
    "parent": [],
    "id": [
        "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
    ],
    "tokenType": [
        "Bearer"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
        "/"
    ],
    "userName": [
        "demo"
    ]
}

To list tokens, perform an HTTP GET on /frrest/oauth2/token/?_queryId=access_token to request the list of access tokens for the current user.

The following example shows a search for the demo user's access tokens:

$ curl \
 --request GET \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcw..." \
 https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=access_token
 {
    "_rev": "1753454107",
    "tokenName": [
    "access_token"
    ],
    "expireTime": "Indefinitely",
    "scope": [
      "openid"
    ],
    "grant_type": [
      "password"
    ],
    "clientID": [
      "myOAuth2Client"
    ],
    "tokenType": [
      "Bearer"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
      "/test"
    ],
    "userName": [
      "user.4"
    ],
    "display_name": "",
    "scopes": "openid"
    },
    {
    "_rev": "1753454107",
    "tokenName": [
      "access_token"
    ],
    "expireTime": "Indefinitely",
    "scope": [
      "openid"
    ],
    "grant_type": [
      "password"
    ],
    "clientID": [
      "myOAuth2Client"
    ],
    "tokenType": [
      "Bearer"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
      "/test"
    ],
    "userName": [
      "user.4"
    ],
    "display_name": "",
    "scopes": "openid"
    }
    ],
    "resultCount": 2,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

To list a specific user's tokens, perform an HTTP GET on /ffrest/oauth2/token/?_queryId=userName=string, where string is the user, such as user.4. You must use an amadmin token with this GET method. Delegated admins are not supported here.

$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \
https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=userName=user.4
{
    "result": [
    {
    "_id": "2aaddde8-586b-4cb7-b431-eb86af57aabc",
    "_rev": "-549186065",
    "tokenName": [
      "access_token"
    ],
    "expireTime": "Indefinitely",
    "scope": [
      "openid"
    ],
    "grant_type": [
      "password"
    ],
    "authGrantId": [
      "50e9f80b-d193-4aeb-93e9-e383ea2cabd3"
    ],
    "clientID": [
      "myOAuth2Client"
    ],
    "parent": [],
    "refreshToken": [
      "5e1423a2-d2cd-40d5-8f54-5b695836cd44"
    ],
    "id": [
      "2aaddde8-586b-4cb7-b431-eb86af57aabc"
    ],
    "tokenType": [
      "Bearer"
    ],
    "auditTrackingId": [
      "6ac90d13-9cac-444b-bfbc-c7aca16713de-777"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
      "/test"
    ],
    "userName": [
      "user.4"
    ],
    "display_name": "",
    "scopes": "openid"
    },
    {
    "_id": "5e1423a2-d2cd-40d5-8f54-5b695836cd44",
    "_rev": "1171292923",
    "tokenName": [
      "refresh_token"
    ],
    "expireTime": "Oct 18, 2016 10:51 AM",
    "scope": [
      "openid"
    ],
    "grant_type": [
      "password"
    ],
    "authGrantId": [
      "50e9f80b-d193-4aeb-93e9-e383ea2cabd3"
    ],
    "clientID": [
      "myOAuth2Client"
    ],
    "authModules": [],
    "id": [
      "5e1423a2-d2cd-40d5-8f54-5b695836cd44"
    ],
    "tokenType": [
      "Bearer"
    ],
    "auditTrackingId": [
      "6ac90d13-9cac-444b-bfbc-c7aca16713de-776"
    ],
    "redirectURI": [],
    "realm": [
      "/test"
    ],
    "userName": [
      "user.4"
    ],
    "acr": [],
    "display_name": "",
    "scopes": "openid"
    },
    ],
    "resultCount": 2,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

To delete a token, perform an HTTP DELETE on /frrest/oauth2/token/token-id, as in the following example:

$ curl \
 --request POST \
 --data "grant_type=client_credentials&username=demo&password=changeit\
&client_id=myClientID&client_secret=password&scope=cn%20mail" \
 https://openam.example.com:8443/openam/oauth2/access_token
{
    "expires_in": 599,
    "token_type": "Bearer",
    "access_token": "867aaab2-61d7-4b78-9b80-4f9098034540"
}

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \
 https://openam.example.com:8443/openam/frrest/oauth2/token/867aaab2..098034540
{
    "success": "true"
}

The OAuth 2.0 administration endpoint lets OpenAM administrators and agent administrators create (that is, register) and delete OAuth 2.0 clients.

OpenAM exposes this endpoint at /frrest/oauth2/client, such as https://openam.example.com:8443/openam/frrest/oauth2/client.

To create an OAuth 2.0 client, perform an HTTP POST to /frrest/oauth2/client/?_action=create with a JSON object fully specifying the client, as in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 --data \
 '{"client_id":["testClient"],
   "realm":["/"],
   "userpassword":["secret12"],
   "com.forgerock.openam.oauth2provider.clientType":["Confidential"],
   "com.forgerock.openam.oauth2provider.redirectionURIs":
     ["www.client.com","www.example.com"],
   "com.forgerock.openam.oauth2provider.scopes":["cn","sn"],
   "com.forgerock.openam.oauth2provider.defaultScopes":["cn"],
   "com.forgerock.openam.oauth2provider.name":["My Test Client"],
   "com.forgerock.openam.oauth2provider.description":["OAuth 2.0 Client"]
  }' \
 https://openam.example.com:8443/openam/frrest/oauth2/client/?_action=create
{"success":"true"}

To delete an OAuth 2.0 client, perform an HTTP DELETE on /frrest/oauth2/client/client-id, as in the following example:

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 https://openam.example.com:8443/openam/frrest/oauth2/client/myClient
{"success":"true"}

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 https://openam.example.com:8443/openam/frrest/oauth2/client/myClient?realm=myRealm
{"success":"true"}

OpenAM exposes endpoints for discovering information about the provider configuration, and about the provider for a given end user:

For examples, see Configuring OpenAM For OpenID Connect Discovery in the Administration Guide.

OpenAM allows both static and dynamic registration of OpenID Connect client applications. For dynamic registration according to the OpenID Connect Dynamic Client Registration 1.0 specification, the endpoint is /oauth2/connect/register. See "To Register a Relying Party Dynamically" in the Administration Guide for details.

Registered clients can request authorization through OpenAM.

OpenID Connect 1.0 supports both a Basic Client Profile using the OAuth 2.0 authorization code grant, and an Implicit Client Profile using the OAuth 2.0 implicit grant. These client profiles rely on the OAuth 2.0 endpoints for authorization. Those endpoints are described in "OAuth 2.0 Client and Resource Server Endpoints".

In addition, authorized clients can access end user information through the OpenID Connect 1.0 specific endpoint /oauth2/userinfo.

For examples, see "Relying Party Examples" in the Administration Guide.

Registered clients can use OpenID Connect Session Management 1.0 to handle end user logout actions.

For an example, see "Managing OpenID Connect User Sessions" in the Administration Guide.

Clients can use an OpenID Connect 1.0 endpoint on OpenAM to quickly validate a stateless OIDC ID token and optionally retrieve any claims within the token. The endpoint is used globally and not within a realm. For information on configuring stateless OIDC tokens, see "Configuring Stateless OpenID Connect 1.0 Tokens".

The endpoint validates an OIDC ID token based on rules 1-10 in section 3.1.3.7 of the OpenID Connect Core and runs the following steps:

To invoke the endpoint, the client sends an HTTP POST request to /openam/oauth2/idtokeninfo using the following parameters in the POST body in application/x-www-form-url-encoded format or as query parameters:

For example, you can run the following command:

curl -X POST -d "id_token=$IDTOKEN" http://openam.example.com:8080/openam/oauth2/idtokeninfo
   

where $IDTOKEN is an OIDC ID token

If the ID token validates successfully, the endpoint unpacks the claims from the ID token and returns them as JSON. You can also use an optional claims parameter in the request to return those specific claims. If a claim is requested that does not exist, no error occurs; it will simply not be present in the response.

For example, you can run the following command to retrieve the claims in an OIDC ID token:

curl -i -X POST -d "id_token=$IDTOKEN" \
'http://openam.example.com:8080/openam/oauth2/idtokeninfo?claims=sub,exp,realm'
HTTP/1.1 200 OK
Date: Wed, 01 Jun 2016 07:31:39 GMT
Accept-Ranges: bytes
Server: Restlet-Framework/2.3.4
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Content-Type: application/json;charset=UTF-8
Content-Length: 50
{
    "sub": "demo",
    "exp": 1461065147,
    "realm": "/"
}

For invalid requests, the endpoint returns a 400 HTTP code with a JSON error response:

curl -i -X POST 'http://openam.example.com:8080/openam/oauth2/idtokeninfo?claims=sub,exp,realm'
HTTP/1.1 400 Bad Request
Date: Wed, 01 Jun 2016 08:32:43 GMT
Accept-Ranges: bytes
Server: Restlet-Framework/2.3.4
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Content-Type: application/json
Transfer-Encoding: chunked
Connection: close
{
    "error":"bad_request",
    "error_description":"no id_token in request"
}

OpenAM supports stateless access, refresh, and ID tokens for OpenID Connect 1.0 (OIDC). Stateless tokens allow clients to directly validate the tokens by storing session information within the token itself and bypassing storage in an external CTS data store. This feature also allows any OpenAM instance in the issuing cluster to validate an OIDC tokens without cross-talk.

For configuration procedures, see "Stateless OpenID Connect 1.0 Access and Refresh Tokens" in the Administration Guide.

OpenAM exposes an endpoint for discovering information about the UMA provider configuration.

A resource server or client can perform an HTTP GET on /uma{/realm}/.well-known/uma-configuration to retrieve a JSON object indicating the UMA configuration.

For an example, see Configuring OpenAM For UMA Discovery in the Administration Guide.

UMA uses the OAuth 2.0 Resource Set Registration standard for registration and management of resources. The endpoint is /oauth2/resource_set/. For details, see "Managing UMA Resource Sets" in the Administration Guide.

OpenAM also provides a read-only endpoint for viewing a user's resource sets, and if available policy definitions. For more information, see "OAuth 2.0 Resource Set Endpoint".

OpenAM exposes the following endpoint for managing UMA policies:

OpenAM exposes the following endpoints for managing UMA workflow and accessing protected resources:

OpenAM lets administrators create a user profile by making an HTTP POST of the JSON representation of the profile to /json/subrealm/users/?_action=create. To add a user to the Top Level Realm, you do not need to specify the realm.

The following example shows an administrator creating a new user. The only required fields are username and userpassword. If no other name is provided, the entry you make for username defaults to both the user id and the user's last name:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --data \
 '{
   "username": "bjensen",
   "userpassword": "secret12",
   "mail": "bjensen@example.com"
 }' \
 https://openam.example.com:8443/openam/json/users/?_action=create
 {
    "username": "bjensen",
    "realm": "/",
    "uid": [
        "bjensen"
    ],
    "mail": [
        "bjensen@example.com"
    ],
    "sn": [
        "bjensen"
    ],
    "cn": [
        "bjensen"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=bjensen,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "person",
        "sunIdentityServerLibertyPPService",
        "sunFederationManagerDataStore",
        "inetorgperson",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "iplanet-am-managed-person",
        "sunAMAuthAccountLockout",
        "iplanet-am-user-service",
        "top"
    ],
    "universalid": [
        "id=bjensen,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}

Alternatively, administrators can create user profiles with specific user IDs by doing an HTTP PUT of the JSON representation of the changes to /json/users/user-id, as shown in the following example:

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --data \
 '{
   "username": "janedoe",
   "userpassword": "secret12",
   "mail": "janedoe@example.com"
 }' \
 https://openam.example.com:8443/openam/json/users/janedoe
 {
    "username": "janedoe",
    "realm": "/",
    "uid": [
        "janedoe"
    ],
    "mail": [
        "janedoe@example.com"
    ],
    "sn": [
        "janedoe"
    ],
    "cn": [
        "janedoe"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=janedoe,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "inetorgperson",
        "sunFederationManagerDataStore",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
    ],
    "universalid": [
        "id=janedoe,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}

As shown in the examples, OpenAM returns the JSON representation of the profile on successful creation. On failure, OpenAM returns a JSON representation of the error including the HTTP status code. For example, version 2.0 of the CREST /json/users, /json/groups, and /json/agents endpoints return 403 if the user making the request is not authorized to do so.

The same HTTP POST and PUT mechanisms also work for other objects such as policy agent profiles and groups:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --data \
 '{
    "username":"myAgent",
    "com.sun.identity.agents.config.fqdn.default":
      ["www.example.com"],
    "com.sun.identity.agents.config.repository.location":
      ["centralized"],
    "agenttype":["WebAgent"],
    "serverurl":["https://openam.example.com:8443/openam/"],
    "agenturl":["http://www.example.com:80/"],
    "userpassword":["password"],
    "com.sun.identity.agents.config.login.url":
      ["[0]=https://openam.example.com:8443/openam/UI/Login"],
    "com.sun.identity.agents.config.logout.url":
      ["[0]=https://openam.example.com:8443/openam/UI/Logout"],
    "sunidentityserverdevicestatus":["Active"]
 }' \
 https://openam.example.com:8443/openam/json/agents/?_action=create
 {
    "username": "myAgent",
    "realm": "/",
    "com.sun.identity.agents.config.fqdn.default": [
        "www.example.com"
    ],
    "com.sun.identity.agents.config.repository.location": [
        "centralized"
    ],
    "AgentType": [
        "WebAgent"
    ],
    "com.sun.identity.agents.config.login.url": [
        "[0]=https://openam.example.com:8443/openam/UI/Login"
    ],
    "com.sun.identity.agents.config.login.url":
        ["[0]=https://openam.example.com:8443/openam/UI/Login"
    ],
    "com.sun.identity.agents.config.logout.url":
        ["[0]=https://openam.example.com:8443/openam/UI/Logout"
    ],
    "sunIdentityServerDeviceStatus": [
        "Active"
    ]
}

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --data '{
   "username":"newGroup",
   "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]
 }' \
 https://openam.example.com:8443/openam/json/groups?_action=create
 {
    "username": "newGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "newGroup"
    ],
    "dn": [
        "cn=newGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=newGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}

$ curl \
 --request PUT \
 --header "If-None-Match: *" \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{
   "username":"anotherGroup",
   "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]
 }' \
 https://openam.example.com:8443/openam/json/groups/anotherGroup
 {
    "username": "anotherGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "anotherGroup"
    ],
    "dn": [
        "cn=anotherGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=anotherGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}

OpenAM lets users and administrators read profiles by requesting an HTTP GET on /json/subrealm/users/user-id. This allows users and administrators to verify user data, status, and directory. If users or administrators see missing or incorrect information, they can write down the correct information and add it using "Updating Identities". To read a profile on the Top Level Realm, you do not need to specify the realm.

Users can review the data associated with their own accounts, and administrators can also read other user's profiles.

The following example shows an administrator accessing user data belonging to demo:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/demo
{
    "username": "demo",
    "realm": "dc=openam,dc=forgerock,dc=org",
    "uid": [
        "demo"
    ],
    "sn": [
        "demo"
    ],
    "cn": [
        "demo"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "inetorgperson",
        "sunFederationManagerDataStore",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
    ],
    "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}

Use the _fields query string parameter to restrict the list of attributes returned. This parameter takes a comma-separated list of JSON object fields to include in the result:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/demo?_fields=username,uid
{"username":"demo","uid":["demo"]}

As shown in the examples, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

Using HTTP GET to read also works for other objects such as agent profiles and groups:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/agents/myAgent
{
    "username": "myAgent",
    "realm": "/",
    "com.sun.identity.agents.config.fqdn.default": [
        "www.example.com"
    ],
    "com.sun.identity.agents.config.repository.location": [
        "centralized"
    ],
    "AgentType": [
        "WebAgent"
    ],
    "com.sun.identity.agents.config.login.url": [
        "[0]=https://openam.example.com:8443/openam/UI/Login"
    ],
    "com.sun.identity.agents.config.login.url":
    [
        "[0]=https://openam.example.com:8443/openam/UI/Login"
    ],
    "com.sun.identity.agents.config.logout.url":
    [
        "[0]=https://openam.example.com:8443/openam/UI/Logout"
    ],
    "sunIdentityServerDeviceStatus": [
        "Active"
    ]
}

The _prettyPrint query string parameter can make the resulting JSON easier to read when you are viewing the resulting JSON directly:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/groups/newGroup?_prettyPrint=true
{
    "username": "newGroup",
    "realm": "dc=openam,dc=forgerock,dc=org",
    "uniquemember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "newGroup"
    ],
    "dn": [
        "cn=newGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=newGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}

OpenAM lets users update their own profiles, and lets administrators update other users' profiles. To update an identity do an HTTP PUT of the JSON representation of the changes to /json/subrealm/users/user-id. To update a profile on the Top Level Realm, you do not need to specify the realm.

The following example shows how users can update their own profiles:

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{ "mail": "demo@example.com" }' \
 https://openam.example.com:8443/openam/json/users/demo
 {
    "username": "demo",
    "realm": "/",
    "uid": [
        "demo"
    ],
    "mail": [
        "demo@example.com"
    ],
    "sn": [
        "demo"
    ],
    "cn": [
        "demo"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "person",
        "sunIdentityServerLibertyPPService",
        "sunFederationManagerDataStore",
        "inetorgperson",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "iplanet-am-managed-person",
        "sunAMAuthAccountLockout",
        "iplanet-am-user-service",
        "top"
    ],
    "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}

As shown in the example, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

You can use HTTP PUT to update other objects as well, such as policy agent profiles and groups.

The following example updates a web policy agent profile:

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{
      "sunIdentityServerDeviceStatus" : [ "Inactive" ]
 }' \
 https://openam.example.com:8443/openam/json/agents/myAgent?_prettyPrint=true
 {
     "username": "myAgent",
     "realm": "/",
     "com.sun.identity.agents.config.fqdn.default": [
         "www.example.com"
     ],
     "com.sun.identity.agents.config.repository.location": [
         "centralized"
     ],
     "AgentType": [
         "WebAgent"
     ],
     "com.sun.identity.agents.config.login.url": [
         "[0]=https://openam.example.com:8443/openam/UI/Login"
     ],
     "com.sun.identity.agents.config.login.url":
     [
         "[0]=https://openam.example.com:8443/openam/UI/Login"
     ],
     "com.sun.identity.agents.config.logout.url":
     [
         "[0]=https://openam.example.com:8443/openam/UI/Logout"
     ],
     "sunIdentityServerDeviceStatus": [
         "Inactive"
     ]
 }

Notice in the following example that updates newGroup the object class value is not included in the JSON sent to OpenAM:

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{
    "uniquemember":[
        "uid=newUser,ou=people,dc=openam,dc=forgerock,dc=org",
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ]
 }' \
 https://openam.example.com:8443/openam/json/groups/newGroup
{
    "name": "newGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=newUser,ou=people,dc=openam,dc=forgerock,dc=org",
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "newGroup"
    ],
    "dn": [
        "cn=newGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=newGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}

OpenAM lets administrators delete a user profile by making an HTTP DELETE call to /json/subrealm/users/user-id. To delete a user from the Top Level Realm, you do not need to specify the realm.

The following example removes a user from the top level realm. Only administrators should delete users. The user id is the only field required to delete a user:

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/bjensen
{"success":"true"}

On success, OpenAM returns a JSON object indicating success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

You can use this same logic for other resources such as performing an HTTP DELETE of an agent profile or of a group:

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/agents/myOAuth2ClientAgent
{"success":"true"}

$ curl \
 --request DELETE \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/groups/newGroup
{"success":"true"}

OpenAM lets administrators list identities by making an HTTP GET call to /json/subrealm/users/?_queryId=*. To query the Top Level Realm, you do not need to specify the realm:

$ curl \
--header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
"https://openam.example.com:8443/openam/json/users?_queryId=*"
{
  "result": [
    {
      "username": "amAdmin",
      "realm": "dc=openam,dc=forgerock,dc=org",
      "sunIdentityMSISDNNumber": [],
      "mail": [],
      "sn": [
        "amAdmin"
      ],
      "givenName": [
        "amAdmin"
      ],
      "universalid": [
        "id=amAdmin,ou=user,dc=openam,dc=forgerock,dc=org"
      ],
      "cn": [
        "amAdmin"
      ],
      "iplanet-am-user-success-url": [],
      "telephoneNumber": [],
      "roles": [
        "ui-global-admin",
        "ui-realm-admin"
      ],
      "iplanet-am-user-failure-url": [],
      "inetuserstatus": [
        "Active"
      ],
      "postalAddress": [],
      "dn": [
        "uid=amAdmin,ou=people,dc=openam,dc=forgerock,dc=org"
      ],
      "employeeNumber": [],
      "iplanet-am-user-alias-list": []
    },
    {
      "username": "demo",
      "realm": "dc=openam,dc=forgerock,dc=org",
      "uid": [
        "demo"
      ],
      "createTimestamp": [
        "20160108155628Z"
      ],
      "inetUserStatus": [
        "Active"
      ],
      "mail": [
        "demo.user@example.com"
      ],
      "sn": [
        "demo"
      ],
      "cn": [
        "demo"
      ],
      "objectClass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "sunFederationManagerDataStore",
        "inetorgperson",
        "oathDeviceProfilesContainer",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "sunFMSAML2NameIdentifier",
        "organizationalperson",
        "inetuser",
        "kbaInfoContainer",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
      ],
      "kbaInfo": [
        {
          "questionId": "2",
          "answer": {
            "$crypto": {
              "value": {
                "algorithm": "SHA-256",
                "data": "VXGtsnjJMC...MQJ/goU5hkfF"
              },
              "type": "salted-hash"
            }
          }
        },
        {
          "questionId": "1",
          "answer": {
            "$crypto": {
              "value": {
                "algorithm": "SHA-256",
                "data": "cfYYzi9U...rVfFl0Tdw0iX"
              },
              "type": "salted-hash"
            }
          }
        }
      ],
      "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
      ],
      "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
      ],
      "modifyTimestamp": [
        "20160113010610Z"
      ]
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The users endpoint also supports the _queryFilter parameter to alter the returned results. For more information, see "Filtering, Sorting, and Paging Results".

The _queryId=* parameter also works for other types of objects, such as agent profiles and groups:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 "https://openam.example.com:8443/openam/json/agents?_queryId=*"
{
  "result" : [ "wsp", "wsc", "agentAuth", "SecurityTokenService" ],
  "resultCount" : 4,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 "https://openam.example.com:8443/openam/json/groups?_queryId=*"
{
  "result" : [ "newGroup", "anotherGroup" ],
  "resultCount" : 2,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}

As the result lists include all objects, this capability to list identity names is mainly useful in testing.

As shown in the examples, OpenAM returns the JSON representation of the resource list if successful. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

If you only have access to the iPlanetDirectoryPro session cookie, you can retrieve the user ID by performing an HTTP POST operation on the /json/users endpoint using the idFromSession action:

$ curl \
 --verbose \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5wM2LY4SfczUFNs-TJwFrCVAKgR0NulIAyNaIkQmjis.*AAJTSQACMDEA
 AlNLABQtNTQ3NDE2Njc5ODk4MjYzMzA2MQ..*" \
 http://openam.example.com:8080/openam/json/users?_action=idFromSession

{
  "id":"demo",
  "realm":"/",
  "dn":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
  "successURL":"/openam/console",
  "fullLoginURL":null
}

Users other than the top-level administrator can change their own passwords with an HTTP POST to /json/subrealm/users/username?_action=changePassword including the new password as the value of userpassword in the request data.

Users must provide the current password, which is set in the request as the value of the currentpassword.

For cases where users have forgotten their password, see "Retrieving Forgotten Usernames" instead.

The following example shows a successful request to change the demo user's password to password:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \
 --data '{
     "currentpassword":"changeit",
     "userpassword":"password"
 }' \
 https://openam.example.com:8443/openam/json/users/demo?_action=changePassword
{}

On success, the response is an empty JSON object {} as shown in the example.

On failure, OpenAM returns a JSON representation of the error including the HTTP status code. See also "REST Status Codes" for more information.

Administrators can change non-administrative users' passwords with an HTTP PUT to /json/subrealm/users/username including the new password as the value of userpassword in the request data.

Unlike users, administrators do not provide users' current passwords when changing passwords.

The following example shows a successful request by an administrator to change the demo user's password to cangetin:

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \
 --header "Content-Type: application/json" \
 --data '{
     "userpassword":"cangetin"
 }' \
 https://openam.example.com:8443/openam/json/users/demo
 {
    "username":"demo",
    "realm":"/",
    "uid":[
        "demo"
    ],
    "universalid":[
        "id=demo,ou=user,dc=example,dc=com"
    ],
    "objectClass":[
        "iplanet-am-managed-person",
        "inetuser","sunFederationManagerDataStore",
        "sunFMSAML2NameIdentifier",
        "devicePrintProfilesContainer",
        "inetorgperson",
        "sunIdentityServerLibertyPPService",
        "iPlanetPreferences",
        "iplanet-am-user-service",
        "forgerock-am-dashboard-service",
        "organizationalperson",
        "top",
        "sunAMAuthAccountLockout",
        "person",
        "oathDeviceProfilesContainer",
        "iplanet-am-auth-configuration-service"
    ],
    "inetUserStatus":[
        "Active"
    ],
    "dn":[
        "uid=demo,ou=people,dc=example,dc=com"
    ],
    "sn":[
        "demo"
    ],
    "cn":[
        "demo"
    ],
    "modifyTimestamp":[
        "20151006213634Z"
    ],
    "createTimestamp":[
        "20151005134244Z"
    ]
}

As shown in the example, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code. See also "REST Status Codes" for more information.

Realms have a number of fields entered with the default loading. The following table provides information on what the default realm settings are, and whether they can be updated, added, or deleted when updating a realm.

OpenAM lets administrators create a realm by making an HTTP POST of the JSON representation of the profile to /json/realms/?_action=create.

You can create realms using an HTTP POST of the JSON representation of the profile to /json/realms/?_action=create, as shown in the following example. The only required data field is realm:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --data '{ "realm": "myRealm" }' \
 https://openam.example.com:8443/openam/json/realms/?_action=create
{"realmCreated":"/myRealm"}

You can also set the sunOrganizationAliases parameter, but it can only be assigned to one realm (usually the top level realm). Before setting this parameter, make sure it is not already assigned elsewhere. If you remove it from another realm, you will lose your configuration.

Alternatively, administrators can create realms by the specific realm name using the HTTP PUT of the JSON representation of the changes to /json/realms/realm-id, as shown in the following example:

$ curl \
 --request PUT \
 --header "If-None-Match: *" \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{ }' \
 https://openam.example.com:8443/openam/json/realms/myRealm

 {
  "realmCreated": "/myRealm"
 }

OpenAM returns an HTTP 201 Created status code, and the JSON representation of the realm on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code. For example, if the If-None-Match header with a value of * is absent, an HTTP 404 Not Found status code is returned.

OpenAM lets administrators read realms by requesting an HTTP GET on /json/realms/realm-id. This allows administrators to review all active realm services for the realm, like policy configuration and modules. If users or administrators see missing information (such as Active status) or incorrect information, they can write down the correct information and add it using "Updating Realms".

The following example shows an administrator receiving information about a realm called myRealm:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/myRealm
{
    "serviceNames":[
      "sunAMAuthHOTPService",
      "iPlanetAMAuthConfiguration",
      "sunAMAuthFederationService",
      "sunIdentityRepositoryService",
      "iPlanetAMPolicyConfigService",
      "iPlanetAMAuthService",
      "iPlanetAMAuthLDAPService",
      "sunAMAuthDataStoreService",
      "sunAMAuthSAEService",
      "sunAMDelegationService",
      "sunAMAuthWSSAuthModuleService",
      "iPlanetAMAuthOATHService"
    ]
}

As shown in the example, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

To read the top-level realm, use toplevelrealm with the realms endpoint:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/toplevelrealm
{
      "serviceNames" : [
       "sunAMAuthFederationService",
       "sunEntitlementIndexes",
       "iPlanetAMAuthService",
       "sunAMAuthDataStoreService",
       "sunAMAuthWSSAuthModuleService",
       "sunAMDelegationService",
       "iPlanetAMAuthOATHService",
       "iPlanetAMAuthConfiguration",
       "sunAMAuthHOTPService",
       "sunIdentityRepositoryService",
       "iPlanetAMPolicyConfigService",
       "iPlanetAMAuthLDAPService",
       "sunEntitlementService",
       "iPlanetAMPolicyService",
       "sunAMAuthSAEService",
       "AgentService" ]
}

If the realm you want to read is not an immediate subrealm of the top-level realm, specify its parent realm to the left of realms in the URL, and specify the realm's final qualifier to the right of realms. For example, to read the /myRealm/myRealmsChildRealm realm:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/myRealm/realms/myRealmsChildRealm
{
      "serviceNames" : [
       "sunAMAuthHOTPService",
       "iPlanetAMAuthConfiguration",
       "sunAMAuthFederationService",
       "sunIdentityRepositoryService",
       "iPlanetAMPolicyConfigService",
       "iPlanetAMAuthService",
       "iPlanetAMAuthLDAPService",
       "sunAMAuthDataStoreService",
       "sunAMAuthSAEService",
       "sunAMDelegationService",
       "sunAMAuthWSSAuthModuleService",
       "iPlanetAMAuthOATHService"
      ]
}

To list a realm and its subrealms, perform an HTTP GET on the endpoint, set the _queryFilter query string parameter as in the following example, which lists the top-level realm and all of its subrealms:

 $ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/realms?_queryFilter=true
 {
     "result" : [ "/", "/myRealm", "/myRealm/myRealmsChildRealm" ],
     "resultCount" : 3,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : -1
 }

You can start listing realms from below the top-level realm by placing the starting realm name in the URL. The following example lists the realm myRealm and all of its subrealms:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/myRealm/realms?_queryFilter=true
 {
     "result" : [ "/myRealm", "/myRealm/myRealmsChildRealm" ],
     "resultCount" : 2,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : -1
 }

OpenAM lets administrators update realms. To update a realm, do an HTTP PUT of the JSON representation of the changes to /json/realms/realm-id.

The following example shows how to update a realm called myRealm. The example command sets the realm's status to Inactive:

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{ "sunOrganizationStatus": "Inactive" }' \
 https://openam.example.com:8443/openam/json/realms/myRealm

OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

OpenAM lets administrators delete a realm by making an HTTP DELETE call to /json/realms/realm-id.

The following example deletes a realm called myRealm. The top level realm cannot be deleted. Only administrators should delete realms. The name of the realm is the only field required to delete the realm.

Make sure that you do not have any information you need within a realm before deleting it. Once a realm is deleted, the only way to restore it is to return to a backed up deployment of OpenAM:

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/myRealm
{"success":"true"}

On success, OpenAM returns a JSON object indicating success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

If the realm you want to delete is not an immediate subrealm of the top-level realm, specify its parent realm to the left of realms in the URL, and specify the realm's final qualifier to the right of realms. For example, to delete the /myRealm/myRealmsChildRealm realm:

 $ curl \
 --request DELETE
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/myRealm/realms/myRealmsChildRealm
 { "success":"true" }