How do I avoid common issues with REST calls in AM/OpenAM (All versions)?

Common issues

The following common issues (with solutions) are seen when using REST calls:

• Used the wrong session cookie name in the REST call.
• Made the REST call to the load balancer URL.
• Used the wrong authenticate endpoint in the REST call.
• Excluded the Accept-API-Version header and/or used the wrong resource version (AM 5 and later).

Used the wrong session cookie name in the REST call

If you have changed your AM/OpenAM session cookie name as recommended for securing your installation, you will need to use the new cookie name in REST calls. For example, if your new cookie is called exampleCookie, you would change the following header in your REST calls:

• From: -H "iPlanetDirectoryPro: AQIC5..."
• To: -H "exampleCookie: AQIC5..."

If you are unsure what your session cookie name is, you can check it with the following REST call:

Made the REST call to the load balancer URL

If you make a REST call to the load balancer URL, the call can go to any AM/OpenAM instance, which may not be the intended server. You can avoid this issue as follows:

• Always use the actual AM/OpenAM server (FQDN) URL in your REST call to ensure the call goes to the correct instance (recommended).
• Add the following cookie header to your REST call to identify the required instance providing your load balancer uses session stickiness (amlbcookie): -H "Cookie: amlbcookie=<serverid>"

Used the wrong authenticate endpoint in the REST call 

If you have changed the Organization Authentication Configuration setting from ldapService to a non-DataStore module based chain, the amAdmin user will not be able to authenticate using the /authenticate endpoint as they must authenticate via the DataStore module. This issue may also affect you if you use a DNS name to map to a different realm.

To ensure the amAdmin user can authenticate in this scenario, you must append the /authenticate endpoint with ?authIndexType=service&authIndexValue=adminconsoleservice. For example:

• AM 5 and later: http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice?authIndexType=service&authIndexValue=adminconsoleservice
• Pre-AM 5: http://host1.example.com:8080/openam/json/authenticate?authIndexType=service&authIndexValue=adminconsoleservice 

The adminconsoleservice service uses the authentication chain defined for the administrator (Administrator Authentication Configuration).

Excluded the Accept-API-Version header and/or used the wrong resource version

In AM 5 and later, you should include the Accept-API-Version header in your REST call with a valid resource version:

• See Upgrade Guide › Reviewing REST API Versions Before Upgrading for advice when upgrading.
• See Getting Started with REST › Supported REST API Versions for your version of AM to check what versions are supported.

Troubleshooting tips

When you use curl for REST calls, there are a couple of useful options you can include for troubleshooting:

• -v, --verbose - the verbose option provides useful debugging information to help you understand what is happening with your curl command.
• -k, --insecure - the insecure option is useful when you have SSL/TLS enabled (HTTPS) and want to eliminate connection issues as a result of certificates etc. By using this option, curl will connect to your server using an insecure connection. In this way, you can isolate whether you are experiencing issues with SSL connectivity or more general issues with your curl command.

See curl.1 man page for further information on all the available curl options.

Example verbose output when authenticating over REST

Usage tips

The following suggestions will help you identify REST calls and improve usability:

• API Explorer - as of AM 5, you can use the API Explorer to locate REST API endpoints as detailed in Getting Started with REST › REST API Explorer.
• Browser Developer Tools - you can use the Developer Tools in your browser to copy a web request as a curl command and replay it on the command line. See How do I understand the underlying REST call being used in web requests in AM (All versions)? for further information.
• Postman - you can use Postman to make REST calls, which allows you swap parameters easily and save commonly used calls. ForgeRock provides some Postman collections for its customers to use to perform tasks as detailed in How do I use the Postman collections that are provided for AM/OpenAM (All versions)? (this article is only available to customers/partners).
• jq - you can use jq on the command line in conjunction with curl commands to parse the JSON response. One of the most common uses is to prettify the response for readability.

jq

You can install jq as outlined in Download jq.

The simplest jq option is to prettify a response on the command line by adding | jq . at the end of the command. Consider the following examples:

• Standard curl command: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice Example response: {"tokenId":"AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*","successUrl":"/openam/console","realm":"/"} 
• Curl command with jq pretty-print option: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice | jq . Example response: {    "realm": "/",    "successUrl": "/openam/console",    "tokenId": "AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*"  }

See Also

Using the REST API in AM/OpenAM

Login to AM/OpenAM console (All versions) fails for amAdmin user

How do I change the session cookie name for AM/OpenAM and Agents (All versions)?

Security Guide

Related Training

N/A

Related Issue Tracker IDs

N/A