From ea87ba0bb80a0d16f8f4221a07613a7ed47a8f12 Mon Sep 17 00:00:00 2001 From: Hasini Samarathunga Date: Mon, 16 Feb 2026 10:14:59 +0530 Subject: [PATCH] Add token issuer configuration guide documentation --- .../oauth2/configure-custom-token-issuer.md | 1 + en/identity-server/7.0.0/mkdocs.yml | 1 + .../oauth2/configure-custom-token-issuer.md | 1 + en/identity-server/7.1.0/mkdocs.yml | 1 + .../oauth2/configure-custom-token-issuer.md | 1 + en/identity-server/7.2.0/mkdocs.yml | 1 + .../oauth2/configure-custom-token-issuer.md | 1 + en/identity-server/next/mkdocs.yml | 1 + .../oauth2/configure-custom-token-issuer.md | 120 ++++++++++++++++++ 9 files changed, 128 insertions(+) create mode 100644 en/identity-server/7.0.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md create mode 100644 en/identity-server/7.1.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md create mode 100644 en/identity-server/7.2.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md create mode 100644 en/identity-server/next/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md create mode 100644 en/includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md diff --git a/en/identity-server/7.0.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md b/en/identity-server/7.0.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md new file mode 100644 index 0000000000..6cb04c0118 --- /dev/null +++ b/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" %} diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index 36abc5f17a..60c466cac4 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/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 diff --git a/en/identity-server/7.1.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md b/en/identity-server/7.1.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md new file mode 100644 index 0000000000..6cb04c0118 --- /dev/null +++ b/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" %} diff --git a/en/identity-server/7.1.0/mkdocs.yml b/en/identity-server/7.1.0/mkdocs.yml index 2fd0ef63f2..6914b56260 100644 --- a/en/identity-server/7.1.0/mkdocs.yml +++ b/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 diff --git a/en/identity-server/7.2.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md b/en/identity-server/7.2.0/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md new file mode 100644 index 0000000000..6cb04c0118 --- /dev/null +++ b/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" %} diff --git a/en/identity-server/7.2.0/mkdocs.yml b/en/identity-server/7.2.0/mkdocs.yml index 8298565983..5223083972 100644 --- a/en/identity-server/7.2.0/mkdocs.yml +++ b/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 diff --git a/en/identity-server/next/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md b/en/identity-server/next/docs/references/extend/authentication/oauth2/configure-custom-token-issuer.md new file mode 100644 index 0000000000..6cb04c0118 --- /dev/null +++ b/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" %} diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index b5c2796838..de84c95d30 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/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 diff --git a/en/includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md b/en/includes/references/extend/authentication/oauth2/configure-custom-token-issuer.md new file mode 100644 index 0000000000..dccb08f960 --- /dev/null +++ b/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 `/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 `/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.