Skip to main content

Resource Owner Password Credentials Flow

The resource owner password credentials grant (ROPC) is designed for obtaining access tokens directly in exchange for a username and password. For this reason, it requires strong trust between the user and client application, and still, additional measures must be taken to mitigate the likely vulnerabilities and complications. Consider ROPC is not recommended as per the OAuth 2.0 best practices.

What Resource Owner Password Credentials (ROPC) Flow Is

The Resource Owner Password Credentials grant (also known as ROPC), according to the OAuth 2.0 Authorization Framework RFC6749 definition, can be used directly to obtain an access token by providing end-user credentials to the authorization server by the client. The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g., the client is part of the device operating system or a highly privileged application).

How ROPC Works

ROPC_Flow.svg

  1. The client requests token by calling the token endpoint.

    Sample cURL to the token endpoint with SecureAuth as an authorization server

    For client authentication method set to none:

    curl --location --request POST \
--url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-raw "grant_type=password&client_id=$CLIENT_ID&username=$USER_NAME&password=$USER_PASSWORD"

    For client authentication method set to client secret post or basic:

    curl --location --request POST \
--url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-raw "grant_type=password&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&username=$USER_NAME&password=$USER_PASSWORD"

    Region identifier

    REGION_ID is available for recently created tenants in the tenant URL next to TENANT_ID. The region IDs are assigned as follows:

    • Australia: au

    • Europe: eu

    • USA: us

    For tenants without the region identifier, the REGION_ID parameter must be skipped.

  2. Authorization server validates user credentials.

    When user credentials are valid, then

  3. Authorization server returns the access and ID tokens.

  4. User gets authenticated.

Custom extensions

Error hints

In case of invalid credentials error response is returned from the token endpoint:

{"error":"request_unauthorized","error_description":"request lacks valid authentication credentials for the target resource","status_code":401}

For specific use cases it is valuable to return additional field error_hint that can give more context and can enrich the response to the client. Below is the list of custom error hints that can be return together with authentication failed response:

  • credential must be reset - credential has been marked by administrator as must be reset

  • credential expired - credential expired

Response headers for successful authentication response

When issuing access token after successful authentication custom headers are used to enrich response to the user. Below is the list of defined headers with explanation what they mean:

  • X-Password-State: must-be-changed - password had must_be_changed flag in the storage; password should be changed (token that has been issued can be used to do that); password has been marked as must_be_reset so it is not possible to authenticate anymore with old password

In this section: