Guide to performing setup and maintenance tasks in ForgeRock® Access Management, such as backing up and restoring, managing keystores, tuning the environment, monitoring, and others. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

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, the entry you make for username defaults to both the user id and the user's last name:

$ 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"
    ]
}

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 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 web or Java agent profiles and groups:

$ curl \
--request POST \
--header "Accept-API-Version: protocol=2.0,resource=1.0" \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data \
'{
    "username":"myAgent",
    "com.sun.identity.agents.config.fqdn.default":[
        "www.example.com"
    ],
    "com.sun.identity.agents.config.repository.location":[
        "centralized"
    ],
    "agenttype":[
        "WebAgent"
    ],
    "serverurl":[
        "https://openam.example.com:8443/openam/"
    ],
    "agenturl":[
        "http://www.example.com:80/"
    ],
    "userpassword":[
        "password"
    ],
    "com.sun.identity.agents.config.login.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#login"
    ],
    "com.sun.identity.agents.config.logout.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#logout"
    ],
    "sunidentityserverdevicestatus":[
        "Active"
    ]
}' \
https://openam.example.com:8443/openam/json/realms/root/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"
    ],
    "userpassword": [
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.sun.identity.agents.config.login.url": [
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#login"
    ],
    "com.sun.identity.agents.config.logout.url":
        ["[0]=https://openam.example.com:8443/openam/XUI/?realm=/#logout"
    ],
    "sunIdentityServerDeviceStatus": [
        "Active"
    ]
}

$ 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"
    ]
}

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 using the REST API". 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/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.

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

$ curl \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--header "Accept-API-Version: protocol=2.0,resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/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"
    ],
    "userpassword":[
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.sun.identity.agents.config.login.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#login"
    ],
    "com.sun.identity.agents.config.logout.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#logout"
    ],
    "sunIdentityServerDeviceStatus":[
        "Active"
    ]
}

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 web or Java agent profiles and groups.

The following example updates a web agent profile:

$ curl \
--request PUT \
--header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \
--header "Accept-API-Version: protocol=2.0,resource=1.0" \
--header "If-Match: *" \
--header "Content-Type: application/json" \
--data '{
    "sunIdentityServerDeviceStatus" : [ "Inactive" ]
}' \
https://openam.example.com:8443/openam/json/realms/root/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"
    ],
    "userpassword":[
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.sun.identity.agents.config.login.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#login"
    ],
    "com.sun.identity.agents.config.logout.url":[
        "[0]=https://openam.example.com:8443/openam/XUI/?realm=/#logout"
    ],
    "sunIdentityServerDeviceStatus":[
        "Inactive"
    ]
}

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"
    ]
}

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 of an agent profile or of a group:

$ curl \
--request DELETE \
--header "Accept-API-Version: protocol=2.0,resource=1.0" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
https://openam.example.com:8443/openam/json/realms/root/agents/myOAuth2ClientAgent
{
    "_id": "myOAuth2ClientAgent",
    "_rev": "-1870449267",
    "success": "true"
}

$ 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"
}

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 agent profiles and groups:

$ curl \
--header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
--header "Accept-API-Version: protocol=2.0,resource=1.0" \
"https://openam.example.com:8443/openam/json/realms/root/agents?_queryId=*"
{
   "result":[
      {
         "_id":"myAgent",
         "_rev":"-1078786086",
         "username":"myAgent",
         "realm":"/"
      }
   ],
   "resultCount":1,
   "pagedResultsCookie":null,
   "remainingPagedResults":-1
}

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

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"
}

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

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

For cases where users have forgotten their password, see "Retrieving Forgotten Usernames" in the User Self-Service Guide 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":"changeit",
    "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.

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"
    ]
}

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"
    ]
}

$ 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"]
}

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

The following shows an example JSON payload when managing a realm:

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

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

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

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

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

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.

$ 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, see "HTTP Status Codes".

You should verify that you have configured the repository and administrator privileges correctly. You can test configuration as follows:

If you receive an LDAP error code 65 while attempting to create a user, it indicates that you did not correctly prepare the external identity repository. Error code 65 is an LDAP object class violation and often indicates a problem with the directory schema or permissions.

A common reason for this error while attempting to create a user is that the bind account might not have adequate rights to add data to the directory. Review the DS access log and locate the entries for the add operation to determine if it is an access rights issue.

For information on setting up Directory Services as an external identity store, see "Installing and Configuring Directory Services for Identity Data" in the Installation Guide.

You can extend user profiles by adding custom attributes. This section demonstrates how to add a custom attribute to a user profile when storing user profiles in the LDAP directory.

Adding a custom attribute involves both updating the identity repository schema to hold the new attribute and updating the XUI. Furthermore, to give users write permissions to the custom attribute, you must also update the AM configuration store.

AM maps user and group identities into a realm using data stores. An AM data store relies on a Java identity repository (IdRepo) plugin to implement interaction with the identity repository where the users and groups are stored.

public void initialize(Map configParams)

public int addListener(SSOToken token, IdRepoListener listener)
public void removeListener()

public void shutdown()

public Set getSupportedTypes()

public Set getSupportedOperations(IdType type)

public boolean supportsAuthentication()

<SubSchema i18nKey="x4000" inheritance="multiple" maintainPriority="no"
           name="CustomRepo" supportsApplicableOrganization="no" validate="yes">
 <AttributeSchema cosQualifier="default" isSearchable="no"
                  name="RequiredValueValidator" syntax="string"
                  type="validator" >
  <DefaultValues>
   <Value>com.sun.identity.sm.RequiredValueValidator</Value>
  </DefaultValues>
 </AttributeSchema>
 <AttributeSchema any="required" cosQualifier="default"
                  i18nKey="x4001" isSearchable="no"
                  name="sunIdRepoClass" syntax="string"
                  type="single" validator="RequiredValueValidator" >
  <DefaultValues>
   <Value>org.test.CustomRepo</Value>
  </DefaultValues>
 </AttributeSchema>
 <AttributeSchema cosQualifier="default" i18nKey="x4002" isSearchable="no"
                  name="sunIdRepoAttributeMapping" syntax="string" type="list">
  <DefaultValues>
    <Value></Value>
  </DefaultValues>
 </AttributeSchema>
</SubSchema>

$ cd /path/to/tomcat/webapps/openam/WEB-INF/classes/
$ jar -xvf ../lib/openam-core-6.5.5.jar amIdRepoService.properties
inflated: amIdRepoService.properties

$ ssoadm \
 add-sub-schema \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename sunIdentityRepositoryService \
 --schematype Organization \
 --filename customIdRepo.xml

https://openam.example.com:8443/openam/XUI/?realm=/myrealm&module=DataStore#login

The following procedure describes how to configure a JSON audit event handler:

The following procedure describes how to configure a comma-separated values (CSV) audit event handler:

AM can publish audit events to a syslog server, which is based on a widely-used logging protocol. You can configure your syslog settings on the AM console.

The following procedure describes how to configure a Syslog audit event handler:

You can configure AM to write audit logs to Oracle, MySQL, PostgreSQL, or other JDBC databases. AM writes audit log records to the following tables: am_auditaccess, am_auditactivity, am_auditauthentication, and am_auditconfig. For more information on the JDBC table formats for each of the logs, see "JDBC Audit Log Tables".

Before configuring the JDBC audit event handler, you must perform several steps to allow AM to log to the database:

The following procedure describes how to configure a JDBC audit event handler. Perform the following steps after you have created audit log tables in your database and installed the JDBC driver in the AM web container:

AM supports audit logging to Elasticsearch 5.0. When you store AM's audit logs in an Elasticsearch data store, you can use Kibana to perform data discovery and visualization on your logs.

You can experiment with an Elasticsearch audit handler without enabling any Elasticsearch security features. However, for a more secure deployment, ForgeRock recommends that you use Elasticsearch Shield to require authentication to Elasticshield. Depending on your network topology, you might also want to configure SSL for Elasticsearch Shield.

Before configuring the Elasticsearch audit event handler, you must configure an Elasticsearch index with AM's audit schema:

The following procedure describes how to configure an Elasticsearch audit event handler. Perform the following steps after you have created an Elasticsearch index for AM audit logging:

AM supports audit logging to a JMS message broker. JMS is a Java API for sending messages between clients using a publish and subscribe model as follows:

Before configuring the JMS audit event handler, you must perform several steps to allow AM to publish audit events as a JMS client:

The following procedure describes how to configure a JMS audit event handler.

If your JMS message broker requires an SSL connection, you might need to perform additional, broker-dependent configuration tasks. For example, you might need to import a broker certificate into AM's keystore, or provide additional JNDI context properties.

See your JMS message broker's documentation for specific requirements for making SSL connections to your broker, and implement them as needed in addition to the steps in the following procedure.

Perform the following steps after you have installed the JMS client .jar file in the AM web container:

AM supports sending audit logging data to a Splunk HTTP event collector REST endpoint. This endpoint requires an authentication token created in Splunk and configured in the AM event handler.

Before configuring the Splunk audit event handler in AM, configure the endpoint in Splunk:

The following procedure describes how to configure a Splunk audit event handler in AM. Perform the following steps after you have created a Splunk HTTP event collector token:

You can configure AM to allow you to access a web based view of AM MBeans on port 8082 where the core server runs, such as http://openam-ter.example.com:8082/. Either use the console, or use the ssoadm command:

$ ssoadm \
  set-attr-defs \
  --servicename iPlanetAMMonitoringService \
  --schematype Global \
  --adminid amadmin \
  --password-file /tmp/pwd.txt \
  --attributevalues iplanet-am-monitoring-http-enabled=true

The default authentication file allows you to authenticate over HTTP as user demo, password changeit. The user name and password are kept in the file specified, with the password encrypted:

$ cat openam/openam/openam_mon_auth
demo AQICMBCKlwx6G3vzK3TYYRbtTpNYAagVIPNP

Or:

$ cat openam/openam/opensso_mon_auth
demo AQICvSe+tXEg8TUUT8ekzHb8IRzVSvm1Lc2u

You can encrypt a new password using the ampassword command. After changing the authentication file, you must restart AM for the changes to take effect.

MBeans in a Browser

You can configure AM to allow you to listen for Java Management eXtension (JMX) clients, by default on port 9999. Either use the AM console page under Configure > Global Services > Monitoring and make sure both Monitoring Status and Monitoring RMI interface status are both set to Enabled, or use the ssoadm command:

$ ssoadm \
  set-attr-defs \
  --servicename iPlanetAMMonitoringService \
  --schematype Global \
  --adminid amadmin \
  --password-file /tmp/pwd.txt \
  --attributevalues iplanet-am-monitoring-enabled=true \
  iplanet-am-monitoring-rmi-enabled=true

A number of tools support JMX, including jvisualvm and jconsole. When you use jconsole to browse AM MBeans for example, the default URL for the AM running on the local system is service:jmx:rmi:///jndi/rmi://localhost:9999/server.

$ jconsole service:jmx:rmi:///jndi/rmi://localhost:9999/server &

You can also browse the MBeans by connecting to your web application container, and browsing to the AM MBeans. By default, JMX monitoring for your container is likely to be accessible only locally, using the process ID.

JConsole Browsing MBeans

Also see Monitoring and Management Using JMX for instructions on how to connect remotely, how to use SSL, and so forth.

You can configure AM to allow you to listen on port 8085 for SNMP monitoring.

Prometheus is third-party software used for gathering and processing monitoring data. AM exposes an endpoint which Prometheus uses to gather metrics from the AM instance. For more information about installing and running Prometheus, see the Prometheus documentation.

When enabled, AM makes the Prometheus-formatted metrics available at the /json/metrics/prometheus endpoint.

Configure Prometheus to monitor the AM endpoint, using the prometheus.yml configuration file. For more information on configuring Prometheus, see the Prometheus configuration documentation.

CREST is the ForgeRock Common REST API. AM exposes an endpoint which allows REST clients to gather information about your AM installation, in JSON format.

When enabled, AM makes the CREST-formatted metrics available at the /json/metrics/api endpoint.

Graphite is third-party software used for storing monitoring data, and rendering graphs of the data. For more information about installing and running Graphite, see the Graphite documentation.

Once activated, SNMP monitoring works over UDP by default. You may want to install one of many available network monitoring tools. For the purpose of this section, basic SNMP service and monitoring tools have been installed on a GNU/Linux system. The same commands should work on a Mac OS X system.

SNMP depends on labels known as Object Identifiers (OIDs). These are uniquely defined labels, organized in tree format. For AM, they are configured in a .mib file named FORGEROCK-OPENAM-CTS.mib, found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-6.5.5.jar file of the AM deployment.

For detailed information on configured OIDs, see "Core Token Service (CTS) Object Identifiers" in the Installation Guide.

With the OIDs in hand, you can set up an SNMP server to collect the data. You would also need SNMP utility commands with associated OIDs to measure the current state of a component. First, to verify the operation of SNMP on a GNU/Linux system, over port 8085, using SNMP version 2c, run the following command:

 # snmpstatus -c public -v 2c localhost

The output should normally specify communications over UDP. If you get a timeout message, the SNMP service may not be running.

You can get the value for a specific OID. For example, the following command would retrieve the cumulative count for CTS create operations, over port 8085:

# snmpget -c public -v 2c :8085 enterprises.36733.1.2.3.3.1.1.1

If your version of the tool does not support the enterprises OID string, use 1.3.6.1.4.1 instead, as in 1.3.6.1.4.1.36733.1.2.3.3.1.1.1.

For one view of the tree of OIDs, you can use the snmpwalk command. For example, the following command lists all OIDs related to CTS:

 # snmpwalk -c public -v 2c :8085 enterprises.36733.1.2.3

A number of CTS OIDs are listed with a Counter64 value. As defined in RFC 2578, an OID configured in this way has a maximum value of 2^64 - 1.

You can monitor policy evaluation performance over SNMP. AM records statistics for up to a number of recent policy evaluation requests. (You can configure the number in the AM console under Configuration > System > Monitoring. For details, see the reference section "Monitoring".

Interface Stability: Evolving in the Release Notes

As described in "CTS SNMP Monitoring", SNMP uses OIDs defined in the .mib file, FORGEROCK-OPENAM-POLICY.mib, found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-6.5.5.jar file of the AM deployment. This file specifies the statistics AM keeps for policy evaluation operations. Adapt the examples in "CTS SNMP Monitoring" to read monitoring statistics about policy evaluation on the command line.

When monitoring is active, AM records statistics about both the numbers and rates of policy evaluations performed, and also the times taken to process policy evaluations.

The statistics are all read-only. The base OID for policy evaluation statistics is enterprises.36733.1.2.2.1. The following table describes the values that you can read:

You can monitor CTS-based session statistics over SNMP. AM records statistics for up to a configurable number of recent sessions. (You can configure the number in the AM console under Configuration > System > Monitoring. For details, see the system configuration reference section, "Monitoring" in the Reference.)

SNMP monitoring is not available for client-based sessions.

Interface Stability: Evolving in the Release Notes

As described in "CTS SNMP Monitoring", SNMP uses OIDs defined in a .mib file that specifies the statistics AM keeps for policy evaluation operations, the FORGEROCK-OPENAM-SESSION.mib file. This file is found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-6.5.5.jar file of the AM deployment. Adapt the examples in "CTS SNMP Monitoring" to read monitoring statistics about sessions on the command line.

When monitoring is active, AM records statistics about both the numbers of internal, remote, and CTS sessions, and also the times taken to process sessions.

The statistics are all read-only. The base OID for session statistics is enterprises.36733.1.2.1. Times are expressed in nanoseconds rather than milliseconds, as many operations take less than one millisecond. The following table describes the values that you can read:

The following general points apply:

AM has two thread pools used to send notifications to clients. The Service Management Service (SMS) thread pool can be tuned in the AM console under Configure > Server Defaults > SDK > Data Store:

The session service has its own thread pool to send notifications to listeners about changes to CTS-based sessions. This is configured under Configure > Server Defaults > Session > Notification:

The Session Service has additional properties to tune, which are configured under Configure > Server Defaults > Session > Session Limits. The following suggestion applies to deployments using CTS-based sessions:

To change LDAP configuration store settings, navigate to Deployment > Servers > Server Name > Directory Configuration.

You can increase the number of connections used for connecting to CTS to increase throughput.

One connection is reserved for cleanup of expired CTS tokens. The remaining connections are allocated for CTS operations such that the number is equal to a power of two. Because of this, you should set the maximum number of connections to 2ⁿ+1, as in 9, 17, 33, 65, and so forth.

The default maximum number of connections to the CTS is 10. To alter the default, navigate to Deployment > Servers > Server Name > CTS > CTS Token Store, and alter the Max Connections property.

You may need to click the Inherit Value property to unlock the value for editing.

If you need to change the default CTS connection timeout, set the org.forgerock.services.datalayer.connection.timeout.cts.async property under Deployment > Servers > Server Name > Advanced.

Most CTS requests to the directory server are handled quickly, so the default timeout of 10 seconds is suitable in most cases.

You must restart AM or the container in which it runs for these changes to take effect.

To change external policy and application data store settings, navigate to Configure > Global Services > External Data Stores > Secondary Configurations > Store Name.

To change LDAP data store settings, navigate to Realms > Realm Name > Identity Stores > Identity Store Name in the AM console. Each store has its own connection pool—so each store needs its own tuning:

To change the various UMA-related data store settings, navigate to Deployment > Servers > Server Name.

To increase the number of connections used for the various UMA-related data stores, navigate to Deployment > Servers > Server Name > UMA > UMA Store Type, and alter the Max Connections property.

You may need to click the Inherit Value property to unlock the value for editing.

To change connection pool settings for the "LDAP Decision Node" in the Authentication and Single Sign-On Guide and LDAP Authentication Module in the Authentication and Single Sign-On Guide, in the AM console, go to Configure > Authentication > Core Attributes > Global Attributes.

By default, AM has caching enabled for configuration data and user data. This setting is governed by the server property com.iplanet.am.sdk.caching.enabled, which is true by default. If you set this advanced property to false, you can enable caching independently for configuration data and for user data.

The table below provides a quick reference, primarily for user data cache settings.

Notice that many properties for configuration data cache have sm (for Service Management) in their names, whereas those for user data have idm (for Identity Management) in their names:

To start a recording event, perform an HTTP POST using the /json/records endpoint, specifying the _action=start parameter in the URL. Specify a JSON payload identical in format to the input file for the ssoadm start-recording command, as described in "The Recording Control File".

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
--data ' {
  "issueID": 103572,
  "referenceID": "policyEvalFails",
  "description": "Troubleshooting artifacts in support of case 103572",
  "zipEnable": true,
  "configExport": {
   "enable": true,
   "password": "5x2RR70",
   "sharePassword": false
  },
  "debugLogs": {
   "debugLevel": "MESSAGE",
   "autoStop": {
    "time":  {
     "timeUnit": "SECONDS",
     "value": 15
    },
    "fileSize": {
     "sizeUnit": "GB",
     "value": 1
    }
   }
  },
  "threadDump" : {
   "enable": true,
   "delay" :  {
    "timeUnit": "SECONDS",
    "value": 5
   }
  }
 }' \
https://openam.example.com:8443/openam/json/records?_action=start
{
    "recording":true,
    "record":{
        "issueID":103572,
        "referenceID":"policyEvalFails",
        "description":"Troubleshooting artifacts in support of case 103572",
        "zipEnable":true,
        "threadDump":{
            "enable":true,
            "delay":{
                "timeUnit":"SECONDS",
                "value":5
            }
        },
        "configExport":{
            "enable":true,
            "password":"xxxxxx",
            "sharePassword":false
        },
        "debugLogs":{
            "debugLevel":"message",
            "autoStop":{
                "time":{
                    "timeUnit":"MILLISECONDS",
                    "value":15000
                },
                "fileSize":{
                    "sizeUnit":"KB",
                    "value":1048576
                }
            }
        },
        "status":"RUNNING",
        "folder":"/opt/demo/openam/config/openam/debug/record/103572/policyEvalFails/"
    }
}

To get the status of a recording event, perform an HTTP POST using the /json/records endpoint, specifying the _action=status parameter in the URL:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/records?_action=status

If there is no active recording event, the following output appears:

{
    "recording":false
}

If there is an active recording event, output similar to the following appears:

{
    "recording":true,
    "record":{
        "issueID":103572,
        "referenceID":"policyEvalFails",
        "description":"Troubleshooting artifacts in support of case 103572",
        "zipEnable":true,
        "threadDump":{
            "enable":true,
            "delay":{
                "timeUnit":"SECONDS",
                "value":5
            }
        },
        "configExport":{
            "enable":true,
            "password":"xxxxxx",
            "sharePassword":false
        },
        "debugLogs":{
            "debugLevel":"message",
            "autoStop":{
                "time":{
                    "timeUnit":"MILLISECONDS",
                    "value":15000
                },
                "fileSize":{
                    "sizeUnit":"KB",
                    "value":1048576
                }
            }
        },
        "status":"RUNNING",
        "folder":"/opt/demo/openam/config/openam/debug/record/103572/policyEvalFails/"
    }
}

To stop a recording event, perform an HTTP POST using the /json/records endpoint, specifying the _action=stop parameter in the URL:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/records?_action=stop

If there is no active recording event, AM returns a 400 error code.

If there is an active recording event, output similar to the following appears:

{
  "recording": false,
  "record": {
    "issueID": 103572,
    "referenceID": "policyEvalFails",
    "description": "Troubleshooting artifacts in support of case 103572",
    "zipEnable": true,
    "threadDump": {
      "enable": true,
      "delay": {
        "timeUnit": "SECONDS",
        "value": 5
      }
    },
    "configExport": {
      "enable": true,
      "password": "xxxxxx",
      "sharePassword": false
    },
    "debugLogs": {
      "debugLevel": "message",
      "autoStop": {
        "time": {
          "timeUnit": "MILLISECONDS",
          "value": 15000
        },
        "fileSize": {
          "sizeUnit": "KB",
          "value": 1048576
        }
      }
    },
    "status": "STOPPED",
    "folder": "/opt/demo/openam/config/openam/debug/record/103572/policyEvalFails/"
  }
}