How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How does the OIDC authorization flow work when IDM 5.5.x, 6.x or 7.x is integrated with AM?

Last updated Apr 26, 2021

The purpose of this article is to provide information on the OIDC authorization flow used when IDM is integrated with AM. This flow is used when you want to protect an IDM endpoint (custom or standard) with AM and are using either the rsFilter module (IDM 7 and later) or the OAUTH_CLIENT module (pre-IDM 7).


4 readers recommend this article

Overview

This article describes the OIDC authorization flows used to obtain the OIDC token that can then be passed to IDM in order to access an endpoint. The same concepts apply for standard and custom IDM endpoints. Follow the authorization flow applicable to your version to obtain an OIDC token for access when IDM is integrated with AM:

Integration

Note

If you are passing a session cookie in pre-IDM 7 (not applicable in this example), you will need to include the X-Requested-With header as discussed in Integrator's Guide › Using Message Level Security.

OIDC authorization flow (IDM 7 and later)

The following example demonstrates the OIDC authorization flow when using the standard idm-admin-ui client where the following example URLs are used:

  • IDM URL: idm.example.net:18080
  • AM URL: host1.example.com:28080
  1. Authenticate to AM as an admin user. For example:$ 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:28080/openam/json/realms/root/authenticate'Example response:{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  2. Obtain an authorization code from AM ensuring you specify the session token returned in the previous step in the Cookie header:$ curl -X GET -H 'Cookie: iPlanetDirectoryPro=AQIC5wM2LY4Sfcxs...EwNDU2NjE0*' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'state=xyz' 'http://host1.example.com:28080/openam/oauth2/authorize?response_type=code&client_id=idm-admin-ui&scope=openid fr:idm:*&redirect_uri=http://idm.example.net:18080/admin/appAuthHelperRedirect.html&state=xyz'Example response (note the code returned in the location header):HTTP/2 302 server: nginx/1.17.10 date: Mon, 26 Apr 2021 17:43:52 GMT  content-Length: 0 location: http://idm.example.net:18080/admin/appAuthHelperRedirect.html?code=sQ5jtgYmdTexe2VcLaWxj9lF1gI&iss=http://host1.example.com:28080/openam/oauth2&state=xyz&client_id=idm-admin-ui set-cookie: route=1595350461.029.542.7328; Path=/openam; Secure; HttpOnly x-Frame-Options: SAMEORIGIN  x-content-type-options: nosniff cache-control: no-store pragma: no-cache set-cookie: OAUTH_REQUEST_ATTRIBUTES=DELETED; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; HttpOnly
  3. Exchange the authorization code for an access token ensuring you specify the access code you obtained in the previous step in the code URL parameter:$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'code=sQ5jtgYmdTexe2VcLaWxj9lF1gI' --data-urlencode 'redirect_uri=http://idm.example.net:18080/admin/appAuthHelperRedirect.html' --data-urlencode 'client_id=idm-admin-ui' 'http://host1.example.com:28080/openam/oauth2/access_token'Example response:{ "access_token":"gr2d9v4mXwU-v3kMBacnwpKKtnE",  "scope":"openid fr:idm:*",  "id_token":"eyJ0eXAiOiJKV..sO4HYqlQ",  "token_type":"Bearer",  "expires_in":239 }

You can now use this access token to access IDM endpoints. For example, you could use it to query the managed/user object:

$ curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer gr2d9v4mXwU-v3kMBacnwpKKtnE' 'http://idm.example.net:18080/openidm/managed/user?_queryFilter=true'

OIDC authorization flow (Pre-IDM 7)

The following example demonstrates the OIDC authorization flow where the following example URLs are used:

  • IDM URL: idm.example.net:8081
  • AM URL: host1.example.com:8080

Example

  1. Send a request to IDM: $ curl -X POST -H 'Content-Type: application/json' -H 'X-OpenIDM-Username: anonymous' -H 'X-OpenIDM-Password: anonymous' -H 'X-OpenIDM-NoSession: true' -d '{   "provider":"OPENAM",    "landingPage":"http://idm.example.net:8081/#login/&oauthReturn=true&provider=OPENAM&gotoURL=%23" }' 'http://idm.example.net:8081/openidm/identityProviders?_action=getAuthRedirect'Example response; this includes a long token value which you should save for step 4: {"redirect":"http://host1.example.com:8080/openam/oauth2/authorize?nonce=74881rqrqjtw4cq7exjhzb9tjeo4vbc&response_type=code&client_id=openidm&redirect_uri=http://idm.example.net:8081/oauthReturn/&scope=openid&state=99iu3pclpz8ub9buogfp4geznl0ax5c","token":"ey...<long token>...cnF0"}
  2. Send the following request to authenticate to AM (note the AM username and password): $ curl -X POST -H "Content-Type: application/json" -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Accept-API-Version: resource=2.1" 'http://host1.example.com:8080/openam/json/realms/root/authenticate'Example response: {"tokenId":"aXuK02gnIwq_2rJacbNqob_QWC8.*AAJTSQACMDEAAlNLABxZeU5DZGhPTm8yVlBBVEx5eW9DZWpIVzh6R0k9AAJTMQAA*","successUrl":"/openam/console","realm":"/"}
  3. Send the following request to AM to obtain an authorization token, ensuring you replace the nonce and state values with the ones returned in step 1: $ curl -v -H 'Cookie: iPlanetDirectoryPro=aXuK02gnIwq_2rJacbNqob...JTMQAA*' 'http://host1.example.com:8080/openam/oauth2/authorize?nonce=74881rqrqjtw4cq7exjhzb9tjeo4vbc&response_type=code&client_id=openidm&redirect_uri=http%3A%2F%2Fidm.example.net%3A8081%2FoauthReturn%2F&scope=openid&state=99iu3pclpz8ub9buogfp4geznl0ax5c'Example response (note the Location header): < HTTP/1.1 302 Found < X-Frame-Options: SAMEORIGIN  < Pragma: no-cache  < Cache-Control: no-store  < Date: Mon, 15 Jan 2018 16:00:25 GMT  < Accept-Ranges: bytes  < Location: http://idm.example.net:8081/oauthReturn/?code=3d69820b-452a-49a9-bf55-22c4c3c588ac&scope=openid&iss=http%3A%2F%2Fhost1.example.com%3A8080%2Fopenam%2Foauth2&state=99iu3pclpz8ub9buogfp4geznl0ax5c&client_id=openidm  < Server: Restlet-Framework/2.3.4  < Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept  < Content-Length: 0
  4. Send the following request to IDM, ensuring you set the X-OpenIDM-DataStoreToken header to the long token value returned in step 1, replace the code value with the one returned in step 3 and replace the state value with the one returned in step 1: $ curl -X POST -H 'Content-Type: application/json' -H 'X-OpenIDM-Username: anonymous' -H 'X-OpenIDM-Password: anonymous' -H 'X-OpenIDM-NoSession: true' -H 'X-OpenIDM-DataStoreToken: ey...<long token>...cnF0' -d '{  "code":["3d69820b-452a-49a9-bf55-22c4c3c588ac"],   "scope":["openid"],   "iss":["http://host1.example.com:8080/openam/oauth2"],   "state":["99iu3pclpz8ub9buogfp4geznl0ax5c"],   "client_id":["openidm"] }' 'http://idm.example.net:8081/openidm/identityProviders?_action=handlePostAuth'Example response: {"landingPage":"http://idm.example.net:8081/#login/&oauthReturn=true&provider=OPENAM&gotoURL=%23","data":null,"token":"eyJ...<BIG JWT>...2hk"}
  5. Send the following request to IDM, ensuring you set the X-OpenIDM-DataStoreToken header to the JWT value returned in step 4: $ curl -H 'Content-Type: application/json' -H 'X-OpenIDM-OAuth-Login: true' -H 'X-OpenIDM-DataStoreToken:eyJ...<BIG JWT...2hk' -H 'Referer: http://idm.example.net:8081/' 'http://idm.example.net:8081/openidm/managed/user/b4acc4e1-365d-4684-85e1-09c27e26725b'Successful response: {"_id":"b4acc4e1-365d-4684-85e1-09c27e26725b","_rev":"00000000b775e5e0","displayName":"demo","givenName":"demo","mail":"demo@example.com","telephoneNumber":"12345","sn":"demo","userName":"demo","kbaInfo":[],"accountStatus":"active","lastChanged":{"date":"2017-12-18T12:44:58.269Z"},"effectiveRoles":[],"effectiveAssignments":[]}

See Also

Security Guide › Authentication and Session Modules

OAuth 2.0 Guide › Authorization Code Grant

Building an SSO Client for Your REST APIs with OIDC

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-10455 (query and non-read operations not authorised for openidm-admin role when OAuth)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.