Access Management 7.3.2

Resource owner password credentials grant

Endpoints

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

Since 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.

You should implement the ROPC grant flow only if the resource owner has a trust relationship with the client (such as the device operating system, or a highly privileged application).

OAuth 2.0 Resource Owner Password Credentials Grant Flow
Figure 1. OAuth 2.0 Resource Owner Password Credentials Grant Flow
ROPC grant flow explained

  1. The resource owner provides the client with their username and password.

  2. 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.

  3. If the credentials are valid, the authorization server returns an access token to the client.

  4. The client requests access to the protected resources presenting the access token to the resource server.

  5. The resource server contacts the authorization server to validate the access token.

  6. The authorization server validates the token and responds to the resource server.

  7. If the token is valid, the resource server allows the client to access the protected resources.

Perform the following procedure to obtain an access token:

Obtain an access token using the ROPC grant flow

This procedure assumes the following configuration:

  • An authentication service that is able to authenticate a username and password combination, without requiring any UI-based interaction from the resource owner, is available.

    For example, the ldapService chain (the 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:

    1. For a specific access token REST request.

      Set the auth_chain parameter.

    2. 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.

    3. Individually for a realm.

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

    4. 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.

  • AM is configured as an OAuth 2.0 authorization server. Ensure that:

    • The Resource Owner Password Credentials grant type is configured in the Grant Types field.

    For more information, see Authorization server configuration.

  • A confidential client called myClient is registered in AM with the following configuration:

    • Client secret: forgerock

    • Scopes: write

    • Grant Types: Resource Owner Password Credentials

For more information, see Client application registration.

Perform the following steps to obtain an access token using the ROPC grant flow:

  1. The resource owner provides their credentials to the client. This is done outside the scope of this procedure.

  2. The client creates a POST request to the authorization server’s token endpoint specifying, at least, the following parameters:

    • username=your-resource-owner-username

    • password=your-resource-owner-password

    • grant_type=password

      For information about the parameters supported by the /oauth2/access_token endpoint, see /oauth2/access_token.

      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, see 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=demo" \
--data "password=Ch4ng31t" \
--data "scope=write" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"

    Note that the scope parameter has been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example.

    The authorization server returns an access token in the access_token property. For example:

    {
  "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
  "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, see Refresh tokens.