Resource Owner Password Flow

Resource Owner Password Flow

operate

Using the Resource Owner Password Credential Flow

The Resource Owner Password Credential (ROPC) flow is one of the standard flows defined in OAuth.1 Unlike some of the other standard flows, it is a very straightforward request and response. The client simply makes a call to the OAuth server's token endpoint and gets tokens in the response. It is a sort of "login" API, if you will.

Pre-requisites

This tutorial builds on the configuration setup in the "Setup and Getting Started" section and the "Setup a Username Authenticator". If you haven't done those steps yet you can visit those guides here:

It's possible to run this tutorial on a custom setup also, but the URLs may be different, as well as the capabilities configured in the profiles.

Overview

Token Endpoint

Client Credentials Flow

  1. The Client makes a POST request to the OAuth Server
  2. The OAuth Server issues the tokens immediately and responds to the client

In this flow, the client firstly collects the Resource Owner's credentials, and then sends them to the OAuth server. When it does this, it also includes its own credentials. The request is a HTTP POST with the client's credentials either in the body or in an Authorization header. The server then responds with an access token, and, optionally, a refresh token.

Setup in Curity

Visit the Profiles screen and click the Token Service.

Set Credential store for Resource Owner Flow

On the general page scroll down to Client Capabilities and under Resource Owner Password Credentials select the default-credential-manager as credential manager.

Credential Store

New Client

On the menu to the right click Clients and on the client listing page click New.

Give the client an ID (eg. legacy for a legacy client).

New Client

Capabilities

Scroll down to the Capabilities section and click Add capabilities.

Capabilities

Select the Resource Owner Password Flow capability and click Next.

Capabiltiy

Client Authentication

For client authentication select secret and enter a secret. Make sure to remember it since it cannot be retrieved later again (but can be reset).

Secret

Set a Scope (Optional)

It's not required for a client to have a scope, but often useful. To set a new scope on the client and to create the scope at the same time, scroll to OAuth/OpenID Settings and select a scope or click New Scope and enter the new scope value below and click Save. The scope shows up in the list below as enabled on the client.

Set Scope

Commit

Make sure to remember to commit the changes in the Changes -> Commit menu.


Making Requests with the Client

The request is a back-channel request only. The user created in the previous tutorials can be used since the same credential-manager is configured for user credential verfication as the username authenticator.

  • CURL
  • HTTP

curl -X POST \
  https://localhost:8443/oauth/v2/oauth-token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id=legacy&client_secret=THE_SECRET&username=THE_USERNAME&password=THE_USER_PASSWORD'

POST /oauth/v2/oauth-token HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=legacy&client_secret=THE_SECRET&username=THE_USERNAME&password=THE_USER_PASSWORD

Response

The response to any of the requests above will be a JSON document similar to other responses from the token endpoint (e.g., the refresh token response). A typical example will look like this:

{
    "access_token": "c8a120ad-55f4-4f24-9d80-7b52fa218a91",
    "refresh_token": "c778735a-348f-4df0-a149-12325130778b",
    "scope": "",
    "token_type": "bearer",
    "expires_in": 300
}

Here, the scope is the default one; to change this, the client should include a scope parameter when making the request. If the scope of access which the OAuth server assigns to the token differs from what the client requested, this value will indicate the actual scope that was permitted. So, a client should always check this response parameter to see what was granted and act accordingly.

If an error occurs, the response will be a JSON object as well; however, the only fields will be error and perhaps error_description. If the latter isn't included, check the server logs and/or enable detailed error reporting in the OAuth profile.

Use with Caution

With any of these methods, the client app is collecting the user's credentials and forwarding them to the OAuth server. This is a kind of anti-pattern because the client sees the user's password. This flow also prevents the use of stronger credentials because username and password are required inputs. It is for these reasons that the specification warns:

Use only for selected clients

The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable.

A common usage of this flow is for migration and to harmonize access to a token-based model. Its use should be the exception though, not the norm.


  1. It is not used or profiled in OpenID Connect. 

Was this page helpful?