How To

ForgeRock Identity Platform

Does not apply to Identity Cloud

How do I perform common OAuth 2.0 tasks using curl commands with the standard endpoints in AM (All versions)?

Last updated Feb 21, 2023

The purpose of this article is to provide information on performing common OAuth 2.0 tasks using curl commands with the standard OAuth 2.0 endpoints in AM. 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.

3 readers recommend this article

Overview

The following OAuth 2.0 endpoints are used in AM:

Endpoint	Description	Standard
/oauth2/par	Used to register a pushed authorization request and get a request URI.	RFC 9126
/oauth2/authorize	Used to obtain consent and an authorization grant.	RFC 6749
/oauth2/bc-authorize	Used to initiate backchannel authorization.	OpenID Connect Client Initiated Backchannel Authentication Flow (draft)
/oauth2/access_token	Used to obtain an access token.	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 consent and an authorization grant.	OAuth 2.0 Device Flow for Browserless and Input Constrained Devices (draft)
/oauth2/token/revoke	Used by administrators to 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
/json/token/macaroon	Used to retrieve metadata about a macaroon and add caveats.

See OAuth 2.0 endpoints for further information and additional examples.

Additionally, there are four grant types defined by RFC 6749, which determine how requests are made. This article provides example curl commands and/or URLs for the different flows associated with the four grant types defined by RFC 6749:

Authorization code grant
Implicit grant
Resource owner password credentials grant
Client credentials grant

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.

See Authorization code grant for further information.

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):

https://am.example.com:8443/am/oauth2/authorize?response_type=code&client_id=myClientID&redirect_uri=https://example.com/oauth

Example response:

HTTP/1.1 302 Found Location: https://example.com:443/oauth?code=7rQNrZ2CpyA8dshIJFn8SX43dAk&scope=openid%20profile&iss=https%3A%2F%2Fam.example.com%3A8443%2Fam%2Foauth2&state=af0ifjsldkj&client_id=myClientID

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=https://example.com/oauth&client_id=myClientID&client_secret=myClientPassword" https://am.example.com:8443/am/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" https://am.example.com:8443/am/oauth2/access_token

Example response (where the access token returned is different from 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.

See Implicit grant for further information.

Requesting authorization

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):

https://am.example.com:8443/am/oauth2/authorize?response_type=token&client_id=myClientID&redirect_uri=https://example.com/oauth

Example response:

HTTP/1.1 302 Found Location: https://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.

See Resource owner password credentials grant for further information.

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" https://am.example.com:8443/am/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

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" https://am.example.com:8443/am/oauth2/access_token

Example response (where the access token returned is different from 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.

See Client credentials grant for further information.

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" https://am.example.com:8443/am/oauth2/access_token

Example response:

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

Related Training

Extending Services using OAuth 2.0-Based Protocols

Related Issue Tracker IDs

N/A