How do I avoid common issues with REST calls in AM (All versions)?
The purpose of this article is to provide information on some common issues encountered with REST calls in AM. It also provides some tips to help you troubleshoot issues and use REST more effectively.
2 readers recommend this article
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.
Used the wrong session cookie name in the REST call
If you have changed your AM 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:
$ curl -s 'https://am.example.com:8443/am/json/serverinfo/*' | tr ',' '\n' | grep cookieName "cookieName":"iPlanetDirectoryPro"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 instance, which may not be the intended server. You can avoid this issue as follows:
- Always use the actual AM 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: https://am.example.com:8443/am/json/realms/root/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
You should include the Accept-API-Version header in your REST call with a valid resource version:
- See Review REST API versions before upgrading for advice when upgrading.
- See 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
* Connected to am.example.com (192.0.2.255) port 8080 (#0) > POST /am/json/authenticate HTTP/1.1 > User-Agent: curl/7.35.0 > Host: am.example.com:8443 > Accept: */* > Cache-Control: no-cache > Content-Type: application/json > X-OpenAM-Password: cangetinam > X-OpenAM-Username: amadmin > < HTTP/1.1 200 OK * Server Apache-Coyote/1.1 is not denylisted < Server: Apache-Coyote/1.1 < X-Frame-Options: SAMEORIGIN < Set-Cookie: amlbcookie=01; Domain=am.example.com; Path=/ < Set-Cookie: iPlanetDirectoryPro="AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*"; Domain=am.example.com; Path=/ < Cache-Control: no-cache, no-store, must-revalidate < Content-API-Version: resource=2.1 < Expires: 0 < Pragma: no-cache < Content-Type: application/json;charset=UTF-8 < Content-Length: 159 < Date: Wed, 25 Apr 2018 11:20:29 GMT < * Connection #0 to host am.example.com left intact {"tokenId":"AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*","successUrl":"/am/console","realm":"/"}Usage tips
The following suggestions will help you identify REST calls and improve usability:
- API Explorer - you can use the API Explorer to locate REST API endpoints as detailed in Online REST API reference.
- 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 Identity Cloud or 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 (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.
Note
These are third-party tools that we suggest can be used with REST calls but are not supported by ForgeRock.
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" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: {"tokenId":"AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*","successUrl":"/am/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" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice | jq .Example response: { "realm": "/", "successUrl": "/am/console", "tokenId": "AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*" }
See Also
Login to AM admin UI (All versions) fails for amAdmin user
How do I change the session cookie name for AM and Agents (All versions)?
Related Training
N/A
Related Issue Tracker IDs
N/A