feat: more rop claims (#1934)

Document more claims in the resource owner password grant.

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 [[email protected]](mailto:[email protected]) for support.
+The resource owner password credentials grant is a legacy grant that Ory Network only supports for enterprise customers. Please
+contact [[email protected]](mailto:[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 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).