Merge pull request #5587 from mpmadhavig/token-hashing

Add OAuth Token Hashing docs

Author: mpmadhavig

en/identity-server/7.1.0/docs/references/token-hashing.md

@@ -0,0 +1 @@
+{% include "../../../../includes/references/token-hashing.md" %}

en/identity-server/7.1.0/mkdocs.yml

@@ -1163,6 +1163,7 @@ nav:
           - Token binding:
               - Token binding: references/token-binding/index.md
               - Client-request: references/token-binding/client-request.md
+          - Token hashing: references/token-hashing.md
           - Financial-grade API: references/financial-grade-api.md
           - App-native authentication: references/app-native-authentication.md
           - OIDC session management: references/concepts/oidc-session-management.md

en/identity-server/next/docs/references/token-hashing.md

@@ -0,0 +1 @@
+{% include "../../../../includes/references/token-hashing.md" %}

en/identity-server/next/mkdocs.yml

@@ -1245,6 +1245,7 @@ nav:
         - Token binding: references/token-binding/index.md
         - Client-request: references/token-binding/client-request.md
         - DPoP: references/token-binding/dpop.md
+      - Token hashing: references/token-hashing.md
       - Financial-grade API: references/financial-grade-api.md
       - App-native authentication: references/app-native-authentication.md
       - OIDC session management: references/concepts/oidc-session-management.md
@@ -1345,7 +1346,6 @@ nav:
           - Manage tokens in .NET: complete-guides/dotnet/manage-tokens-in-dotnet-apps.md
           - Next Steps: complete-guides/dotnet/next-steps.md
 
-
 not_in_nav: |
   /page-not-found.md
   /guides/authentication/add-identifier-first-login.md

en/includes/guides/authorization/user-impersonation/user-impersonation.md

@@ -224,7 +224,7 @@ To make an application discoverable,
 
 3. Click **Update** to save the changes.
 
-### Step 4: Share Application with Organization(Optional)
+### Step 6: Share Application with Organization(Optional)
 
 To allow impersonating organization users, share the business applications with the relevant organization. Use the [documentation here]({{base_path}}/guides/organization-management/share-applications/#share-a-registered-application) to proceed with configuring.
 

en/includes/references/token-hashing.md

@@ -0,0 +1,83 @@
+# OAuth Token Hashing
+
+WSO2 Identity Server (WSO2 IS) allows you to enable OAuth2 token hashing to protect OAuth2 access tokens, refresh tokens, consumer secrets, and
+authorization codes.
+
+!!! note
+    -   Token hashing is only required if there are long lived tokens.
+
+    -   If you want to enable this feature, WSO2 recommends using a fresh
+        WSO2 Identity Server distribution.  
+
+    -   To use this feature with an existing database, you may need to
+        perform data migration before you enable the feature. If you have to
+        perform data migration before you enable this feature, [Contact
+        us](https://wso2.com/contact/).
+    
+----
+
+## Set up OAuth token hashing
+
+1. Add the following configurations to the `deployment.toml` file found in the `<IS_HOME>/repository/conf` folder.
+    - Add the following property and set it to true to enable hashing.
+
+        ``` toml
+        [oauth]
+        hash_tokens_and_secrets = true
+        ```
+
+    - Add the following configuration to specify the algorithm to use for hashing:
+
+        ``` toml
+        [oauth]
+        hash_token_algorithm = "SHA-256"
+        ```
+
+    - Add the following token persistence processor to  enable token hashing:
+
+        ``` toml
+        [oauth.extensions]
+        token_persistence_processor = "org.wso2.carbon.identity.oauth.tokenprocessor.HashingPersistenceProcessor"
+        ```
+
+        !!! tip
+            WSO2 Identity Server allows you to use hashing algorithms supported by MessageDigest. For more information on hashing algorithms supported by MessageDigest, see [MessageDigest Algorithms](https://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#MessageDigest).  
+
+            The default algorithm for hashing is SHA-256.
+
+2. Run the appropriate database command to remove the `CONN_APP_KEY` constraint from the `IDN_OAUTH2_ACCESS_TOKEN` table.
+
+    For example, if you are using an H2 database, you need to run the following command:
+
+    ``` sql
+    ALTER TABLE IDN_OAUTH2_ACCESS_TOKEN DROP CONSTRAINT IF EXISTS CON_APP_KEY
+    ```
+
+    !!! tip
+        In general, for a specified consumer key, user, and scope, there can be only one active access token. The `CON_APP_KEY` constraint in the
+        `IDN_OAUTH2_ACCESS_TOKEN` table enforces this by allowing only one active access token to exist for specified consumer key, user, and scope values.  
+
+        With regard to hashing, a new access token is issued for every access token request. Therefore, for a given consumer key, user, and scope, there can be multiple active access tokens. To allow existence of multiple active access tokens, you need to remove the `CONN_APP_KEY` constraint from the `IDN_OAUTH2_ACCESS_TOKEN` table.
+
+----
+
+## Configure a service provider
+
+Follow the steps below to register an application:
+
+1. On the {{ product_name }} Console, go to **Applications**.
+
+2. Click **New Application** and select **Standard-Based Application** to open the following:
+
+    ![Register a standard based application]({{base_path}}/assets/img/apis/management-apis/register-a-sba.png){: width="600" style="display: block; margin: 0;"}
+
+3. Provide an application name.
+
+4. Select **OAuth 2.0 OpenID Connect** as the application protocol.
+
+5. Click **Register** to complete the registration.
+
+!!! tip
+    The **Consumer Secret** value is displayed in plain text only once. Therefore, be sure to copy and save it for later use.
+
+You have successfully set up OAuth token hashing. Now all of the OAuth2 access tokens, refresh tokens, consumer secrets, and authorization codes will be hashed in the database.