Configure a custom token issuer¶

This guide explains how to configure token issuers in WSO2 Identity Server. A token issuer determines the format and structure of the tokens generated by the authorization server.

Understand token issuers¶

WSO2 Identity Server provides two out-of-the-box token issuers:

OauthTokenIssuer (default): Generates opaque access tokens (UUID-based).
JWTTokenIssuer: Generates self-contained JWT 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:

Open the deployment.toml file found in the <IS_HOME>/repository/conf/ directory.
Add the following configuration:
```
[oauth.extensions]
token_generator = "org.wso2.carbon.identity.oauth2.token.JWTTokenIssuer"
```
Note

By default, WSO2 Identity Server uses OauthTokenIssuer (which generates opaque tokens). The example above shows how to switch to JWTTokenIssuer for generating JWT access tokens.
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 WSO2 Identity Server 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:

Package your custom implementation as a JAR file.
Place the JAR file in the <IS_HOME>/repository/components/lib/ directory.
Open the deployment.toml file.
Add the following configuration to register your custom token issuer:
```
[[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.
Restart the server to apply the changes.

After this configuration, WSO2 Identity Server 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:

Open the deployment.toml file.

Add the following configuration:

[[oauth.extensions.token_types]]
name = "JWT"
issuer = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"

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:

Open the deployment.toml file.
Add the following configuration:
```
[oauth.extensions]
token_generator = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"

[[oauth.extensions.token_types]]
name = "Default"
issuer = "org.wso2.carbon.identity.extensions.CustomJWTTokenIssuer"
```
Why register as 'Default'?

Registering your custom token issuer with the name Default in SupportedTokenTypes ensures that WSO2 Identity Server recognizes it as the primary token issuer. This registration aligns with the behavior expected by the OAuth framework.
Restart the server to apply the changes.

After this configuration, your custom token issuer acts as the default issuer for all token requests server-wide.