Access Management 7.3.2

Configure identities and realms over REST

This page shows how to use the REST API to manage identities and realms.

Long URLs are wrapped to fit the printed page, and some output is formatted for easier reading.

Before making a REST API call to manage an identity or realm, 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.

To make REST requests to a specific realm, see Specify realms in REST API calls.

Manage identities

This section shows how to create, read, update, delete, and list identities using the REST API.

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 Authenticate over 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 Manage realms for examples related to realms.

The following sections cover this JSON-based API:

Create an identity

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 and /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/realms/alpha/groups?_action=create'
{
    "username":"newGroup",
    "realm":"/alpha",
    "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/realms/alpha/anotherGroup'
{
    "username":"anotherGroup",
    "realm":"/alpha",
    "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"
    ]
}

Read an identity

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 Update an identity. 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.

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.

Update an identity

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/realms/alpha/groups/newGroup'
{
    "name":"newGroup",
    "realm":"/alpha",
    "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"
    ]
}

Delete an identity

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/realms/alpha/groups/newGroup'
{
    "success":"true"
}

Deleting a user does not automatically remove any of the user’s sessions. If you are using server-side 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-side sessions, you cannot remove users' sessions; you must wait for the sessions to expire.

List 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/realms/alpha/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.

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/XUI/?realm=%2F"
}

Change 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.

Changing the top-level administrator’s password requires a more complex procedure. See Changing the amAdmin Password (UI) for more information.

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

If a user has forgotten their password, see Retrieve 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.

Create a group

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/realms/alpha/groups?_action=create'
{
    "username":"newGroup",
    "realm":"/alpha",
    "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"
    ]
}

Add 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/realms/alpha/groups/newGroup'
{
    "name":"newGroup",
    "realm":"/alpha",
    "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"
    ]
}

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/realms/alpha/groups/newGroup'
{
    "username": "newGroup",
    "realm": "/alpha",
    "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"]
}

Manage realms

This section shows how to create, read, update, and delete realms using the /json/global-config/realms endpoint.

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 admin UI, click the Help icon, and then go to API Explorer > /global-config > /realms.

The following sections cover managing realms with the REST API:

Required realm properties

The following table shows the required properties when managing realms using the REST API:

Realm Properties for JSON-based API
Realm Property Purpose

name

The name of the realm.

Realm names must not match any of the following:

  • Existing realm names.

  • Existing realm aliases.

  • Names of AM REST endpoints.

    By default, you cannot use any of the following names for a new realm:

    agents
api
applications
applicationtypes
authenticate
cache
conditiontypes
dashboard
decisioncombiners
docs
email
global-audit
global-config
groups
health
metrics
policies
push
realm-audit
realm-config
realms
records
resourcetypes
scripts
selfservice
serverinfo
sessions
subjectattributes
subjecttypes
things
timetravel
token
tokens
users

active

Whether the realm is to be active, or not.

Specify either true or false.

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 JSON object shows an example realm configuration:

{
    "name": "mySubRealm",
    "active": true,
    "parentPath": "/",
    "aliases": [ "payroll.example.com" ]
}

Create a realm

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.

List 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.

Read a realm

To read a realm’s details, send an HTTP GET to 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.

Update a realm

To update a realm’s aliases or to toggle between active and inactive, send an HTTP PUT to 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.

Delete a realm

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.

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.