How To
Archived

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

Last updated Apr 12, 2021

The purpose of this article is to provide information on performing common OAuth 2.0 tasks using curl commands with the standard OAuth2 endpoints in AM/OpenAM. This article provides example curl commands for common use cases including requesting authorization, requesting an access token and refreshing an access token across the different OAuth 2.0 grant types. It also provides an example curl command for checking an OAuth access token is still valid.


3 readers recommend this article

Archived

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

Overview

Note

For AM 6 and later, you should refer to the documentation for details of all the OAuth 2.0 grant flows that AM supports: OAuth 2.0 Guide › OAuth 2.0 Grant Flows.

The following OAuth2 endpoints are used in AM/OpenAM:

Endpoint Description Standard
/oauth2/authorize Used to obtain an authorization grant from the resource owner. RFC 6749 
/oauth2/access_token Used to obtain an access token from the authorization server. RFC 6749 
/oauth2/device/code Used by a client device to obtain a device code. OAuth 2.0 Device Flow for Browserless and Input Constrained Devices (draft) 
/oauth2/device/user Used by a client device to obtain an access token. OAuth 2.0 Device Flow for Browserless and Input Constrained Devices (draft) 
/oauth2/token/revoke Lets administrators revoke access and refresh tokens. RFC 7009 
/oauth2/introspect Used to retrieve metadata about a token, such as approved scopes and the context in which the token was issued. RFC 7662 
/frrest/oauth2/token (legacy)

Lets administrators read, list, and delete OAuth 2.0 tokens and includes information such as the creator of the token.

This endpoint is deprecated in AM 5 and later; you should use the /oauth2/introspect and /oauth2/token/revoke endpoints instead.

N/A
/oauth2/tokeninfo (legacy) Used to validate tokens and to retrieve information about the token such as scopes. N/A

You should refer to OAuth 2.0 Guide › OAuth 2.0 Client and Resource Server Endpoints for further information and examples for the endpoints that are not defined in RFC 6749.  

Caution

The /oauth2/authorize endpoint requires the csrf parameter in AM and OpenAM 13.5.x. The csrf parameter should equal the iPlanetDirectoryPro cookie value. See Development Guide › Cross-Site Request Forgery (CSRF) Protection for further information.

Additionally, there are four grant types defined by RFC 6749, which determine how requests are made. The flows associated with these grant types are illustrated in OAuth 2.0 Guide › OAuth 2.0 Authorization Server.

This article provides example curl commands and/or URLs for the different flows associated with the four grant types defined by RFC 6749. It also provides an example for checking that an OAuth access token is still valid using the legacy /oauth2/tokeninfo endpoint. See OAuth 2.0 Guide › /oauth2/introspect for information on using the /oauth2/introspect endpoint instead. 

Authorization Code Grant

The authorization code grant type is used to obtain both access tokens and refresh tokens. Upon requesting authorization, a short-lived authorization code is returned, which can be used to obtain the access token. Example URLs and/or curl commands for the requests you can issue with this grant type are detailed below.

Requesting authorization

The parameters defined in RFC 6749 for requesting authorization are shown in the Authorization Request section of the RFC. As can be seen from the RFC, the response_type and client_id are required parameters.

The user should be sent to a URL such as the following in order that they can authenticate and give their consent (bypassing consent is against the standard): 

http://host1.example.com:8080/openam/oauth2/authorize?response_type=code&client_id=myClientID&redirect_uri=http://example.com/oauth

Example response:

HTTP/1.1 302 Found Location: http://example.com:8080/oauth?code=7rQNrZ2CpyA8dshIJFn8SX43dAk&scope=openid%20profile&iss=http%3A%2F%2Fhost1.example.com%3A8080%2Fopenam%2Foauth2&state=af0ifjsldkj&client_id=myClientID
Note

There is a RFE to reduce the number of query parameters returned: OPENAM-13204 (OAuth2 Authorization Response - Additional query parameters are added in the redirect_URI). Per RFC 6749, the required code parameter is returned and any extra parameters will be ignored.

Requesting an access token

The parameters defined in RFC 6749 for requesting an access token for a user are shown in the Access Token Request section of the RFC. As can be seen from the RFC, the grant_type, code, redirect_uri and client_id are required parameters. client_secret is also required to allow the client to authenticate with the authorization server.

For example, to request an access token, you would use a curl command such as the following (where code is the authorization code you received when you requested authorization):

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&redirect_uri=http://example.com/oauth&client_id=myClientID&client_secret=myClientPassword" 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":"238beab2-b545-4fee-80fa-63f224bc56f6"}

Refreshing an access token

The parameters defined in RFC 6749 for refreshing an access token are shown in the Refreshing an Access Token section of the RFC. As can be seen from the RFC, the grant_type and refresh_token are required parameters. client_id and client_secret are also required to allow the client to authenticate with the authorization server.

For example, to refresh an existing access token, you would use a curl command such as the following (where refresh_token is the refresh_token you received when you requested the access token):

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=534310ab-570b-4eb4-0ed7-d01d243fae21&client_id=myClientID&client_secret=myClientPassword" http://host1.example.com:8080/openam/oauth2/access_token

Example response (where access token returned is different to the one initially returned when requesting the access token):

{"scope":"cn","expires_in":599,"token_type":"Bearer","access_token":"fd473223-8b1b-1b94-4f80-96923daa3237"}​

Implicit Grant

The implicit grant type is used to obtain an access token. This is a simplified flow compared to the authorization code grant type as an access token is issued immediately, although this can be considered less secure as the client is not authenticated. An example URL that can be used for the authorization request with this grant type is detailed below.

Requesting authorization

The parameters defined in RFC 6749 for requesting authorization are shown in the Authorization Request section of the RFC. As can be seen from the RFC, the response_type and client_id are required parameters.

The user should be sent to a URL such as the following in order that they can authenticate and give their consent (bypassing consent is against the standard): 

http://host1.example.com:8080/openam/oauth2/authorize?response_type=token&client_id=myClientID&redirect_uri=http://example.com/oauth

Example response:

HTTP/1.1 302 Found Location: http://example.com/oauth/#token_type=Bearer&expires_in=599&access_token=fd473223-8b1b-1b94-4f80-96923daa3237

Resource Owner Password Credentials Grant

The resource owner password credentials grant type is used to obtain both access tokens and refresh tokens. Username and password are used to obtain the access token directly. This grant type should only be used when other grant types are not available and there is a great deal of trust between the resource owner and the client. Example curl commands for the requests you can issue with this grant type are detailed below.

Requesting an access token

The parameters defined in RFC 6749 for requesting an access token for a user are shown in the Access Token Request section of the RFC. As can be seen from the RFC, the grant_type, username and password are required parameters.

For example, to request an access token, you would use a curl command such as the following:

$ 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":"238beab2-b545-4fee-80fa-63f224bc56f6"}
Note

There is a known issue, which means you must set the Token Endpoint Authentication Method to client_secret_post if you use scope=openid%20profile with the resource owner password credentials grant type. See invalid_client error when requesting an OAuth 2.0 access token in AM (All versions) for further details.

Refreshing an access token

The parameters defined in RFC 6749 for refreshing an access token are shown in the Refreshing an Access Token section of the RFC. As can be seen from the RFC, the grant_type and refresh_token are required parameters.

For example, to refresh an existing access token, you would use a curl command such as the following (where refresh_token is the refresh_token you received when you requested the access token):

$ curl -X POST -u "myClientID:password" -d "grant_type=refresh_token&refresh_token=534310ab-570b-4eb4-0ed7-d01d243fae21" http://host1.example.com:8080/openam/oauth2/access_token

Example response (where access token returned is different to the one initially returned when requesting the access token):

{"scope":"cn","expires_in":599,"token_type":"Bearer","access_token":"fd473223-8b1b-1b94-4f80-96923daa3237"}​

Client Credentials Grant

The client credentials grant type is used to obtain an access token. Client credentials are used to obtain the access token directly. An example curl command for the access token request you can issue with this grant type is detailed below.

Requesting an access token

The parameters defined in RFC 6749 for requesting an access token for a client are shown in the Access Token Request section of the RFC. As can be seen from the RFC, the grant_type is the only required parameter.

For example, to request an access token, you would use a curl command such as the following:

$ curl -X POST -u "myClientID:password" -d "grant_type=client_credentials" http://host1.example.com:8080/openam/oauth2/access_token

Example response:

{"scope":"cn","expires_in":599,"token_type":"Bearer","access_token":"238beab2-b545-4fee-80fa-63f224bc56f6"}

Checking an OAuth access token is valid (legacy)

You can use the legacy /oauth2/tokeninfo endpoint to validate an access token. For example, you would use a curl command such as the following:

$ curl -k 'http://host1.example.com:8080/openam/oauth2/tokeninfo?access_token=238beab2-b545-4fee-80fa-63f224bc56f6'

Example response:

{"scope":["cn"],"grant_type":"password","cn":"demo","realm":"/","token_type":"Bearer","expires_in":40,"access_token":"238beab2-b545-4fee-80fa-63f224bc56f6"}

See Also

FAQ: OAuth 2.0 in Identity Cloud and AM

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

How do I bypass the OAuth 2.0 Authorization Consent page in OpenAM 13.x?

invalid_client error when requesting an OAuth 2.0 access token in AM (All versions)

OAuth 2.0 Guide

The OAuth 2.0 Authorization Framework - RFC6749

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13204 (OAuth2 Authorization Response - Additional query parameters are added in the redirect_URI)


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