Resource owner password credentials grant

Endpoints

/oauth2/access_token

The resource owner password credentials (ROPC) grant flow lets the client use the resource owner’s username and password to get an access token.

Because the resource owner shares their credentials with the client, this flow is deemed the most insecure of the OAuth 2.0 flows. The resource owner’s credentials can potentially be leaked or abused by the client application, and the resource owner has no control over the authorization process.

Only implement the ROPC grant flow if the resource owner has a trusted relationship with the client, such as when the client is part of the device operating system or a highly privileged application.

The ROPC grant flow

Figure 1. OAuth 2.0 ROPC grant flow

The resource owner provides the client with their username and password.
The client sends the resource owner’s and its own credentials to the authorization server, which authenticates the credentials and authorizes the resource owner’s request.
If the credentials are valid, the authorization server returns an access token to the client.
The client requests access to the protected resource presenting the access token to the resource server.
The resource server contacts the authorization server to validate the access token.
The authorization server validates the token and responds to the resource server.
If the token is valid, the resource server allows the client to access the protected resource.

Demonstrate the ROPC grant flow

Perform these steps to get an access token:

Prepare the demonstration
Define an ROPC authentication service
Get an access token using the ROPC grant flow

Prepare the demonstration

This demonstration assumes the following configuration:

AM is configured as an OAuth 2.0 authorization server.

Make sure the Resource Owner Password Credentials grant type is configured in the Grant Types field.

For more information, refer to Authorization server configuration.
A confidential client called myClient is registered in AM with the following configuration:
- Client secret: forgerock
- Scope(s): write
- Grant Types: Resource Owner Password Credentials
For more information, refer to Client application registration.

Define an ROPC authentication service

Configure AM to use a tree or chain that can authenticate a resource owner without UI-based interaction, such as the ldapService chain (default), or the Example tree.

Specify the tree or chain by using one or more of the methods below. AM checks for the configured value in the following order, using the first value found:

For a specific access token REST request.

Set the auth_chain parameter.
Individually for a realm, overriding the realm-level setting below.

Go to Realms > Realm Name > Services > OAuth2 Provider > Advanced, and set the Password Grant Authentication Service property.
Individually for a realm.

Go to Realms > Realm Name > Authentication > Settings > Core, and set the Organization Authentication Configuration property.
Globally, for all realms.

Go to Configure > Authentication > Core Attributes > Core, and set the Organization Authentication Configuration property.

For more information, see Configure sensible default authentication services.

Get an access token using the ROPC grant flow

The resource owner provides their credentials to the client. This is done outside the scope of this procedure.
As the client, call /oauth2/access_token specifying the resource owner’s and the client’s credentials, and grant_type=password.

Confidential clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:
- client_id=your-client-id
- client_secret=your-client-secret
For more information, refer to OAuth 2.0 client authentication.

If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /alpha realm, then use /oauth2/realms/root/realms/alpha/access_token.

For example:
$ curl \ --request POST \ --data "grant_type=password" \ --data "username=<resource-owner-username>" \ --data "password=<resource-owner-password>" \ --data "scope=write" \ --data "client_id=myClient" \ --data "client_secret=forgerock" \ "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
The scope parameter is optional if default values are configured in the authorization server or the client.

The authorization server returns an access token, for example:
{ "access_token": "<access-token>", "scope": "write", "token_type": "Bearer", "expires_in": 3599 }
The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, refer to Refresh tokens.