OAuth2 resource owner password credentials grant

info

The resource owner password credentials grant is a legacy grant that Ory Network only supports for enterprise customers. Please contact [email protected] for support.

The OAuth 2.0 Resource Owner Password Credentials Grant is an OAuth 2.0 grant where the application exchanges the user's username and password for an access token. This grant type suits clients highly trusted by the user, such as their computer operating system or a highly privileged application. This grant type works as follows:

1. The resource owner (i.e., the user) provides their username and password directly to the client.

2. The client sends a POST request with the following parameters in the request body using form encoding to the token endpoint:

   • grant_type: The value must be password.
   • client_id: The ID of the client making the request.
   • client_secret: The client secret used to authenticate the client. Only necessary if token_endpoint_auth_method is set to "client_secret_post" in the OAuth2 client.
   • username: The resource owner username.
   • password: The resource owner password.

3. If the credentials are valid, the authorization server responds with an access token. This OAuth 2.0 grant does not support refresh tokens. The client has to ask the user for their username and password whenever the access token expires.

To use the Resource Owner Password Credentials Grant, include the "password" grant in the supported grant types. In the Ory Console, edit the grant types by creating or editing an OAuth client.

Ory Identities checks the credentials (username and password). The user being authenticated must already exist.

Token introspection and access token claims

You can introspect the access token that is issued using the OAuth 2.0 Token Introspection endpoint. The following claims are returned from the introspection endpoint and are part of the access token if the config parameter strategies.access_token is set to jwt:

• sub: The Ory Network identity ID of the user.
• client_id: The ID of the OAuth 2.0 client.
• scope: The scope of the token, as configured by the client and requested in the token request.
• aud: The audience of the token, as configured by the client.
• iss: The issuer of the token, the URL of the Ory Network instance.
• ext.username: The username of the user, as passed in the token request.

Here is an example of the body returned from the introspection endpoint:

{
  "active": true,
  "scope": "offline",
  "client_id": "70d417fc-2aea-4830-b247-f140a9c4bae1",
  "sub": "70d417fc-2aea-4901-4830-f140a9c412f7",
  "exp": 1730210703,
  "iat": 1730207103,
  "nbf": 1730207103,
  "username": "ory-username",
  "aud": ["https://aud.example.com"],
  "iss": "https://issuer.example.com",
  "token_type": "Bearer",
  "token_use": "access_token",
  "ext": {
    "username": "ory-username"
  }
}

Customizing the claims

You can further customize the claims in the access token and introspection data using a token hook.