How To

How do I invoke the OpenIDM 4.x REST API when OpenIDM is protected by OpenAM?

Last updated Jan 5, 2021

The purpose of this article is to provide information on invoking the REST API when OpenIDM is protected by OpenAM using the OPENAM_SESSION authentication module. You can still use this authentication module in IDM 5.x in certain circumstances (in which case the advice in this article applies), but typically you should use the OAUTH_CLIENT module (IDM 5.5) or the OPENID_CONNECT module (IDM 5) instead. The OPENAM_SESSION authentication module is deprecated as of IDM 5.5.

1 reader recommends this article

This article has been archived and is no longer maintained by ForgeRock.


In general, when OpenIDM is protected by OpenAM, an OpenIDM user should authenticate with credentials stored in the OpenAM's identity repository. The OpenAM servlet filter will intercept the authentication request and redirect the request to the OpenAM server. If the user's credentials match those in the OpenAM's repository, OpenAM will redirect the user back to OpenIDM.

Invoking the REST API via a browser

When a user is authenticated to OpenIDM via OpenAM, the user does not need to re-authenticate during a session when invoking the REST API providing the following is true:

  • The same browser is used to authenticate the user to OpenAM and make REST calls to OpenIDM.
  • The session is still valid.

In this scenario, OpenAM creates and maintains the session, and passes the browser cookie (with the authenticated user's credentials) to OpenIDM.

Invoking the REST API via curl

When using curl to invoke the REST API, you must explicitly pass the authenticated user's credentials as follows:

  1. Create policy rules in OpenAM to provide authenticated users with access to the OpenIDM REST endpoints in addition to the selfservice endpoints required. For example:**?***?*
  2. Restart both OpenAM and OpenIDM.
  3. Authenticate to OpenAM, for example: $ curl -X POST -H "X-OpenAM-Username: openidm-admin" -H "X-OpenAM-Password: openidm-admin" -H "Content-Type: application/json" Example response: { "tokenId": "AQIC5wM2LY4SfcxUm6wdixPGaSrucHNIH7haV14vmdkrRsU.*AAJTSQACMDE.*", "successUrl": "/openam/console", "realm": "/" }
  4. Pass the authenticated user's token in the iPlanetDirectoryPro header (default OpenAM session cookie name), along with the header "X-Requested-With: XMLHttpRequest", when performing operations that require authentication. For example: $ curl -b "iPlanetDirectoryPro=AQIC5wM2LY4SfcxUm6wdixPGaSrucHNIH7haV14vmdkrRsU.*AAJTSQACMDE.*" -H "X-Requested-With: XMLHttpRequest" ""

See Also

How does the OIDC authorization flow work when IDM (All versions) is integrated with AM?

How do I correctly configure the OPENAM_SESSION authentication module in OpenIDM 4.5?

How does the password reset flow work in IDM (All versions)?

OpenAM Developer's Guide › Authentication & Logou