Configuring Realms (REST)
This section shows how to use the AM RESTful interfaces for identity and realm management.
In this section, long URLs are wrapped to fit the printed page, as some of the output is formatted for easier reading.
Before making a REST API call to manage an identity, make sure that you have:
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call
Obtained the session token returned after successful authentication
When making the REST API call, pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see "Using the Session Token After Authentication". For general information about the REST API, see Getting Started with REST.
Tip
To make REST requests to a specific realm, see Specifying Realms in REST API Calls.
Identity Management
This section shows how to create, read, update, delete, and list identities using the RESTful APIs.
Important
AM is not primarily an identity store, nor is it provisioning software. For storing identity data, consider ForgeRock Directory Services. For provisioning, consider ForgeRock Identity Management. Both of these products provide REST APIs as well.
AM has the /json/groups and /json/users JSON-based APIs for managing identities. These APIs follow the ForgeRock Common REST pattern for creating, reading, updating, deleting, and querying resources.
Examples in this section do not repeat the authentication shown in Authenticating (REST). For browser-based clients, you can rely on AM cookies rather than construct the header in your application. Managing agent profiles, groups, and users with these APIs requires authentication. The examples shown in this section were performed with the token ID gained after authenticating as an AM administrator, for example amAdmin.
Although the examples here show user management, you can use /json/groups in a similar fashion. See "Realm Management" for examples related to realms.
The following sections cover this JSON-based API:
Creating Identities
AM lets administrators create a user profile with 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, _id, cn, sn, and uid are all set to the value of username. Values provided for uid are not used.
$curl \ --request POST \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --data \ '{ "username": "bjensen", "userpassword": "secret12", "mail": "bjensen@example.com" }' \ https://openam.example.com:8443/openam/json/realms/root/users/?_action=create{ "_id": "bjensen", "_rev": "-588258934", "username": "bjensen", "realm": "/", "uid": [ "bjensen" ], "mail": [ "bjensen@example.com" ], "universalid": [ "id=bjensen,ou=user,dc=openam,dc=forgerock,dc=org" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "inetorgperson", "sunIdentityServerLibertyPPService", "devicePrintProfilesContainer", "iplanet-am-user-service", "iPlanetPreferences", "pushDeviceProfilesContainer", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "person", "sunAMAuthAccountLockout", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "inetUserStatus": [ "Active" ], "dn": [ "uid=bjensen,ou=people,dc=openam,dc=forgerock,dc=org" ], "cn": [ "bjensen" ], "sn": [ "bjensen" ], "createTimestamp": [ "20180426120642Z" ] }
When LDAP User Search Attribute and Authentication Naming Attribute are set to different attributes, AM treats _id and username as distinct values. In this case, _id is mapped to LDAP User Search Attribute, which is autogenerated if not specified in the payload, and username is mapped to Authentication Naming Attribute.
For example, given the same payload as above, if LDAP User Search Attribute is set to cn, the user data is set using the generated UUID as follows:
{
"_id":"f3377274-99e4-44f3-8578-0a09914368fc",
"_rev":"-1",
"realm":"/",
"username":"bjensen",
"uid":[
"bjensen"
],
"mail":["bjensen@example.com"],
"universalid":[
"id=f3377274-99e4-44f3-8578-0a09914368fc,ou=user,dc=openam,dc=forgerock,dc=org"
],
"objectClass":[
...
],
"inetUserStatus":[
"Active"
],
"dn":[
"cn=f3377274-99e4-44f3-8578-0a09914368fc,ou=people,dc=openam,dc=forgerock,dc=org"],
"cn":[
"f3377274-99e4-44f3-8578-0a09914368fc"],
"sn":[
"bjensen"
],
"createTimestamp":[
"20220608100442Z"
]
}
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 "Accept-API-Version: protocol=2.1,resource=3.0" \ --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/realms/root/users/janedoe{ "_id": "janedoe", "_rev": "-1686380958", "username": "janedoe", "realm": "/", "uid": [ "janedoe" ], "mail": [ "janedoe@example.com" ], "universalid": [ "id=janedoe,ou=user,dc=openam,dc=forgerock,dc=org" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "inetorgperson", "sunIdentityServerLibertyPPService", "devicePrintProfilesContainer", "iplanet-am-user-service", "iPlanetPreferences", "pushDeviceProfilesContainer", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "person", "sunAMAuthAccountLockout", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn": [ "uid=janedoe,ou=people,dc=openam,dc=forgerock,dc=org" ], "inetUserStatus": [ "Active" ], "cn": [ "janedoe" ], "sn": [ "janedoe" ], "createTimestamp": [ "20180426121152Z" ] }
As shown in the examples, AM returns the JSON representation of the profile on successful creation. On failure, AM returns a JSON representation of the error including the HTTP status code. For example, version 2.0 of the Common REST /json/users /json/groups 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 groups:
$curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --data '{ "username":"newGroup" }' \ https://openam.example.com:8443/openam/json/realms/root/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/realms/root/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" ] }
Reading Identities
AM lets users and administrators read profiles by requesting an HTTP GET on /json/subrealm/users/user-id. This allows users and administrators to verify user data, status, and directory. If users or administrators see missing or incorrect information, they can write down the correct information and add it using "Updating Identities". To read a profile on the Top Level Realm, you do not need to specify the realm.
Users can review the data associated with their own accounts, and administrators can also read other user's profiles.
Note
If an administrator user is reading their own profile, an additional roles element, with a value of ui-admin is returned in the JSON response. The UI verifies this element to grant or deny access to the AM Console.
The following example shows an administrator accessing user data belonging to demo:
$curl \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/realms/root/users/demo{ "_id":"demo", "_rev":"-320505756", "username":"demo", "realm":"/", "uid":[ "demo" ], "universalid":[ "id=demo,ou=user,dc=openam,dc=forgerock,dc=org" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" ], "inetUserStatus":[ "Active" ], "sn":[ "demo" ], "cn":[ "demo" ], "createTimestamp":[ "20170105101638Z" ], "modifyTimestamp":[ "20170110102632Z" ] }
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. Note that the _fields argument is case-sensitive. In the following example, the returned value matches the specified argument, uid, whereas UID would not:
$curl \ --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/realms/root/users/demo?_fields=username,uid{ "username":"demo", "uid":[ "demo" ] }
As shown in the examples, AM returns the JSON representation of the profile on success. On failure, AM returns a JSON representation of the error including the HTTP status code.
Updating Identities
AM 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" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-Match: *" \ --data '{ "mail": "demo@example.com" }' \ https://openam.example.com:8443/openam/json/realms/root/users/demo{ "username":"demo", "realm":"/", "uid":[ "demo" ], "mail":[ "demo@example.com" ], "universalid":[ "id=demo,ou=user,dc=openam,dc=forgerock,dc=org" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" ], "inetUserStatus":[ "Active" ], "sn":[ "demo" ], "cn":[ "demo" ], "createTimestamp":[ "20170105101638Z" ], "modifyTimestamp":[ "20170110105038Z" ], "roles":[ "ui-self-service-user" ] }
As shown in the example, AM returns the JSON representation of the profile on success. On failure, AM 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 groups:
Notice in the following example, which updates newGroup, the object class value is not included in the JSON sent to AM:
$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/realms/root/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" ] }
Deleting Identities
AM 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 "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ https://openam.example.com:8443/openam/json/realms/root/users/bjensen{ "_id": "bjensen", "_rev": "-1870449267", "success": "true" }
On success, AM returns a JSON object indicating success. On failure, AM 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 on a group:
$curl \ --request DELETE \ --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/realms/root/groups/newGroup{ "success":"true" }
Important
Deleting a user does not automatically remove any of the user's sessions. If you are using CTS-based sessions, you can remove a user's sessions by checking for any sessions for the user and then removing them using the console's Sessions page. If you are using client-based sessions, you cannot remove users' sessions; you must wait for the sessions to expire.
Listing Identities
AM 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/realms/root/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 "Query".
The _queryId=* parameter also works for other types of objects, such as groups:
$curl \ --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ "https://openam.example.com:8443/openam/json/realms/root/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, AM returns the JSON representation of the resource list if successful. On failure, AM returns a JSON representation of the error including the HTTP status code.
Retrieving Identities Using the Session Cookie
If you only have access to the iPlanetDirectoryPro session cookie, you can retrieve the user ID by performing an HTTP POST operation on the /json/users endpoint using the idFromSession action:
$curl \ --verbose \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcz...c5ODk4MjYzMzA2MQ..*" \ https://openam.example.com:8443/openam/json/realms/root/users?_action=idFromSession{ "id":"demo", "realm":"/", "dn":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org", "successURL":"/openam/console", "fullLoginURL":"/openam/UI/Login?realm=%2F" }
Changing Passwords
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.
Note
Changing the top-level administrator's password requires a more complex procedure. See "Changing the amAdmin Password (Console)" for more information.
Users must provide the current password, which is set in the request as the value of the currentpassword.
For cases where users have forgotten their password, see Retrieving Forgotten Usernames instead.
The following example shows a successful request to change the demo user's password to password:
$curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \ --data '{ "currentpassword":"Ch4ng31t", "userpassword":"password" }' \ https://openam.example.com:8443/openam/json/realms/root/users/demo?_action=changePassword{}
On success, the response is an empty JSON object {} as shown in the example.
On failure, AM returns a JSON representation of the error including the HTTP status code. See also "HTTP 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 "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "Content-Type: application/json" \ --data '{ "userpassword":"cangetin" }' \ https://openam.example.com:8443/openam/json/realms/root/users/demo{ "_id":"demo", "_rev":"-1942782480", "username":"demo", "realm":"/", "uid":[ "demo" ], "mail":[ "demo@example.com" ], "universalid":[ "id=demo,ou=user,dc=openam,dc=forgerock,dc=org" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" ], "inetUserStatus":[ "Active" ], "sn":[ "demo" ], "cn":[ "demo" ], "modifyTimestamp":[ "20170110105705Z" ], "createTimestamp":[ "20170105101638Z" ] }
As shown in the example, AM returns the JSON representation of the profile on success. On failure, AM returns a JSON representation of the error including the HTTP status code. See also "HTTP Status Codes" for more information.
Creating Groups
AM lets administrators create a group with an HTTP POST of the JSON representation of the group to the /json/subrealm/groups?_action=create endpoint.
The following example shows how to create a group called newGroup in the top level realm using the REST API after authenticating to AM:
$curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --data '{ "username":"newGroup" }' \ https://openam.example.com:8443/openam/json/realms/root/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" ] }
Adding a User to a Group
AM lets administrators add a user to an existing group with an HTTP PUT to the JSON representation of the group to the /json/subrealm/groups/groupName endpoint.
The following example shows how to add users to an existing group by using the REST API. The example assumes that the DS backend is in use. Make sure to use the uniquemember attribute to specify the user using the DS server:
$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/realms/root/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" ] }
Note
For Active Directory implementations, use the member attribute when adding a user to a group using the REST API:
$curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \ --header "Content-Type: application/json" \ --data '{ "member":[ "cn=newUser,cn=users,dc=forgerock,dc=org", "cn=demo,cn=users,dc=forgerock,dc=org" ] }' \ https://openam.example.com:8443/openam/json/realms/root/groups/newGroup{ "username": "newGroup", "realm": "/", "sAMAccountName": ["$FL2000-EP4RN8LPBKUS"], "universalid": ["id=newGroup,ou=group,dc=forgerock,dc=org"], "sAMAccountType": ["268435456"], "member": ["cn=newUser,cn=users,dc=forgerock,dc=org", "cn=demo,cn=users,dc=forgerock,dc=org"], "name": ["newGroup"], "objectClass": [ "top", "group" ], "distinguishedName": ["CN=newGroup,CN=Users,DC=forgerock,DC=org"], "dn": ["CN=newGroup,CN=Users,DC=forgerock,DC=org"], "cn": ["newGroup"], "objectCategory": ["CN=Group,CN=Schema,CN=Configuration,DC=forgerock,DC=org"] }
Realm Management
This section shows how to create, read, update, and delete realms using the /json/global-config/realms endpoint.
Tip
You can use the AM API Explorer for detailed information about this endpoint and to test it against your deployed AM instance.
In the AM console, click the Help icon, and then navigate to API Explorer > /global-config > /realms.
The following sections cover managing realms with the JSON-based RESTful API:
Required Properties for Managing Realms
The following table shows the required properties when managing realms using the REST API:
| Realm Property | Purpose |
|---|---|
name | The name of the realm. Do not use the names of AM REST endpoints as the name of a realm. Names that should not be used include |
active | Whether the realm is to be active, or not. Specify either |
parentPath | The path of the parent realm. |
aliases | An array of any applicable aliases associated with the realm. Be aware that an alias can only be used once. Entering an alias used by another realm will remove the alias from that realm and you will lose configuration. |
The following shows an example JSON payload when managing a realm:
{
"name": "mySubRealm",
"active": true,
"parentPath": "/",
"aliases": [ "payroll.example.com" ]
}Creating Realms
AM lets administrators create a realm by performing an HTTP POST of the JSON representation of the realm to /json/global-config/realms.
The following example creates a new, active subrealm in the top level realm, named mySubRealm:
$curl \ --request POST \ --header "Content-Type: application/json" \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ --data '{ "name": "mySubRealm", "active": true, "parentPath": "/", "aliases": [ "payroll.example.com" ] }' \ https://openam.example.com:8443/openam/json/global-config/realms{ "_id": "L2Fub3RoZXJSZWFsbQ", "_rev": "-1054013208", "parentPath": "/", "active": true, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }
AM returns a 201 HTTP status code and a JSON representation of the realm on success. The value returned in the _id field is used in subsequent REST calls relating to the realm. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see "HTTP Status Codes".
Listing Realms
To list and query realms, perform an HTTP GET on the /json/global-config/realms endpoint, and set the _queryFilter query string parameter to true as in the following example, which lists all available realms:
$curl \ --header "iPlanetDirectoryPro: AQIC5..." \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ https://openam.example.com:8443/openam/json/global-config/realms?_queryFilter=true{ "result":[ { "_id":"Lw", "_rev":"252584985", "parentPath":null, "active":true, "name":"/", "aliases":[ "openam.example.com", "openam" ] }, { "_id":"L215U3ViUmVhbG0", "_rev":"949061198", "parentPath":"/", "active":true, "name":"mySubRealm", "aliases":[ "payroll.example.com" ] } ], "resultCount":2, "pagedResultsCookie":null, "totalPagedResultsPolicy":"NONE", "totalPagedResults":-1, "remainingPagedResults":-1 }
For more information about using the _queryString parameter in REST calls, see "Query".
Reading Realms
To read a realm's details, perform an HTTP GET on the /json/global-config/realms/realm-id endpoint, where realm-id is the value of _id for the realm.
The following example shows an administrator receiving information about a realm called mySubRealm, which has an _id value of L215U3ViUmVhbG0:
$curl \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/global-config/realms/L215U3ViUmVhbG0{ "_id": "L215U3ViUmVhbG0", "_rev": "949061698", "parentPath": "/", "active": true, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }
AM returns a 200 HTTP status code and a JSON representation of the realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see "HTTP Status Codes".
Updating Realms
To update a realm's aliases or to toggle between active and inactive, perform an HTTP PUT on the /json/global-config/realms/realm-id endpoint, where realm-id is the value of _id for the realm.
The request should include an updated JSON representation of the complete realm. Note that you cannot alter the name or parent properties of a realm.
The following example shows how to update a realm called mySubRealm, which has an _id value of L215U3ViUmVhbG0. The example changes the realm status to inactive:
$curl \ --request PUT \ --header "iplanetDirectoryPro: AQIC5...Y3MTAx*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0, protocol=1.0" \ --data '{ "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }' \ https://openam.example.com:8443/openam/json/global-config/realms/L215U3ViUmVhbG0{ "_id": "L215U3ViUmVhbG0", "_rev": "94906213", "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }
AM returns a 200 HTTP status code and a JSON representation of the realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see "HTTP Status Codes".
Deleting Realms
To delete a realm, perform an HTTP DELETE on the /json/global-config/realms/realm-id endpoint, where realm-id is the value of _id for the realm.
The following example shows how to delete a realm called mySubRealm, which has an _id value of L215U3ViUmVhbG0.
Caution
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 previously backed up deployment of AM.
$curl \ --request DELETE \ --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ https://openam.example.com:8443/openam/json/global-config/realms/L215U3ViUmVhbG0{ "_id": "L215U3ViUmVhbG0", "_rev": "949061708", "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }
AM returns a 200 HTTP status code and a JSON representation of the deleted realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, "HTTP Status Codes".