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

How To

Last updated Nov 30, 2018

The purpose of this article is to provide information on some common issues encountered with REST calls in AM/OpenAM. It also provides some tips to help you troubleshoot issues and use REST more effectively.

1 reader recommends 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/protocol versions (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:

$ 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/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. See Authentication and Single Sign-On Guide › To Set the Default Authentication Tree or Chain for further information. 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

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/protocol versions

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

See Upgrade Guide › Review REST API Versions Before Upgrading for advice when upgrading.
See Development Guide › 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 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:

API Explorer - as of AM 5, you can use the API Explorer to locate REST API endpoints as detailed in Development Guide › Introducing the API Explorer.
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.

Note

These are third-party tools that we suggest can be used with REST calls but are not supported by ForgeRock.

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.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate

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.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate | jq .

Example response:

{
  "realm": "/",
  "successUrl": "/openam/console",
  "tokenId": "AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*"
}

Related Training

N/A

Related Issue Tracker IDs

N/A