Merge pull request #5627 from piraveena/jwt-bearer-grant

Add jwt bearer grant docs

Author: piraveena

en/identity-server/next/docs/guides/authentication/configure-jwt-bearer-grant.md

@@ -0,0 +1,4 @@
+{% set product_name = "WSO2 Identity Server" %}
+{% set product_url_format = "https://localhost:9443" %}
+{% set product_url_sample = "https://localhost:9443" %}
+{% include "../../../../../includes/guides/authentication/configure-jwt-bearer-grant.md" %}

en/identity-server/next/mkdocs.yml

@@ -600,6 +600,7 @@ nav:
             - JWT Secured Authorization Response Mode (JARM) for OAuth 2.0: guides/authentication/oidc/jarm.md
             - Implement login using the OIDC Hybrid Flow: guides/authentication/oidc/implement-oidc-hybrid-flow.md
             - Configure token exchange: guides/authentication/configure-token-exchange.md
+            - Configure JWT Bearer Grant: guides/authentication/configure-jwt-bearer-grant.md
             - Validate ID tokens: guides/authentication/oidc/validate-id-tokens.md
             - Request user information: guides/authentication/oidc/request-user-info.md
             - Validate tokens: guides/authentication/oidc/token-validation-resource-server.md

en/includes/guides/authentication/configure-jwt-bearer-grant.md

@@ -0,0 +1,120 @@
+# Configure JWT Bearer Grant
+
+You can add a trusted token issuer to a exchange JWT assertion with an OAuth 2.0 access token in order to access protected resources on behalf of the resource owner. 
+
+Learn how to configure the OAuth 2.0 JWT Bearer Grant flow in WSO2 Identity Server. Refer [JWT Bearer grant]({{base_path}}/references/grant-types/#jwt-bearer-grant) for more information on how the flow works.
+
+Follow this guide for instructions.
+
+## Register a trusted token issuer
+
+To exchange a third-party token for an {{ product_name }}  token, you need to register the third-party token issuer as a trusted token issuer in your {{ product_name }}  organization.
+
+To register a trusted token issuer:
+
+1. On the {{ product_name }} console, go to **Connections**.
+2. Click **New Connections** and click **Create** on the **Trusted Token Issuer**.
+3. Enter the following details of the trusted token issuer:
+
+    <table>
+      <tr>
+        <th>Parameter</th>
+        <th>Description</th>
+      </tr>
+      <tr>
+        <td>Trusted token issuer name</td>
+        <td>A unique name for the new trusted token issuer.</td>
+      </tr>
+      <tr>
+        <td>Issuer</td>
+        <td>A unique issuer value of the trusted token issuer. This is the value of the `iss` claim in the JWT token generated from the configured identity provider. <br>
+        Example: <code>https://third-party-token-issuers.io/oauth2/token</code></td>
+      </tr>
+      <tr>
+        <td>Alias</td>
+        <td>The name by which the trusted token issuer knows {{ product_name }}. The <code>aud</code> claim of the token should include the {{ product_name }} organization's issuer value. If the <code>aud</code> claim doesn't include the organization's issuer value, the system validates the alias value you assign here against the <code>aud</code> claim. <br>
+       Example: <code>https://third-party-token-issuers.io/oauth2/token</code></td> 
+       </td>
+      </tr>
+    </table>
+
+4. Click **Next** and provide the mode of certificate configuration.
+
+    - **JWKS endpoint**: The JWKS endpoint of the trusted token issuer.
+
+      {% if product_name == "WSO2 Identity Server" %}
+
+        !!! note
+            For JWKS endpoints, the default read timeout equals 1000 milliseconds. To modify this value, add the following parameter to the `deployment.toml` file in the `<PRODUCT_HOME>/conf/repository` directory.
+
+            ```toml
+            [oauth.jwks_endpoint]
+            read_timeout = <value in milliseconds>
+            ```
+      {% endif %}
+
+    - **Use PEM certificate**: Upload or paste the public certificate of the trusted token issuer. The certificate should be in PEM format.
+
+        ??? note "If you have a certificate in other formats such as `.crt`, `.cer` or `.der`, expand here to see how you can convert them to PEM format using [OpenSSL](https://www.openssl.org/){:target="_blank"}"
+            **Convert CRT to PEM**
+            ```bash
+            openssl x509 -in cert.crt -out cert.pem
+            ```
+            **Convert CER to PEM:**
+            ```bash
+            openssl x509 -in cert.cer -out cert.pem
+            ```
+            **Convert DER to PEM:**
+            ```bash
+            openssl x509 -in cert.der -out cert.pem
+            ```
+
+5. Click **Finish** to add the new trusted token issuer.
+
+## Enable JWT Bearer Grant in your app
+
+!!! note "Before you begin"
+    You need to register  [Standard-based OIDC application]({{base_path}}/guides/applications/register-standard-based-app/) application types with WSO2 Identity Server.
+
+
+To enable JWT bearer grant in your application:
+
+1. On the {{ product_name }} Console, go to **Applications**.
+
+2. Open your application from the list and go to the **Protocol** tab.
+
+3. Add `JWT Bearer` under the **Allowed grant types**.
+
+4. Click **Update** to save the configurations.
+
+## Try it out
+
+Follow the steps given below.
+
+1. Obtain the JWT token received from the third-party token issuer.
+2. The application sends the access request to the token endpoint in WSO2 Identity Server with the following:
+    - JWT bearer grant type.
+    - `JWT assertion` that is created by the third-party token issuer.
+    - Service provider's `client ID` and `client secret`.
+3. Execute the following cURL command to exchange the third-party token for an {{ product_name }} token.
+
+   ```bash
+   curl -v -k -X POST {{base_url}}/oauth2/token \
+   --header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+   --header "Content-Type:application/x-www-form-urlencoded" \
+   --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+   --data-urlencode "assertion=<jwt_token>"
+   ```
+
+Upon successful execution, you will receive the exchanged token issued by {{ product_name }}.
+
+
+!!! note
+    While configuring the JWT bearer grant type, the iat validating time period can also be configured in the `deployment.toml` file in the `<IS_HOME>/repository/conf` as shown below. The default value is 30 minutes.
+   ```toml
+    [oauth.grant_type.jwt]
+    enable_iat_validation="true"
+    iat_validity_period=30
+   ``` 
+
+Refer [JWT Bearer grant]({{base_path}}/references/grant-types/#jwt-bearer-grant) for more information on how the flow works.

en/includes/guides/authentication/configure-token-exchange.md

@@ -189,3 +189,4 @@ Follow the steps given below.
         {{ product_name }} only copies the `sub` claim from the token received from the trusted token issuer to the exchanged {{ product_name }} token.
 
 Upon successful execution, you will receive the exchanged token issued by {{ product_name }}.
+

en/includes/references/grant-types.md

@@ -14,6 +14,7 @@ Grant types in OAuth 2.0 are defined as the methods used by a client to obtain a
 {% endif %}
 - [Token exchange grant](#token-exchange-grant)
 {% if product_name == "WSO2 Identity Server" %}
+- [JWT Bearer Grant](#jwt-bearer-grant)
 - [SAML 2.0 bearer grant](#saml-20-bearer-grant)
 {% endif %}
 
@@ -431,9 +432,49 @@ The following diagram shows how the token exchange grant flow works.
 6. The client application can now request resources from the resource server by providing the access token.
 7. As the resource server trusts {{ product_name }} issued tokens, it returns the requested resources to the client application.
 
-See [configure the token exchange flow]({{base_path}}/guides/authentication/configure-token-exchange) for more details.
+Token exchange can be used for delegation and impersonation use cases. See [configure the token exchange flow]({{base_path}}/guides/authentication/configure-token-exchange) for more details about delegation usecase. See  [user impersonation]({{base_path}}/guides/authorization/user-impersonation/via-business-application) for more details on user impersonation with token exchange grant.
 
 {% if product_name == "WSO2 Identity Server" %}
+
+## JWT Bearer grant
+
+OAuth 2.0 JWT bearer is a grant type in the OAuth 2.0 framework that enables the exchange of one type of token for another with a different set of permissions or attributes. This grant type is defined in the [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523).
+
+The following diagram shows how the JWT Bearer grant flow works.
+
+![How the JWT bearer grant works]({{base_path}}/assets/img/references/grants/token-exchange-grant.png)
+
+1. The user sends a login request to the client application.
+2. The client application sends an authorization request to the third-party IdP.
+3. The third-party IdP returns the JWT access token for the user to the client application.
+4. The client application makes a token exchange request to the authorization server:
+
+    === "Request format (/token)"
+
+        ```bash
+        curl -v -k -X POST {{base_url}}/oauth2/token \
+        --header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+        --header "Content-Type:application/x-www-form-urlencoded" \
+        --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+        --data-urlencode "assertion=<jwt_token>"
+        ```
+    
+    === "Sample request (/token)"
+
+        ```bash
+        curl -v -k -X POST {{base_url_example}}/oauth2/token \
+        --header "Authorization: Basic RWkwV2Y5YnpmTXE0UTBsZndTdlRQamU4a2NFYTpIRvvyUzJIUjlrZE9YMjBXTG9JNmY1eE1wdUlBamdKeG5aUVVUMV9lNTJnYQ==" \
+        --header "Content-Type:application/x-www-form-urlencoded" \
+        --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+        --data-urlencode "assertion=eyJ4NXQiOiJJSm5VOF9rbkpQOC1jMEJHWTdOT2N1eWEtSlEiLCJraWQiOiJPRE0wWkRBMk5qQTFOREl4TkdFd05ERmlOakl5TWpRd05qQTJNMlppWVRKak1UbGxObVkzTm1FMVpXWmhPVEV3T1RZd01EQXdOREZpWVROaVpUQTFOQV9SUzI1NiIsInR5cCI6ImF0K2p3dCIsImFsZyI6IlJTMjU2In0.ewogICJzdWIiOiAiNDUzZDBjYTMtN2ZkNi00ZWJhLWJiYWUtNjEwNjI5OSIsCiAgImF1dCI6ICJBUFBMSUNBVElPTl9VU0VSIiwKICAiaXNzIjogImh0dHBzOi8vYXBpLmFzZ2FyZGVvLmlvL3Qvb3JnbmFtZS9vYXV0aDIvdG9rZW4iLAogICJjbGllbnRfaWQiOiAiS2tXclNQMzM0VkVKazNFbnV4NXE3YlFhIiwKICAiYXVkIjogWwogICAgIktrV3JTUDMzNFZFSmszRW51eDVxN2JRYSIsCiAgICAiaHR0cHM6Ly9sb2NhbGhvc3Q6OTQ0My9vYXV0aDIvdG9rZW4iCiAgXSwKICAibmJmIjogMTc2MDA3NDEzOSwKICAiYXpwIjogIktrV0puclNQMzM0VkVKazNFblFBdXg1cTdiUWEiLAogICJvcmdfaWQiOiAiMWY5ZTk4MWIiLAogICJzY29wZSI6ICJvcGVuaWQiLAogICJleHAiOiAxNzYwMDc3NzM5LAogICJvcmdfbmFtZSI6ICJvcmduYW1lIiwKICAiaWF0IjogMTc2MDA3NDEzOSwKICAianRpIjogImRmZTMzZDRiIiwKICAib3JnX2hhbmRsZSI6ICJvcmduYW1lIgp9.GXwYyOkaMNgFWyksSgSaAKmj6FqSRJX_3e1CxlLZwtoLtndrM2VfzRdx2J-uTdJLNSLF4fyDvdLzM0OC1TAfGaJNxJ2l_CYNvDnNcncMa1nfnmKeydmDbGksLasZah384jt8i49zD1DboMsglv2vFq9v7Ce6BHfPvHiL_nqOW8q34uXt8QmZLugalPA-2qchsi1C0NDu1niXz3DEO7VPMy7S2SZGHBmeoydoifWtKeqzKr5ArU0xJ9w5pW-VmQT8XWctE4UfRaYzpubl6DvAijT4uTAQYAgpk1IJC6Su_OTEEgnGf7L-iQxTf-KdvpNPvL6i-CFkBf9IktMm0o5kXw"
+        ```
+
+5. The authorization server responds to the client with the new access token.
+6. The client application can now request resources from the resource server by providing the access token.
+7. As the resource server trusts {{ product_name }} issued tokens, it returns the requested resources to the client application.
+
+See [configure the JWT Bearer Grant flow]({{base_path}}/guides/authentication/configure-jwt-bearer-grant) for more details.
+
 ## SAML 2.0 bearer grant
 
 SAML 2.0 bearer grant is a grant type in the OAuth 2.0 framework that enables the exchange of a SAML 2.0 assertion for an OAuth 2.0 access token. This grant type is defined in the [SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants specification (RFC 7522)](https://datatracker.ietf.org/doc/html/rfc7522){:target="_blank"}.