How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 13, 2021

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 'http://host1.example.com:8080/openam/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: http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice?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:

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 host1.example.com (192.0.2.255) port 8080 (#0) > POST /openam/json/authenticate HTTP/1.1  > User-Agent: curl/7.35.0  > Host: host1.example.com:8080  > 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 blacklisted  < Server: Apache-Coyote/1.1  < X-Frame-Options: SAMEORIGIN  < Set-Cookie: amlbcookie=01; Domain=host1.example.com; Path=/  < Set-Cookie: iPlanetDirectoryPro="AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*"; Domain=host1.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 host1.example.com left intact {"tokenId":"AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*","successUrl":"/openam/console","realm":"/"}

Usage tips

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

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

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

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

Security Guide

Related Training

N/A

Related Issue Tracker IDs

N/A



Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.
Loading...