Merge pull request #4778 from mpmadhavig/app-versioning

Sub attribute and introspection response docs updated
wso2 · Oct 10, 2024 · 8668cc5 · 8668cc5
2 parents 69ad583 + 79e5c94
commit 8668cc5
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 48 deletions.
diff --git a/en/includes/guides/authentication/oidc/token-validation-resource-server.md b/en/includes/guides/authentication/oidc/token-validation-resource-server.md
@@ -1,64 +1,60 @@
 # Token validation by resource servers
 
-A resource server is responsible for protecting resources such as APIs via OAuth2 access tokens. Access tokens are intended for authorizing the access of a resource.
-The resource server should be able to verify the access token sent by the application. If the application sends a [self-contained JWT access token]({{base_path}}/references/app-settings/oidc-settings-for-app/#access-token), then the resource server can validate the access token without interacting with the authorization server.
-OAuth2.0 supports [token introspection](https://datatracker.ietf.org/doc/html/rfc7662){:target="_blank"} to inspect the **access tokens** and **refresh tokens** using authorization servers.
+Access tokens provide limited authorization to resources within a resource server. The resource server is responsible for validating these tokens before granting access. Token validation differs based on the [type of the access tokens]({{base_path}}/references/app-settings/oidc-settings-for-app/#access-token) that the resource server receives.
 
-{{ product_name }} provides the `/oauth2/introspect` endpoint to perform token validation. A resource server can inspect tokens using {{ product_name }} and know the information related to the tokens. On {{ product_name }}, the resource server has to use client secret basic authentication to authenticate with the token introspection endpoint.
-You have to send it as the authorization header in the request: `Authorization: Basic BASE46_ENCODING<client_id:client_secret>`
+## Validate JWT tokens
 
-**Token introspection endpoint**
+A Jason Web Token (JWT) is a self-contained token. This means that the resource server does not need to interact with the identity provider to validate tokens. The payload of a sample decoded JWT token is as shown below.
 
-``` 
-{{ product_url_sample }}/oauth2/introspect
+```json
+{
+  "sub": "Alica@bifrost.com",
+  "aut": "APPLICATION_USER",
+  "aud": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
+  "nbf": 1623904805,
+  "azp": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
+  "scope": "openid",
+  "iss": "{{product_url_sample}}/oauth2/token",
+  "exp": 1623908405,
+  "iat": 1623904805,
+  "jti": "9fac7747-bb2d-46be-bef2-a95b2f69f8b2"
+}
 ```
 
-!!! tip
-    To perform base64 encoding for the client ID and client secret, you can use a tool, or you can run the below command.
+## Validate opaque tokens
 
-    `
-    echo -n '<client_id:client_secret>' | base64
-    `
+Unlike JWT tokens, opaque tokens are non-transparent. This means that the authorization information is not readily available to resource servers and they should interact with the identity provider to validate and extract the relevant information. OAuth2.0 supports [token introspection](https://datatracker.ietf.org/doc/html/rfc7662){:target="_blank"} to inspect access tokens and refresh tokens.
 
-**Request format**
+{{ product_name }} provides the following endpoint to perform token validation. 
 
-```bash
-curl --location --request POST '{introspection_endpoint_url}' \
---header 'Content-Type: application/x-www-form-urlencoded' \
---header 'Authorization: Basic V3NvcTh0NG5IVzgwZ1NuUGZ5RHZSYmlDX19FYTp6MEM3OXpsb3B4OGk3QnlPdzhLMTVBOWRwbFlh' \
---data-urlencode 'token={access_token}'
+``` 
+{{product_url_format}}/oauth2/introspect
 ```
+=== "Request format"
 
-**Sample request**
-
-=== "cURL"
-  ```bash
-  curl --location --request POST '{{ product_url_sample }}/oauth2/introspect' \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --header 'Cookie: atbv=646b0ed2-c501-4b17-9251-94112013a718' \
-  --header 'Authorization: Bearer 54bd024f-5080-3db5-9422-785f5d610605' \
-  --data-urlencode 'token=94e325b7-77c8-32c2-a6ff-d7be430bf785'
-  ```
+    ```bash
+    curl --location --request POST {{product_url_format}}/oauth2/introspect \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    --header 'Authorization: Basic <Base64Encoded(ClientID:ClientSecret)>' \
+    --data-urlencode 'token={access_token}'
+    ```
 
-This introspection request takes the following parameters:
+=== "Request sample"
+
+    ```bash
+    curl --location --request POST '{{ product_url_sample }}/oauth2/introspect' \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    --header 'Cookie: atbv=646b0ed2-c501-4b17-9251-94112013a718' \
+    --header 'Authorization: Basic V3NvcTh0NG5IVzgwZ1NuUGZ5RHZSYmlDX19FYTp6MEM3OXpsb3B4OGk3QnlPdzhLMTVBOWRwbFlh' \
+    --data-urlencode 'token=94e325b7-77c8-32c2-a6ff-d7be430bf785'
+    ```
 
-!!! note
-    See the [OAuth2.0 introspection request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1){:target="_blank"} for details.
+### User access token response
 
-<table>
-  <tr>
-    <th>Request Parameter</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td><code>token</code><Badge text="Required" type="mandatory"/></td>
-    <td>The token(access token or refresh token) you want to inspect.</td>
-  </tr>
-</table>
+User access tokens are tokens generated through user interactions, such as logging in by entering credentials. The access token represents the user and the user's permissions.
 
-**Sample response**
+The following response will be returned for the provided user access token:
 
-The following response will be returned for the provided access token:
 ```json
 {
   "aut": "APPLICATION_USER",
@@ -94,4 +90,31 @@ If the token you used is invalid, you will get the following response:
 {'active':false}
 ```
 
-<br>
+!!! note
+    See the [OAuth2.0 introspection request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1){:target="_blank"} for details.
+
+### Application access token response
+
+Application access tokens are tokens obtained through grant types like the [client_credentials]({{base_path}}/references/grant-types/#client-credentials-grant) grant, without any user involvement. Unlike user-bound tokens, application access tokens represent the application itself rather than an individual user.
+
+The introspection response for Application access Ttkens follows the format shown below:
+
+```json
+{
+  "nbf": 1629961093,
+  "scope": "openid profile",
+  "active": true,
+  "token_type": "Bearer",
+  "exp": 1629968693,
+  "iat": 1629961093,
+  "client_id": "Wsoq8t4nHW80gSnPfyDvRbiC__Eb"
+}
+```
+
+!!! warning "Deprecated behavior"
+
+    Previously, the introspection response for application access tokens included the `username` attribute, which contained the application owner's username. This attribute will no longer be included in the introspection response.
+
+    If your application's access tokens still return the response, it is likely that your application is out-of-date. If so, update your application through the {{product_name}} Console by navigating to the relevant application under the **Applications** section.
+
+    Once updated, the `username` attribute will no longer be included in the introspection response. Therefore, before updating, ensure that your application does not rely on the `username` attribute and remove any such dependencies.
diff --git a/...ncludes/guides/authentication/user-attributes/enable-attributes-for-oidc-app.md b/...ncludes/guides/authentication/user-attributes/enable-attributes-for-oidc-app.md
@@ -35,9 +35,7 @@ To add user attributes to the app:
 
 ### Select an alternate subject attribute
 
-The subject attribute is used for exchanging information about the user. The subject is represented by the **subject** attribute in the ID token.
-
-By default, Asgardeo shares **User ID** as the subject. You can define any user attribute as the subject.
+The subject attribute is used for exchanging information about the user. The subject is represented by the **subject** attribute in the ID token. By default, Asgardeo shares **User ID** as the subject. You can define any user attribute as the subject.
 
 To define a different attribute as the subject:
 
@@ -52,6 +50,14 @@ To define a different attribute as the subject:
 
 3. Click **Update**.
 
+!!! warning "Deprecated `sub` attribute behavior in application access tokens"
+
+    Application access tokens are tokens generated to represent the application rather than an individual user. Such tokens are generated during grant types such as [client_credential]({{base_path}}/references/grant-types/#client-credentials-grant).
+
+    Previously, the `sub` attribute of application access tokens contained the `userid` of the application owner. With the latest updates, the `sub` value will contain the `client_id` of the application. If your application's access tokens still return the `userid` in the `sub` attribute, it is likely that your application is out-of-date. If so, update your application through the {{product_name}} Console by navigating to the relevant application under the **Applications** section.
+
+    Once updated, the `sub` attribute will return the `client_id`. Therefore, before updating, ensure that your application does not rely on the `sub` attribute and remove any such dependencies.
+
 ### Define mandatory user attributes
 
 {% include "../../fragments/manage-app/manage-user-attributes/select-mandatory-attributes.md" %}