OpenAM 13 > Developer's Guide (2024)

2.1.1.About the RESTful APIs

OpenAM provides versions for the following aspects of the REST API.

resource

Any changes to the structure or syntax of a returned response will incur a resource version change. For example changing errorMessage to message in a JSON response.

protocol

Any changes to the methods used to make REST API calls will incur a protocol version change. For example changing _action to $action in the required parameters of an API feature.

The REST API version numbers supported in OpenAM 13 are as follows:

The OpenAM Release Notes section, Chapter4, "Changes and Deprecated Functionality" in the Release Notes describes the differences between API versions.

You can specify which version of the REST API to use by adding an Accept-API-Version header to the request, as in the following example, which is requesting resource version 2.0 and protocol version 1.0:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ https://openam.example.com:8443/openam/json/authenticate

You can configure the default behavior OpenAM will take when a REST call does not specify explicit version information. For more information, see Chapter20, "Configuring REST APIs" in the Administration Guide.

OpenAM provides REST API version messages in the JSON response to a REST API call. You can also configure OpenAM to return version messages in the response headers. See Chapter20, "Configuring REST APIs" in the Administration Guide.

Messages include:

The resource and protocol version used to service a REST API call are returned in the Content-API-Version header, as shown below:

$ curl \ -i \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ https://openam.example.com:8443/openam/json/authenticateHTTP/1.1 200 OKContent-API-Version: protocol=1.0,resource=2.0Server: Restlet-Framework/2.1.7Content-Type: application/json;charset=UTF-8{ "tokenId":"AQIC5wM...TU3OQ*", "successUrl":"/openam/console"}

If the default REST API version behavior is set to None, and a REST API call does not include the Accept-API-Version header, or does not specify a resource version, then a 400 Bad Request status code is returned, as shown below:

$ curl \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=1.0" \ https://openam.example.com:8443/openam/json/serverinfo/*{ "code":400, "reason":"Bad Request", "message":"No requested version specified and behavior set to NONE."}

If a REST API call does include the Accept-API-Version header, but the specified resource or protocol version does not exist in OpenAM, then a 404 Not Found status code is returned, as shown below:

$ curl \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=1.0, resource=999.0" \ https://openam.example.com:8443/openam/json/serverinfo/*{ "code":404, "reason":"Not Found", "message":"Accept-API-Version: Requested version \"999.0\" does not match any routes."}

DNS Alias

When making a REST API call, the DNS alias of a realm can be specified in the subdomain and domain name components of the REST endpoint.

To list all users in the top-level realm use the DNS alias of the OpenAM instance, for example the REST endpoint would be:

https://openam.example.com:8443/openam/json/users?_queryId=*

To list all users in a realm with DNS alias suppliers.example.com the REST endpoint would be:

https://suppliers.example.com:8443/openam/json/users?_queryId=*

Path

When making a REST API call, the realm, or realm alias, can be specified in the path component of the REST endpoint.

To authenticate a user in the top-level realm the REST endpoint would be:

https://openam.example.com:8443/openam/json/authenticate

To authenticate a user in a realm named customers the REST endpoint would be:

https://openam.example.com:8443/openam/json/customers/authenticate

Subrealms are supported and should be separated with a forward slash (/).

For example, to authenticate to a subrealm named europe of a realm named partners, the REST endpoint would be:

https://openam.example.com:8443/openam/json/partners/europe/authenticate

Query Parameter

When making a REST API call the realm, or realm alias, can be specified as the value of a query parameter named realm.

To list the groups in the top-level realm the REST endpoint would be:

https://openam.example.com:8443/openam/json/groups?_queryId=*

To list the groups in a realm named partners the REST endpoint would be:

https://openam.example.com:8443/openam/json/groups?realm=/partners&_queryId=*

Important

When working with a named subrealm of the top-level realm a forward slash preceeding the realm name is required. You should not use a forward slash when using a realm alias.

Subrealms are supported and should be separated with a forward slash (/).

To authenticate a user in a subrealm named europe of a realm named partners the REST endpoint would be:

https://openam.example.com:8443/openam/json/authenticate?realm=/partners/europe

1. If realms are specified using both the DNS alias and path methods, they are concatenated together.

   For example, the following REST endpoint returns users in a subrealm named europe of a realm with DNS alias suppliers.

   https://suppliers.example.com:8443/openam/json/europe/users?_queryId=*

2. If realms are specified using the realm query parameter, they override anything specified in either the DNS alias or path method.

   For example, the following REST endpoint returns users in a subrealm of the customers realm, named asia.

   https://suppliers.example.com:8443/openam/json/europe/users?realm=/customers/asia&_queryId=*

Tip

When authentication depends on the client IP address, and OpenAM lies behind a load balancer or proxy layer, configure the load balancer or proxy to send the address by using the X-Forwarded-For header, and configure OpenAM to consume and forward the header as necessary. For details, see Section4.4, "Handling HTTP Request Headers" in the Installation Guide.

• If stateless sessions are not enabled, the tokenId is an OpenAM SSO token.

• If stateless sessions are enabled, the tokenId is an OpenAM SSO token that includes an encoded OpenAM session.

Tip

 $ curl \ --request POST \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ --header "Authorization: Basic ZGVtbzpjaGFuZ2VpdA==" \ --header "Content-Type: application/json" \ --data "{}" \ https://openam.example.com:8443/openam/json/authenticate { "tokenId": "AQIC5w...NTcy*", "successUrl": "/openam/console" }

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{ "authId": "...jwt-value...", "template": "", "stage": "DataStore1", "callbacks": [ { "type": "NameCallback", "output": [ { "name": "prompt", "value": " User Name: " } ], "input": [ { "name": "IDToken1", "value": "demo" } ] }, { "type": "PasswordCallback", "output": [ { "name": "prompt", "value": " Password: " } ], "input": [ { "name": "IDToken2", "value": "changeit" } ] } ] }' \ https://openam.example.com:8443/openam/json/authenticate{ "tokenId": "AQIC5wM2...U3MTE4NA..*", "successUrl": "/openam/console" }

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{ "authId": "...jwt-value...", "template": "", "stage": "DataStore1", "callbacks": [ { "type": "NameCallback", "output": [ { "name": "prompt", "value": " User Name: " } ], "input": [ { "name": "IDToken1", "value": "demo" } ] }, { "type": "PasswordCallback", "output": [ { "name": "prompt", "value": " Password: " } ], "input": [ { "name": "IDToken2", "value": "changeit" } ] } ] }' \ https://openam.example.com:8443/openam/json/authenticate?noSession=true{ "message": "Authentication Successful", "successUrl": "/openam/console" }

• Using the realm in the URI to the endpoint (preferred method):

  https://openam.example.com:8443/openam/json/myRealm/authenticate

• Using the realm query string parameter:

  https://openam.example.com:8443/openam/json/authenticate?realm=myRealm

You can use the authIndexType and authIndexValue query string parameters as a pair to provide additional information about how you are authenticating. The authIndexType can be one of the following types:

composite

Set the value to a composite advice string.

level

Set the value to the authentication level.

module

Set the value to the name of an authentication module.

resource

Set the value to a URL protected by an OpenAM policy.

role

Set the value to an OpenAM role.

service

Set the value to the name of an authentication chain.

user

Set the value to an OpenAM user ID.

OpenAM uses the following callback types depending on the authentication module in use:

• ChoiceCallback: Used to display a list of choices and retrieve the selected choice.

• ConfirmationCallback: Used to ask for a confirmation such as Yes, No, or Cancel and retrieve the selection.

• HiddenValueCallback: Used to return form values that are not visually rendered to the end user.

• HttpCallback: Used for HTTP handshake negotiations.

• LanguageCallback: Used to retrieve the locale for localizing text presented to the end user.

• NameCallback: Used to retrieve a name string.

• PasswordCallback: Used to retrieve a password value.

• RedirectCallback: Used to redirect the client user-agent.

• ScriptTextOutputCallback: Used to insert a script into the page presented to the end user. The script can, for example, collect data about the user's environment.

• TextInputCallback: Used to retrieve text input from the end user.

• TextOutputCallback: Used to display a message to the end user.

• X509CertificateCallback: Used to retrieve the content of an x.509 certificate.

• First, call the /json/authenticate endpoint to log a user in to OpenAM. This REST API call returns a tokenID value, which is used in subsequent REST API calls to identify the user:

  $ curl \ --request POST \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ --header "Content-Type: application/json" \ --data "{}" \ https://openam.example.com:8443/openam/json/authenticate { "tokenId": "AQIC5w...NTcy*", "successUrl": "/openam/console" }

  The returned tokenID is known as a session token (also referred to as an SSO token). REST API calls made after successful authentication to OpenAM must present the session token in the HTTP header as proof of authentication.

• Next, call one or more additional REST APIs on behalf of the logged-in user. Each REST API call passes the user's tokenID back to OpenAM in the HTTP header as proof of previous authentication.

  The following is a partial example of a curl command that inserts the token ID returned from a prior successful OpenAM authentication attempt into the HTTP header:

  $ curl \ --request POST \ --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \ --header "Content-Type: application/json" \ --data '{ ...

  Observe that the session token is inserted into a header field named iPlanetDirectoryPro. This header field name must correspond to the name of the OpenAM session cookie—by default, iPlanetDirectoryPro. You can find the cookie name by navigating to Configuration > Servers and Sites > Server Name > Security and locating the Cookie Name field in the OpenAM console.

  Once a user has authenticated, it is not necessary to insert login credentials in the HTTP header in subsequent REST API calls. Note the absence of X-OpenAM-Username and X-OpenAM-Password headers in the preceding example.

  Users are required to have appropriate privileges in order to access OpenAM functionality using the REST API. For example, users who lack administrative privileges cannot create OpenAM realms. For more information on the OpenAM privilege model, see Section4.1, "Managing Realms" in the Administration Guide.

• Finally, call the REST API to log the user out of OpenAM as described in . As with other REST API calls made after a user has authenticated, the REST API call to log out of OpenAM requires the user's tokenID in the HTTP header.

The query string parameters for manipulating returned results are:

_queryFilter

The _queryFilter parameter can take true to return every result, false to return no results, or a filter of the following form to match field values: field operator value where field represents the field name, operator is the operator code, value is the value to match, and the entire filter is URL-encoded.

Note

Supported fields and operator codes vary depending on the endpoint.

The operators codes are as follows:

• co: contains

• eq: equals

  Used for matching strings, and supports regular expression pattern matching.

• ge: greater than or equal to

• gt: greater than

• le: less than or equal to

• lt: less than

• pr: field exists, field is present

  Note

  Do not set a value when using this operator.

• sw: starts with

Filters can be composed of multiple expressions by a using boolean operator AND, OR, or ! (NOT) and by using parentheses, (expression) to group expressions.

Regular expressions are implemented for some operators, so you can create a filter that includes or excludes certain records.

You must URL-encode the filter expression in _queryFilter=filter.

The following example returns resource types with a name that contains Service and also has a pattern that starts with http:

$ curl \--header "iPlanetDirectoryPro: AQIC5..." \--get \--data-urlencode \'_queryFilter=name co "Service" and patterns sw "http"' \https://openam.example.com:8443/openam/json/resourcetypes

_fields

You can use _fields=field-name[,field-name...] to limit the fields returned in the output.

The following example returns the name and creationDate of all policies in the top level realm:

$ curl \--header "iPlanetDirectoryPro: AQIC5..." \--get \--data-urlencode '_queryFilter=true' \--data-urlencode '_fields=name,creationDate' \https://openam.example.com:8443/openam/json/policies

_prettyPrint

You can use the query string parameters _prettyPrint=true to make the output easier to read.

_pageSize

You can use _pageSize=integer to limit the number of results returned.

_pagedResultsOffset

You can use _pagedResultsOffset=integer to return results starting at a specified result when using paged results.

_sortKeys

You can use _sortKeys=[+-]field-name[,field-name...] to sort the results returned, where field-name represents a field in the returned JSON. Optionally use the + prefix to sort in ascending order (the default), or - to sort in descending order.

The following example returns all applications in the top level realm, sorted in descending creationDate order:

$ curl \--header "iPlanetDirectoryPro: AQIC5..." \--get \--data-urlencode '_queryFilter=true' \--data-urlencode '_sortKeys=-creationDate' \https://openam.example.com:8443/openam/json/applications

To check over REST whether a session token is valid, perform an HTTP POST to the resource URL, /json/sessions/tokenId, using the validate action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ http://openam.example.com:8080/openam/json/sessions/AQIC5...?_action=validate{"valid":true,"uid":"demo","realm":"/myRealm"} 

An invalid session token returns only information about the validity:

$ curl \ --request POST \ --header "Content-Type: application/json" \ http://openam.example.com:8080/openam/json/sessions/AQIC5...?_action=validate{"valid":false} 

Validating a session token has the tangential effect of resetting the idle timeout for a stateful session. If session failover is enabled in your deployment, validating session tokens can trigger write operations to the Core Token Service token store. See Section2.1.1.8.2, "Session Information" for information about how to validate a session token without resetting the idle timeout, thereby avoiding the overhead of writes to the token store.

Note that OpenAM does not reset the idle timeout for a stateless session.

You can use REST API calls to:

For these REST endpoints, specify two token IDs. Provide the token ID for the current authenticated user as the value of a header whose name is the name of the SSO token cookie, by default iPlanetDirectoryPro. Specify the token ID you want information about as the tokenId query string parameter of the REST URL. In the examples in this section, AQIC5w...NTcy* is the token ID for the current authenticated user, while BXCCq...NX*1* is the token being queried.

To determine whether a session is active, perform an HTTP POST to the resource URL, /json/sessions/, using the isActive action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=isActive&tokenId=BXCCq...NX*1* {"active":true}

To check the maximum remaining time (in seconds) of a session, perform an HTTP POST to the resource URL, /json/sessions/, using the getTimeLeft action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=getTimeLeft&tokenId=BXCCq...NX*1* {"maxtime":7022}

To check the time (in minutes) configured for sessions, perform an HTTP POST to the resource URL, /json/sessions/, using the getMaxSessionTime action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=getMaxSessionTime {"maxsessiontime":120}

To check the idle time (in minutes) configured for sessions, perform an HTTP POST to the resource URL, /json/sessions/, using the getMaxIdle action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=getMaxIdle {"maxidletime":30}

To check the amount of time (in seconds) that a stateful session has been idle, perform an HTTP POST to the resource URL, /json/sessions/, using the getIdle action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=getIdle&tokenId=BXCCq...NX*1* {"idletime":355}

Because OpenAM does not monitor idle time for stateless sessions, do not use the tokenId of a stateless session when using the getIdle action.

To reset a stateful session's idle time, perform an HTTP POST to the resource URL, /json/sessions/, using the isActive action with the refresh=true option as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=isActive&refresh=true&tokenId=BXCCq...NX*1* {"active":true}

REST API calls to retrieve session information do not reset a stateful session's idle time if you specify the refresh=false parameter, which is the default.

If you specify the refresh=true parameter, OpenAM resets the idle time for stateful sessions. If session failover is enabled in your deployment, resetting a stateful session's idle time can trigger write operations to the Core Token Service token store. Therefore, to avoid the overhead of writes to the token store, be careful to use the refresh=true parameter only if you want to reset a stateful session's idle time.

Because OpenAM does not monitor idle time for stateless sessions, do not use the tokenId of a stateless session when refreshing a session's idle time.

OpenAM lets you set, read, and delete properties on users' sessions using REST API calls.

Before you can perform operations on session properties using the REST API, you must first define the properties you want to set in the Session Property Whitelist Service configuration. For information on whitelisting session properties, see Section1.4.19, "Session Property Whitelist" in the Reference.

You can use REST API calls for the following purposes:

Session state affects the ability to set and delete properties as follows:

Differentiate the user who performs the operation on session properties from the session affected by the operation as follows:

The following examples assume that you configured a property named LoginLocation in the Session Property Whitelist Service configuration.

To retrieve the names of the properties you can get or set, perform an an HTTP POST to the resource URL, /json/sessions/, using the getPropertyNames action as shown in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ http://openam.example.com:8080/openam/json/sessions/?_action=getPropertyNames {"properties":["LoginLocation"]}

To set the value of a session property, perform an HTTP POST to the resource URL, /json/sessions/, using the setProperty action. Because no tokenId parameter is present in the REST API call, the session affected by the operation is the session specified in the iPlanetDirectoryPro header:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ --data '{"LoginLocation":"40.748440, -73.984559"}' \ http://openam.example.com:8080/openam/json/sessions/?_action=setProperty {"success":true}

You can set multiple properties in a single REST API call by specifying a set of fields and their values in the JSON data. For example, --data '{"property1":"value1", "property2":"value2"}'.

To set the value of a session property on another user's session, specify the session token of the user performing the setProperty action in the iPlanetDirectoryPro, and specify the session token to be modified as the value of the tokenId parameter:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ --data '{"LoginLocation":"40.748440, -73.984559"}' \ http://openam.example.com:8080/openam/json/sessions/?_action=setProperty&tokenId=BXCCq...NX*1* {"success":true}

If the user attempting to modify the session does not have sufficient access privileges, the preceding example results in a 403 Forbidden error.

To read the value of a session property, perform an HTTP POST to the resource URL, /json/sessions/, using the getProperty action:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ --data '{"properties": ["LoginLocation"]}' \ http://openam.example.com:8080/openam/json/sessions/?_action=getProperty {"LoginLocation":"40.748440, -73.984559"}

You can read multiple properties in a single REST API call by specifying an array of fields in the JSON data. For example, --data '{"properties": ["property1", "property2"]}'.

To delete the value of a session property, perform an HTTP POST to the resource URL, /json/sessions/, using the deleteProperty action:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ --data '{"properties": ["LoginLocation"]}' \ http://openam.example.com:8080/openam/json/sessions/?_action=deleteProperty {"success":true}

You can not read or set properties internal to OpenAM sessions. If you specify an internal property in a REST API call, a 403 Forbidden error is returned. For example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ --data '{"properties": ["AuthLevel"]}' \ http://openam.example.com:8080/openam/json/sessions/?_action=getProperty {"code":403,"reason":"Forbidden","message":"Forbidden"}

OpenAM logs information about all REST API calls to the access topic. For more information about OpenAM audit topics, see Section6.2, "Audit Log Topics" in the Administration Guide.

Locate specific REST endpoints in the http.path log file property.

OpenAM logs information about REST API calls to two files:

OpenAM also provides additional information in its debug notifications for accesses to any endpoint, depending on the message type (error, warning or message) including realm, user, and result of the operation.

200 OK

The request was successful and a resource returned, depending on the request. For example, a successful HTTP GET on /users/myUser returns a user profile and status code 200, whereas a successful HTTP DELETE returns {"success","true"} and status code 200.

201 Created

The request succeeded and the resource was created.

400 Bad Request

The request was malformed. Either parameters required by the action were missing, or as in the following example incorrect data was sent in the payload for the action:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{"bad":"data"}' \ https://openam.example.com:8443/openam/json/users?_action=forgotPassword{ "code":400, "reason":"Bad Request", "message":"Username or email not provided in request"}

401 Unauthorized

The request requires user authentication as in the following example, which is missing an SSO Token value:

$ curl \ --request POST \ https://openam.example.com:8443/openam/json/sessions?_action=logout{ "code": 401, "reason": "Unauthorized", "message": "Access denied"}

403 Forbidden

Access was forbidden during an operation on a resource as in the following example, which has a regular user trying to read the OpenAM administrator profile:

$ curl \ --request POST \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ https://openam.example.com:8443/openam/json/authenticate{ "tokenId": "AQIC5w...YyMA..*" }$ curl \ --header "iplanetDirectoryPro: AQIC5w...YyMA..*" \ https://openam.example.com:8443/openam/json/users/amadmin{ "code": 403, "reason": "Forbidden", "message": "Permission to perform the read operation denied to id=demo,ou=user,dc=openam,dc=forgerock,dc=org"}

404 Not Found

The specified resource could not be found as in the following example, which is attempting to read a nonexistent user's profile:

$ curl \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ https://openam.example.com:8443/openam/json/users/missing{ "code":404, "reason":"Not Found", "message":"Resource cannot be found."}

405 Method Not Allowed

The HTTP method is not allowed for the requested resource.

406 Not Acceptable

The request contains parameters that are not acceptable as in the following example, which specifies an API version parameter that is not supported by OpenAM:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: changeit" \ --header "Accept-API-Version: protocol=1.0, resource=999.0" \ https://openam.example.com:8443/openam/json/authenticate{ "code":406, "reason":"Not Acceptable", "message":"Accept-API-Version: Requested version \"999.0\" does not match any routes."}

409 Conflict

The request would have resulted in a conflict with the current state of the resource. For example using the Forgot Password feature and specifying the user's email address as in the following example, where multiple users have the same email address:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{"email":"demo@example.com"}' \ https://openam.example.com:8443/openam/json/users?_action=forgotPassword{ "code":409, "reason":"Conflict", "message":"Multiple users found"}

410 Gone

The requested resource is no longer available, and will not become available again. The URI returned for resetting a password may have expired as in the following example:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{"username": "demo"}' \ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword{ "code":410, "reason":"Gone", "message":"Token not found"}

415 Unsupported Media Type

The request is in a format not supported by the requested resource for the requested method as in the following example, which is attempting to pass basic authentication credentials as form-encoded data rather than query string parameters:

$ curl \ --request POST \ --data "username=demo&password=changeit" \ https://openam.example.com:8443/openam/json/authenticate...HTTP Status 415...The server refused this request because the request entity is in aformat not supported by the requested resource for the requested method...

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request. This could be caused by an invalid configuration in the Email Service, or as in the following example the specified user account not having an associated email address to send the Forgot Password URI to:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{"username": "demo"}' \ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword{ "code":500, "reason":"Internal Server Error", "message":"No email provided in profile."}

501 Not Implemented

The resource does not support the functionality required to fulfill the request as in the following example, which is attempting to delete an entry as a delete action instead of using an HTTP DELETE request:

$ curl \ --request POST \ --header "iplanetDirectoryPro: AQIC5w...NTcy*" \ https://openam.example.com:8443/openam/json/users/demo?_action=delete{ "code": 501, "reason": "Not Implemented", "message": "Actions are not supported for resource instances"}

503 Service Unavailable

The requested resource was temporarily unavailable. The service may have been disabled, as in the following example, where the Forgot Password functionality has been disabled:

$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{"username": "demo"}' \ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword{ "code":503, "reason":"Service Unavailable", "message":"Forgot password is not accessible."}

2.1.2.RESTful Authorization and Policy Management Services

• Under /json{/realm}/resourcetypes, you find a JSON-based API for managing resource types.

• Under /json{/realm}/applications and /json/applicationtypes you find JSON-based APIs for administering policy sets and reading application types.

• Under /json{/realm}/policies, you find a JSON-based API for policy management and evaluation.

• Under /json/conditiontypes you find a JSON-based API for viewing what types of conditions you can use when defining policies.

• Under /json/subjecttypes you find a JSON-based API for viewing what types of subjects you can use when defining policies.

• Under /json/subjectattributes you find a JSON-based API for viewing subjects' attributes you can use when defining response attributes in policies.

• Under /json/decisioncombiners you find a JSON-based API for viewing implementations you can use when defining policies to specify how to combine results when multiple policies apply.

• Authenticated successfully to OpenAM as a user with sufficient privileges to make the REST API call

• Obtained the session token returned after successful authentication

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 "iPlanetDirectoryPro: AQIC5..." \ --header "Content-Type: application/json" \ --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 Section2.1.2.6, "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 "iPlanetDirectoryPro: AQIC5...NDU1*" \ --header "Content-Type: application/json" \ --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.

OpenAM provides the resourcetypes REST endpoint for the following:

• Section2.1.2.3.1, "Querying Resource Types"

• Section2.1.2.3.2, "Reading a Specific Resource Type"

• Section2.1.2.3.3, "Creating a Resource Type"

• Section2.1.2.3.4, "Updating a Resource Type"

• Section2.1.2.3.5, "Deleting a Specific Resource Type"

The values for the fields shown in the description are explained below:

"uuid"

String matching the unique identifier OpenAM generated for the resource type when created.

"name"

The name provided for the resource type.

"description"

An optional text string to help identify the resource type.

"patterns"

An array of resource patterns specifying individual URLs or resource names to protect.

For more information on patterns in resource types and policies, see Section3.3.4, "Specifying Resource Patterns with Wildcards" in the Administration Guide

"actions"

Set of string action names, each set to a boolean indicating whether the action is allowed.

"createdBy"

A string containing the universal identifier DN of the subject that created the resource type.

"creationDate"

An integer containing the creation date and time, in ISO 8601 format.

"lastModifiedBy"

A string containing the universal identifier DN of the subject that most recently updated the resource type.

If the resource type has not been modified since it was created, this will be the same value as createdBy.

"lastModifiedDate"

An string containing the last modified date and time, in ISO 8601 format.

If the resource type has not been modified since it was created, this will be the same value as creationDate.

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 Administrator user 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 Section2.1.1.6, "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 Administrator user 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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\u0000).

$ curl \--header "iPlanetDirectoryPro: AQIC5..." \--request POST \--header "Content-Type: application/json" \--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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\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 Administrator user 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.

OpenAM provides the applicationtypes REST endpoint for the following:

• Section2.1.2.4.1, "Querying Application Types"

• Section2.1.2.4.2, "Reading a Specific Application Type"

The values for the fields shown in the description are explained below:

"name"

The name provided for the application type.

"actions"

Set of string action names, each set to a boolean indicating whether the action is allowed.

"resourceComparator"

Class name of the resource comparator implementation used in the context of this application type.

The following implementations are available:

"com.sun.identity.entitlement.ExactMatchResourceName"

"com.sun.identity.entitlement.PrefixResourceName"

"com.sun.identity.entitlement.RegExResourceName"

"com.sun.identity.entitlement.URLResourceName"

"saveIndex"

Class name of the implementation for creating indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameIndexGenerator" for URL resource names.

"searchIndex"

Class name of the implementation for searching indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameSplitter" for URL resource names.

"applicationClassName"

Class name of the application type implementation, such as "com.sun.identity.entitlement.Application".

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 Administrator user 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 Section2.1.1.6, "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 Administrator user 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"}

OpenAM provides the applications REST endpoint for the following:

• Section2.1.2.5.1, "Querying Policy Sets"

• Section2.1.2.5.2, "Reading a Specific Policy Set"

• Section2.1.2.5.3, "Creating Policy Sets"

• Section2.1.2.5.4, "Updating Policy Sets"

• Section2.1.2.5.5, "Deleting Policy Sets"

The values for the fields shown in the description are explained below:

"conditions"

Condition types allowed in the context of this policy set.

For information on condition types, see Section2.1.2.6, "Managing Policies" and Section2.1.2.8, "Managing Environment Condition Types".

"applicationType"

Name of the application type used as a template for this policy set.

"subjects"

Subject types allowed in the context of this policy set.

For information on subject types, see Section2.1.2.6, "Managing Policies" and Section2.1.2.9, "Managing Subject Condition Types".

"entitlementCombiner"

Name of the decision combiner, such as "DenyOverride".

For more on decision combiners, see Section2.1.2.11, "Managing Decision Combiners".

"saveIndex"

Class name of the implementation for creating indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameIndexGenerator" for URL resource names.

"searchIndex"

Class name of the implementation for searching indexes for resource names, such as "com.sun.identity.entitlement.util.ResourceNameSplitter" for URL resource names.

"resourceComparator"

Class name of the resource comparator implementation used in the context of this policy set.

The following implementations are available:

"com.sun.identity.entitlement.ExactMatchResourceName"

"com.sun.identity.entitlement.PrefixResourceName"

"com.sun.identity.entitlement.RegExResourceName"

"com.sun.identity.entitlement.URLResourceName"

"resourceTypeUuids"

A list of the UUIDs of the resource types associated with the policy set.

"attributeNames"

A list of attribute names such as cn. The list is used to aid policy indexing and lookup.

"description"

String describing the policy set.

"realm"

Name of the realm where this policy set is defined. You must specify the realm in the policy set JSON even though it can be derived from the URL that is used when creating the policy set.

"name"

String matching the name in the URL used when creating the policy set by HTTP PUT or in the body when creating the policy set by HTTP POST.

"createdBy"

A string containing the universal identifier DN of the subject that created the policy set.

"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 set.

If the policy set 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 set has not been modified since it was created, this will be the same value as creationDate.

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 Administrator user who has access to perform the operation.

$ curl \--header "iPlanetDirectoryPro: AQIC5..." \https://openam.example.com:8443/openam/json/applications?_queryFilter=true{ "result": [ { "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" } ], "resultCount": 1, "pagedResultsCookie": null, "remainingPagedResults": 0} 

Additional query strings can be specified to alter the returned results. For more information, see Section2.1.1.6, "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 Administrator user 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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\u0000).

$ curl \--request POST \--header "iPlanetDirectoryPro: AQIC5..." \--header "Content-Type: application/json" \--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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\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 Administrator user who has access to perform the operation.

 $ curl \ --request DELETE \ --header "iPlanetDirectoryPro: AQIC5..." \ https://openam.example.com:8443/openam/json/applications/myupdatedpolicyset {}

OpenAM provides the policies REST endpoint for the following:

• Section2.1.2.6.1, "Querying Policies"

• Section2.1.2.6.2, "Reading a Specific Policy"

• Section2.1.2.6.3, "Creating Policies"

• Section2.1.2.6.4, "Updating Policies"

• Section2.1.2.6.5, "Deleting Policies"

• Section2.1.2.6.6, "Copying and Moving Policies"

The values for the fields shown in the example are explained below:

"name"

String matching the name in the URL used when creating the policy by HTTP PUT or in the body when creating the policy by HTTP POST.

"active"

Boolean indicating whether OpenAM 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.

Tip

Action values can also be expressed as numeric values. When using numeric values, use the value 0 for false and use any non-zero numeric value for true.

"subject"

Specifies the subject conditions to which the policy applies, where subjects can be combined by using the built-in types "AND", "OR", and "NOT", and where subject implementations are pluggable.

Subjects are shown as JSON objects with "type" set to the name of the implementation (using a short name for all registered subject implementations), and also other fields depending on the implementation. The subject types registered by default include the following:

• "AuthenticatedUsers", meaning any user that has successfully authenticated to OpenAM.

  { "type": "AuthenticatedUsers"} 

  Warning

  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, also add the AuthenticateToRealm environment condition.

• "Identity" to specify one or more users from an OpenAM 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 OpenAM 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 Section2.1.2.9, "Managing Subject Condition Types".

"condition"

Specifies environment conditions, where conditions can be combined by using the built-in types "AND", "OR", and "NOT", and where condition implementations are pluggable.

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 also other fields depending on the implementation. The condition types registered by default include the following.

• "AMIdentityMembership" to specify a list of OpenAM users and groups.

  { "type": "AMIdentityMembership", "amIdentityName": [ "id=scarter,ou=People,dc=example,dc=com" ]}

• "AuthLevel" to specify the authentication level.

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

• "AuthScheme" to specify the authentication module used to authenticate and the policy set name, and to set 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 chain that was used to authenticate.

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

• "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 either IP to match the user's IP address, or 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 that was used to authenticate the user, for example DataStore.

  service

  The authentication chain 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 from which the user was redirected.

  realm

  The realm to which the user authenticated.

• "Session" to specify how long the user's stateful or stateless session has been active, and to terminate the session if deemed too old, such that the user must authenticate again. Note that OpenAM terminates stateless sessions only if session blacklisting is in effect. For more information about session blacklisting, see Section9.4, "Session Termination" in the Administration Guide.

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

• "SessionProperty" to specify attributes set in the user's stateful or stateless 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 Section2.1.2.8, "Managing 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.

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 with "type" set to the name of the implementation (by default either "Static" for statically defined attributes or "User" for attributes from the user profile), "propertyName" 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.

To list all the policies in a realm, perform an HTTP GET to the /json{/realm}/policies endpoint, with a _queryFilter parameter set to true.

The iPlanetDirectoryPro header is required and should contain the SSO token of an Administrator user who has access to perform the operation.

$ curl \ --header "iPlanetDirectoryPro: AQIC5w..." \ https://openam.example.com:8443/openam/json/myrealm/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 Section2.1.1.6, "Filtering, Sorting, and Paging Results".

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 Administrator user 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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\u0000).

$ curl \ --request POST \ --header "iPlanetDirectoryPro: AQIC5..." \ --header "Content-Type: application/json" \ --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 Administrator user 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 consoleor REST endpoints. Using the special characters listed below causesOpenAM to return a 400 Bad Request error.The special characters are: double quotes ("), plussign (+), comma (,),less than (<), equals (=), greaterthan (>), backslash (\), forward slash(/), semicolon (;), andnull (\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 Administrator user 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 \ --header "iPlanetDirectoryPro: AQIC5w..." \ --header "Content-Type: application/json" \ --request POST \ --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 \ --header "iPlanetDirectoryPro: AQIC5w..." \ --header "Content-Type: application/json" \ --request POST \ --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 \ --header "iPlanetDirectoryPro: AQIC5w..." \ --header "Content-Type: application/json" \ --request POST \ --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"}

Note

OpenAM can only import XACML 3.0 policy sets that were either created by an OpenAM instance, or that have had minor manual modifications, due to the reuse of some XACML 3.0 parameters for non-standard information.

Table2.7.OpenAM Policies to XACML Mappings

Note

XACML obligation is not supported. Also, only one XACML match is defined for each privilege action, and only one XACML rule for each privilege action value.

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/policieshttp://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/policieshttp://openam.example.com:8080/openam/xacml/{realm}/policieswhere {realm} is the name of a specific realm 

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

OpenAM provides the conditiontypes REST endpoint for the following:

• Section2.1.2.8.1, "Querying Environment Condition Types"

• Section2.1.2.8.2, "Reading a Specific Environment Condition Type"

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 Administrator user 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 Section2.1.1.6, "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 Administrator user 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" } } } }}

OpenAM provides the subjecttypes REST endpoint for the following:

• Section2.1.2.9.1, "Querying Subject Condition Types"

• Section2.1.2.9.2, "Reading a Specific Subject Condition Type"

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 Administrator user 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 Section2.1.1.6, "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 Administrator user 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" } } } }}

OpenAM provides the subjectattributes REST endpoint for the following:

• Section2.1.2.10.1, "Querying Subject Attributes"

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 Administrator user 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.

OpenAM provides the decisioncombiners REST endpoint for the following:

• Section2.1.2.11.1, "Querying Decision Combiners"

• Section2.1.2.11.2, "Reading a Specific Decision Combiner"

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 Administrator user 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 Section2.1.1.6, "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 Administrator user who has access to perform the operation.

$ curl \ --header "iPlanetDirectoryPro: AQIC5..." \ https://openam.example.com:8443/openam/json/decisioncombiners/DenyOverride{ "title" : "DenyOverride"}

2.1.3.RESTful OAuth 2.0, OpenID Connect 1.0 and UMA 1.0 Services

OpenAM exposes the following REST endpoints for different OAuth 2.0 purposes:

• Endpoints for OAuth 2.0 clients and resource servers, mostly defined in RFC 6749, The OAuth 2.0 Authorization Framework, with additional tokeninfo and introspect endpoints useful to resource servers and clients.

• An endpoint for reading OAuth 2.0 resource sets. This is specific to OpenAM.

• An endpoint for OAuth 2.0 token administration. This is specific to OpenAM.

• An endpoint for OAuth 2.0 client administration. This is specific to OpenAM.

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

The /oauth2/authorize, and /oauth2/access_token endpoints function as described in RFC 6749.

The /oauth2/authorize endpoint is protected by the policy created during OAuth 2.0 authorization server configuration, which grants all authenticated users access.

The /oauth2/tokeninfo endpoint takes an HTTP GET on /oauth2/tokeninfo?access_token=token-id, and returns information about the token.

Resource servers — or any party having the token ID — can get token information through this endpoint without authenticating. This means any application or user can validate the token without having to be registered with OpenAM.

The following example shows OpenAM issuing an access token, and then returning token information:

$ curl \ --request POST \ --user "myClientID:password" \ --data "grant_type=password&username=demo&password=changeit&scope=cn%20mail" \ https://openam.example.com:8443/openam/oauth2/access_token{ "expires_in": 599, "token_type": "Bearer", "refresh_token": "f6dcf133-f00b-4943-a8d4-ee939fc1bf29", "access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"}$ curl https://openam.example.com:8443/openam/oauth2/tokeninfo\?access_token=f9063e26-3a29-41ec-86de-1d0d68aa85e9{ "mail": "demo@example.com", "scope": [ "mail", "cn" ], "cn": "demo", "realm": "/", "token_type": "Bearer", "expires_in": 577, "access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"} 

The resource server making decisions about whether the token is valid can thus use the /oauth2/tokeninfo endpoint to retrieve expiration information about the token. Depending on the scopes implementation, the JSON response about the token can also contain scope information. As described in Section13.1.3, "Using Your Own Client and Resource Server" in the Administration Guide, the default scopes implementation in OpenAM considers scopes to be names of attributes in the resource owner's user profile. Notice that the JSON response contains the values for those attributes from the user's profile, as in the preceding example, with scopes set to mail and cn.

Both the /oauth2/authorize and /oauth2/access_token endpoints can take additional parameters. In particular you must specify the realm using the realm=realm-name parameter if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top Level Realm). For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/authorize?realm=/customers and /oauth2/access_token?realm=/customers.

The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Section2.7, "Authenticating To OpenAM" in the Administration Guide, where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.

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 and /oauth2/access_token REST endpoints to support the OAuth 2.0 Device Flow.

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 \ --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=string, where string is either access_token to request the list of access tokens for the current user or all users if requested by amAdmin, or any other string to request the list of access tokens and refresh tokens.

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

$ curl \ --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcw..." \ https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=access_token{ "result": [ { "expireTime": "Dec 17, 2014 1:02 PM", "tokenName": [ "access_token" ], "scope": [ "cn" ], "grant_type": [ "password" ], "clientID": [ "myClientID" ], "parent": [], "id": [ "d2bbd4f9-955f-4683-bb83-bc0d7523b0f9" ], "tokenType": [ "Bearer" ], "redirectURI": [], "nonce": [], "realm": [ "/" ], "userName": [ "demo" ], "display_name": "", "scopes": "cn" }, { "expireTime": "Dec 17, 2014 1:02 PM", "tokenName": [ "access_token" ], "scope": [ "cn" ], "grant_type": [ "password" ], "clientID": [ "myClientID" ], "parent": [], "id": [ "12f9907f-dbfb-4c4c-a231-2b24964fee8b" ], "tokenType": [ "Bearer" ], "redirectURI": [], "nonce": [], "realm": [ "/" ], "userName": [ "demo" ], "display_name": "", "scopes": "cn" } ], "resultCount": 2, "pagedResultsCookie": null, "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 "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \ --header "Content-Type: application/json" \ --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 the following REST endpoints for OpenID Connect 1.0 purposes:

• Endpoints for discovering information.

• An endpoint for registering client applications.

• Endpoints for client authorization.

• Endpoints for session management.

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 Procedure14.4, "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 Section2.1.3.1.1, "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 Section14.7, "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 Section14.6, "Managing OpenID Connect User Sessions" in the Administration Guide.

OpenAM exposes the following REST endpoints for User-Managed Access purposes:

• An endpoint for automatic configuration and registration of the Authorization Server.

• An endpoint for registering sets of resources.

• An endpoint for managing UMA policies.

• Endpoints for requesting and granting authorization for access to resources.

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 Section15.4, "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 Section2.1.3.1.3, "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:

2.1.4.RESTful User Self-Service

/dashboard/assigned

This endpoint retrieves the list of applications assigned to the authenticated user.

$ curl \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/dashboard/assigned{ "google": { "dashboardIcon": [ "Google.gif" ], "dashboardName": [ "Google" ], "dashboardLogin": [ "http://www.google.com" ], "ICFIdentifier": [ "" ], "dashboardDisplayName": [ "Google" ], "dashboardClassName": [ "SAML2ApplicationClass" ] }} 

/dashboard/available

This endpoint retrieves the list of applications available in the authenticated user's realm. The example is based on two of the default Dashboard applications: Google and Salesforce.

$ curl \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/dashboard/available{ "google": { "dashboardIcon": [ "Google.gif" ], "dashboardName": [ "Google" ], "dashboardLogin": [ "http://www.google.com" ], "ICFIdentifier": [ "" ], "dashboardDisplayName": [ "Google" ], "dashboardClassName": [ "SAML2ApplicationClass" ] } "salesforce": { "dashboardIcon": [ "salesforce.gif" ], "dashboardName": [ "Salesforce" ], "dashboardLogin": [ "http://salesforce.com" ], "ICFIdentifier": [ "" ], "dashboardDisplayName": [ "Salesforce" ], "dashboardClassName": [ "SAML2ApplicationClass" ] }}

/dashboard/defined

This endpoint retrieves the list of all applications available defined for the OpenAM Dashboard service. The example is based on the three default Dashboard applications: Google, Salesforce, and Zendesk.

$ curl \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/dashboard/defined{ "google": { "dashboardIcon": [ "Google.gif" ], "dashboardName": [ "Google" ], "dashboardLogin": [ "http://www.google.com" ], "ICFIdentifier": [ "idm magic 34" ], "dashboardDisplayName": [ "Google" ], "dashboardClassName": [ "SAML2ApplicationClass" ] }, "salesforce": { "dashboardIcon": [ "salesforce.gif" ], "dashboardName": [ "SalesForce" ], "dashboardLogin": [ "http://www.salesforce.com" ], "ICFIdentifier": [ "idm magic 12" ], "dashboardDisplayName": [ "Salesforce" ], "dashboardClassName": [ "SAML2ApplicationClass" ] }, "zendesk": { "dashboardIcon": [ "ZenDesk.gif" ], "dashboardName": [ "ZenDesk" ], "dashboardLogin": [ "http://www.ZenDesk.com" ], "ICFIdentifier": [ "idm magic 56" ], "dashboardDisplayName": [ "ZenDesk" ], "dashboardClassName": [ "SAML2ApplicationClass" ] }} 

• A user loses a registered device—for example, a mobile phone—but had not saved the device recovery codes available in the OpenAM dashboard.

• A user loses a registered device and has no device recovery codes remaining.

2.1.5.RESTful Identity and Realm Management Services

Important

OpenAM is not primarily an identity data store, nor is it provisioning software. For storing identity data, consider OpenDJ. For provisioning, consider OpenIDM. Both of these products provide REST APIs as well.

OpenAM has two REST APIs for managing identities:

• Under the /json/agents, /json/groups, and /json/users, you find the newer JSON-based APIs. The newer APIs follow the ForgeRock common REST pattern creating, reading, updating, deleting, and querying resources.

  Examples in this section do not repeat the authentication shown in Authorization and Policy Management. For browser-based clients, you can rely on OpenAM cookies rather than construct the header in your application. Managing agent profiles, groups, realms, and users with these APIs of course require authorization. The examples shown in this section were performed with the token ID gained after authenticating as OpenAM administrator.

  Although the examples here show user management, you can use /json/agents, /json/groups, /json/realms in similar fashion. See Section2.1.5.2, "Realm Management" for examples related to realms.

  The following sections cover this JSON-based API:

  • Section2.1.5.1.1, "Creating Identities"

  • Section2.1.5.1.2, "Reading Identities"

  • Section2.1.5.1.3, "Updating Identities"

  • Section2.1.5.1.4, "Deleting Identities"

  • Section2.1.5.1.5, "Listing Identities"

  • Section2.1.5.1.7, "Changing Passwords"

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 "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Content-Type: application/json" \ --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 "iPlanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Content-Type: application/json" \ --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 "iPlanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Content-Type: application/json" \ --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 Section2.1.5.1.3, "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 Section2.1.1.6, "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 "iplanetdirectorypro: AQIC5wM2LY4SfczUFNs-TJwFrCVAKgR0NulIAyNaIkQmjis.*AAJTSQACMDEA AlNLABQtNTQ3NDE2Njc5ODk4MjYzMzA2MQ..*" \ --header "Content-Type: application/json" 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 Section2.1.4.2, "Retrieving Forgotten Usernames" instead.

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

$ curl \ --request POST \ --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \ --header "Content-Type: application/json" \ --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 Section2.1.1.10, "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 Section2.1.1.10, "REST Status Codes" for more information.

• Under the /json/realms endpoint, you find the newer JSON-based API:

  The following sections cover this JSON-based API.

  • Section2.1.5.2.1, "Default Parameters for Realms"

  • Section2.1.5.2.2, "Creating Realms"

  • Section2.1.5.2.3, "Reading Realms"

  • Section2.1.5.2.4, "Listing Realms"

  • Section2.1.5.2.5, "Updating Realms"

  • Section2.1.5.2.6, "Deleting Realms"

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 "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Content-Type: application/json" \ --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 Section2.1.5.2.5, "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" } 

2.1.6.RESTful Script Management

Note

If the realm is not specified in the URL, OpenAM returns scripts in the top level realm, as well as any global scripts.

Table2.12.Supported _queryFilter Fields and Operators

Tip

To read a script in the top-level realm, or to read a built-in global script, do not specify a realm in the URL.

Note

If the realm is not specified in the URL, OpenAM creates the script in the top level realm.

Note

If the realm is not specified in the URL, OpenAM uses the top level realm.

Note

If the realm is not specified in the URL, OpenAM uses the top level realm.

2.1.7.RESTful Troubleshooting Information Recording