How To
Archived

How do I request further information (such as client_id or uid) for an OAuth 2.0 access token in OpenAM 13.x?

Last updated Jan 5, 2021

The purpose of this article is to provide assistance with requesting further information such as client_id or uid (userName) for an OAuth 2.0 access token in OpenAM. The response returned with the openam/oauth2/tokeninfo endpoint does not include this information by default.


1 reader recommends this article

Archived

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

Overview

An access token can either be obtained by a user or by an admin on behalf of a user; the approach you take depends on your workflow and which grant type you use.

This article gives examples of a user requesting an access token directly as well as examples of an admin performing the whole process, including obtaining an access token on behalf of a user.

AM 5 and later

The endpoints referred to in this article (/frrest/oauth2/token and /openam/oauth2/tokeninfo) are legacy endpoints. You should use the /oauth2/introspect endpoint instead in AM 5 and later. This endpoint is defined by RFC 7662 and returns these additional details by default. See OAuth 2.0 Guide › /oauth2/introspect for further information.

Obtaining an access token (user)

The following examples show the implicit grant type being used to obtain an access token. You can use other grant types as shown in How do I perform common OAuth 2.0 tasks using curl commands with the standard endpoints in AM 5.x and OpenAM 13.x?

Top level realm

You can send a user to a URL such as the following in order to obtain an access token: 

http://host1.example.com:8080/oauth2/authorize?response_type=token&client_id=myClientID&scope=cn&redirect_uri=http://www.forgerock.com

Example response:

https://www.forgerock.com/#scope=cn&token_type=Bearer&expires_in=3599&access_token=e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a

Subrealms

You can send a user to a URL such as the following in order to obtain an access token if they authenticated to a subrealm: 

http://host1.example.com:8080/oauth2/test/authorize?response_type=token&client_id=myClientID&scope=cn&redirect_uri=http://www.forgerock.com

Requesting further information about an access token

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

If you want to find out more about an access token (such as the client_id or userName) in the top level realm, you can use the ForgeRock specific endpoint: openam/frrest/oauth2/token. This endpoint is for administrators, meaning you must authenticate first in order to obtain a SSOToken:

  1. Authenticate as an admin user. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate?authIndexType=service&authIndexValue=adminconsoleservice Example response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  2. Request an access token on behalf of a user using the following curl command with the resource owner password credentials grant type (ignore this step if the user has obtained the access token themselves): $ curl -X POST -u "myClientID:password" -d "grant_type=password&username=jdoe&password=changeit&scope=cn" http://host1.example.com:8080/openam/oauth2/access_token Example response: {"scope":"cn","expires_in":599,"token_type":"Bearer","refresh_token":"534310ab-570b-4eb4-0ed7-d01d243fae21","access_token":"e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a"}
  3. Request information about the token using one of the following curl commands: $ curl -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/frrest/oauth2/token/e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a Example response: {"_id":"id","_rev":"1465836044372","tokenName":["access_token"],"expireTime":["1465839520553"],"scope":["cn"],"grant_type":["password"],"clientID":["myClientID"],"parent":[],"id":["e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a"],"tokenType":["Bearer"],"auditTrackingId":["988a5d7f-1639-494f-abdf-7729e4f92a6a"],"realm":["/"],"nonce":[],"redirectURI":["http://www.forgerock.com"],"userName":["jdoe"]}

Subrealms

If you are querying an access token that exists for a user who authenticated to a subrealm and want to retrieve their user name, you will need to use openam/oauth2/tokeninfo endpoint but include the uid scope in both the OAuth provider configuration (Supported Scopes and Default Client Scopes) and the client configuration (Default Scopes and Scopes). See Reference › OAuth2 Provider and Administration Guide › Configuring OpenAM as Authorization Server and Client for further details on setting these scopes.

You can then use a curl command such as the following:

$ curl 'http://host1.example.com:8080/openam/oauth2/tokeninfo?access_token=e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a'

Example response:

{"uid":"demo","scope":["uid","cn"],"grant_type":"token","cn":"Demo User","realm":"/test","token_type":"Bearer","expires_in":3576,"access_token":"e1c9cf2f-6dd8-4f5e-8f0a-75671f6c132a"}

See Also

How do I perform common OAuth 2.0 tasks using curl commands with the standard endpoints in AM 5.x and OpenAM 13.x?

How do I improve OAuth 2.0 performance in OpenAM 13.0?

FAQ: OAuth 2.0 in Identity Cloud and AM

Reference › OAuth2 Provider

Administration Guide › Configuring OpenAM as Authorization Server and Client

Developer's Guide › OAuth 2.0 Client and Resource Server Endpoints

Related Training

N/A

Related Issue Tracker IDs

N/A


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