From 391cac3fc63696ca1048c0e66921799cd58c461f Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Thu, 7 Nov 2024 10:05:42 +0100 Subject: [PATCH] feat: more rop claims (#1934) Document more claims in the resource owner password grant. --- .../resource-owner-password-grant.mdx | 66 +++++++++++++++---- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/oauth2-oidc/resource-owner-password-grant.mdx b/docs/oauth2-oidc/resource-owner-password-grant.mdx index 60a467cd1..c65c01c83 100644 --- a/docs/oauth2-oidc/resource-owner-password-grant.mdx +++ b/docs/oauth2-oidc/resource-owner-password-grant.mdx @@ -6,32 +6,32 @@ sidebar_label: Resource owner password flow :::info -The resource owner password credentials grant is a legacy grant that is only supported in Ory Network for enterprise customers. -Please contact [sales@ory.sh](mailto:sales@ory.sh) for support. +The resource owner password credentials grant is a legacy grant that Ory Network only supports for enterprise customers. Please +contact [sales@ory.sh](mailto:sales@ory.sh) 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 is suitable for clients which are highly trusted by the user, such as his or her -computer operating system or a highly privileged application. This grant type works as follows: +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 his or her username and password directly to the client. -2. The client sends a POST request with following parameters in the request body using form encoding to the token endpoint: +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 that is making the request. - - `client_secret`: The client secret that is used to authenticate the client. Only necessary if `token_endpoint_auth_method` is - set to `"client_secret_post"` in the OAuth2 client. + - `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 username and password whenever the access token expires. + 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, you need to include the "password" grant in the supported grant types. In -the Ory Console, edit the grant types by creating or editing an OAuth client. +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. -The credentials (username and password) are checked against Ory Identities. The user that is authenticated must already exist. +Ory Identities checks the credentials (username and password). The user being authenticated must already exist. ```mdx-code-block import Mermaid from "@site/src/theme/Mermaid"; @@ -48,3 +48,43 @@ import Mermaid from "@site/src/theme/Mermaid"; Client->>User: Use access token `} /> ``` + +## 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: + +```json +{ + "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](/hydra/guides/oauth2-webhooks.mdx).