Add token issuer configuration guide documentation

en/identity-server/7.0.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md

@@ -0,0 +1 @@
+{% include "../../../../../../../includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md" %}

en/identity-server/7.0.0/mkdocs.yml

@@ -1084,6 +1084,7 @@ nav:
       - Authentication:
         - OAuth2:
           - Write a custom OAuth2 grant type: references/extend/authentication/oauth2/write-a-custom-oauth-2.0-grant-type.md
+          - Configure a custom token issuer: references/extend/authentication/oauth2/configure-custom-token-issuer.md
         - Conditional authentication:
           - Write custom functions for conditional authentication: references/extend/authentication/conditional-auth/write-custom-functions-for-conditional-authentication.md
         - Customize the authentication endpoint: references/extend/authentication/customize-the-authentication-endpoint.md

en/identity-server/7.1.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md

@@ -0,0 +1 @@
+{% include "../../../../../../../includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md" %}

en/identity-server/7.1.0/mkdocs.yml

@@ -1190,6 +1190,7 @@ nav:
           - Authentication:
               - OAuth2:
                   - Write a custom OAuth2 grant type: references/extend/authentication/oauth2/write-a-custom-oauth-2.0-grant-type.md
+                  - Configure a custom token issuer: references/extend/authentication/oauth2/configure-custom-token-issuer.md
               - Conditional authentication:
                   - Write custom functions for conditional authentication: references/extend/authentication/conditional-auth/write-custom-functions-for-conditional-authentication.md
               - Write a custom local authenticator: references/extend/authentication/write-a-custom-local-authenticator.md

en/identity-server/7.2.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md

@@ -0,0 +1 @@
+{% include "../../../../../../../includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md" %}

en/identity-server/7.2.0/mkdocs.yml

@@ -1342,6 +1342,7 @@ nav:
       - Authentication:
         - OAuth2:
           - Write a custom OAuth2 grant type: references/extend/authentication/oauth2/write-a-custom-oauth-2.0-grant-type.md
+          - Configure a custom token issuer: references/extend/authentication/oauth2/configure-custom-token-issuer.md
         - Conditional authentication:
           - Write custom functions for conditional authentication: references/extend/authentication/conditional-auth/write-custom-functions-for-conditional-authentication.md
         - Write a custom local authenticator: references/extend/authentication/write-a-custom-local-authenticator.md

en/identity-server/next/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md

@@ -0,0 +1 @@
+{% include "../../../../../../../includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md" %}

en/identity-server/next/mkdocs.yml

@@ -1348,6 +1348,7 @@ nav:
       - Authentication:
         - OAuth2:
           - Write a custom OAuth2 grant type: references/extend/authentication/oauth2/write-a-custom-oauth-2.0-grant-type.md
+          - Configure a custom token issuer: references/extend/authentication/oauth2/configure-custom-token-issuer.md
         - Conditional authentication:
           - Write custom functions for conditional authentication: references/extend/authentication/conditional-auth/write-custom-functions-for-conditional-authentication.md
         - Write a custom local authenticator: references/extend/authentication/write-a-custom-local-authenticator.md

en/includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md

@@ -0,0 +1,120 @@
+# Configure a custom token issuer
+
+This guide explains how to configure token issuers in {{ product_name }}. A token issuer determines the format and structure of the tokens generated by the authorization server.
+
+## Understand token issuers
+
+{{ product_name }} provides two out-of-the-box token issuers:
+
+- **OauthTokenIssuer** (default): Generates opaque access tokens (UUID-based).
+- **JWTTokenIssuer**: Generates self-contained JWT (JSON Web Token) access tokens.
+
+You can configure either of these issuers as the default token generator. Or, you can implement and register a custom token issuer.
+
+## Configure the default token issuer
+
+You can set the default token issuer using the `token_generator` configuration. This configuration replaces the `self_contained` configuration used in previous versions.
+
+To set the default token issuer:
+
+1. Open the `deployment.toml` file found in the `<IS_HOME>/repository/conf/` directory.
+
+2. Add the following configuration:
+
+    ```toml
+    [oauth.extensions]
+    token_generator = "org.wso2.carbon.identity.oauth2.token.JWTTokenIssuer"
+    ```
+
+    !!! note
+        By default, {{ product_name }} uses `OauthTokenIssuer` (which generates opaque tokens). The example above shows how to switch to `JWTTokenIssuer` for generating JWT access tokens.
+
+3. Restart the server to apply the changes.
+
+After this configuration, the authorization server generates tokens using the specified issuer for all token requests.
+
+---
+
+## Register a custom token issuer
+
+If you want to use a custom token issuer, you must register it under `SupportedTokenTypes`. This registration allows {{ product_name }} to recognize and use your custom implementation.
+
+### Prerequisites
+
+Write a custom token issuer by implementing the `org.wso2.carbon.identity.oauth2.token.OauthTokenIssuer` interface or extending an existing token issuer class such as `org.wso2.carbon.identity.oauth2.token.JWTTokenIssuer`.
+
+### Register the custom issuer
+
+To register a custom token issuer:
+
+1. Package your custom implementation as a JAR file.
+
+2. Place the JAR file in the `<IS_HOME>/repository/component/lib/` directory.
+
+3. Open the `deployment.toml` file.
+
+4. Add the following configuration to register your custom token issuer:
+
+    ```toml
+    [[oauth.extensions.token_types]]
+    name = "CustomTokenIssuer"
+    issuer = "org.wso2.carbon.identity.extensions.CustomTokenIssuer"
+    persist_access_token_alias = true
+    ```
+
+    !!! info
+        - The `name` parameter defines a unique identifier for this token type.
+        - The `issuer` parameter specifies the fully qualified class name of your custom token issuer.
+        - The `persist_access_token_alias` parameter (optional) determines whether to persist the token alias.
+
+5. Restart the server to apply the changes.
+
+After this configuration, {{ product_name }} recognizes your custom token issuer.
+
+---
+
+## Register a custom issuer as the JWT token issuer
+
+To replace the default JWT token issuer with your custom implementation, register it with the name `JWT`.
+
+To register a custom issuer as the JWT token issuer:
+
+1. Open the `deployment.toml` file.
+
+2. Add the following configuration:
+
+    ```toml
+    [[oauth.extensions.token_types]]
+    name = "JWT"
+    issuer = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"
+    ```
+
+3. Restart the server to apply the changes.
+
+After this configuration, your custom issuer generates JWT tokens when an application requests them.
+
+---
+
+## Set a custom issuer as the default token issuer
+
+To make your custom token issuer the default for all token requests server-wide, register it with the name `Default` and set it in the `token_generator` configuration.
+
+To set a custom issuer as the default token issuer:
+
+1. Open the `deployment.toml` file.
+
+2. Add the following configuration:
+
+    ```toml
+    [[oauth.extensions.token_types]]
+    name = "Default"
+    issuer = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"
+
+    [oauth.extensions]
+    token_generator = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"
+    ```
+
+    !!! note "Why register as 'Default'?"
+        Registering your custom token issuer with the name `Default` in `SupportedTokenTypes` ensures that {{ product_name }} recognizes it as the primary token issuer. This registration aligns with the behavior expected by the OAuth framework.
+
+3. Restart the server to apply the changes.