Skip to content

Secure APIs using JWT (Self Contained) Access Tokens

WSO2 Integrator: MI supports RFC 9068-compliant, self-contained JWT access tokens as secure API credentials. JSON Web Token (JWT) is an open standard of transmitting information securely between two parties. Because these tokens are digitally signed, they provide a tamper-proof mechanism for transmitting authorization data directly within the request.

JWT access tokens are ideal as API credentials because they function as self-contained security assertions. By carrying specific claims such as resource scopes, intended audience, and issuer details, etc. directly within the token, they provide the necessary context for delegated authorization. This allows the WSO2 Integrator: MI to inspect the token’s internal data and enforce granular security policies locally, ensuring that requests are authorized based on the specific permissions granted by the user.

Prerequisites for JWT based tokens

The following prerequisites have to be satisfied for JWT based tokens to work.

  • Only signed JWT access tokens are allowed.

  • The expected token format is as follows:

    base64(header).base64(payload).base64(signature)

  • Mandatory Claims: The token must include iss, sub, aud, jti, iat, and exp.

  • The JWT header should ideally contain "typ": "at+jwt" or "typ": "application/at+jwt" to indicate that the token is a JWT access token.

  • WSO2 Integrator: MI must have network access to the IdP's JSON Web Key Set (/jwks) endpoint for digital signature verification purposes.

  • If using a static public key instead of JWKS, the IdP’s public certificate must be imported into the WSO2 Integrator: MI's truststore (client-truststore.jks) with the alias configured in the handler. For more information, see Importing SSL certificates to a truststore.

Mandatory attributes of a JWT access token

The following are the mandatory attributes that are required for a JWT access token.

Note

Please note that the WSO2 Integrator: MI exclusively supports RFC 9068 (JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens). The mandatory attributes of a JWT access token and the validation pipeline described below is strictly implemented to comply with this specification.

  • Header

    alg The algorithm which signs the token (e.g., RS256).
    typ The media type of the complete JWS (e.g., at+jwt or application/at+jwt).

  • Payload

    sub The subject of the token, which identifies as to whom the token refers to.
    iat Token issued time
    exp The expiry time of the token.
    iss The principal that issued the JWT.
    aud The recipients that the JWT is intended for.
    jti The unique identifier of the JWT.

Validation Pipeline

1. Header Metadata Validation

Before verifying the signature, the handler inspects the JWT header for two critical security markers:

  • Type Check (typ): The handler confirms that the typ header is set to at+jwt (or application/at+jwt). This prevents "Token Confusion" attacks where an ID token might be mistakenly presented as an Access Token.

  • Algorithm Check (alg): The handler enforces the use of strong asymmetric algorithms (e.g., RS256). Any tokens using the none algorithm or weak symmetric algorithms (HMAC) are rejected immediately to prevent signature bypass.

Note

  • Default Behavior: By default, the server only accepts algorithms from the RSA family (e.g., RS256, RS384, RS512, PS256, PS384, PS512). This ensures that only strong, asymmetric signatures are trusted.
  • Strict Validation: If you need to be more specific or restrict the API to a single signature type, you can configure the allowedAlgorithm parameter at the handler level. This will force the handler to validate that the token's alg header matches your specified value exactly.

2. Integrity & Authenticity Check

Once the header is validated, the process moves to Digital Signature Verification. Using the kid (Key ID) found in the JWT header, the handler retrieves the corresponding public key from the configured JWKS endpoint. This step confirms that the token was indeed issued by a trusted Identity Provider and has not been altered in transit.

3. Temporal Policy Enforcement

Once the signature is verified, the handler enforces time-based security policies.

  • exp Claim Check: The Expiration (exp) claim is validated to ensure the token is currently active.

  • iat Claim Check: The iat check ensures the token is not "from the future" (accounting for the clock_skew_seconds parameter) and that it hasn't exceeded the max_issued_at_age_seconds policy, which limits the total lifespan of a token regardless of its official expiration.

Example Scenario

  • Policy: max_issued_at_age_seconds is set to 3600 (1 hour).
  • Token Issued At (iat): 10:00 AM
  • Expiration (exp): 01:00 PM
  • Current Time: 11:30 AM
  • Result: The token will be rejected, even if the expiration (exp) is set for 1:00 PM. This is because the token is now 90 minutes old, exceeding your 60-minute "maximum age" policy.

4. Audience validation

The handler then validates that the token is intended for this specific API by inspecting the Audience (aud) claim. If the configured audience is not present in the token's audience list, the request is rejected. This method is particularly useful when APIs are shared across multiple clients or services, and you want to ensure that each token is issued for a specific intended audience.

There are two levels to configure this:

  • Global Audience Validation: By setting the audience parameter at the global level (in deployment.toml), you can enforce a universal audience requirement across all APIs. This is ideal for scenarios where all your APIs are intended for the same set of clients.
  • Handler-Level Audience Validation: If you have APIs that serve different audiences, you can override the global setting by configuring the audience parameter at the handler level within the API definition. This is recommended for business-critical integrations where you must strictly validate that a token was issued specifically for that high-security resource, preventing "token reuse" across different parts of your ecosystem.

5. Scope validation

The WSO2 Integrator: MI validates the scopes coming in the scope claim of the JWT. The handler ensures the scope claim contains the necessary permissions (defined in the Open API spec) required to access the specific resource.

6. Sender Constrain & Proof-of-Possession

The final layer of the pipeline is the Confirmation (cnf) claim check. If cnf validation is enabled (for maximum security, cnf validation is enabled by default), the handler extracts the thumbprint of the client certificate used during the TLS handshake and compares it with the x5t#S256 value inside the token. This Proof-of-Possession check ensures that even if a JWT is intercepted, it cannot be used by any party other than the original client to whom it was issued.

Note

If your environment does not support mTLS or if this specific validation is not required, you must explicitly disable it

  • To disable: Set the disableCNFValidation parameter to true within the handler properties of your API definition.

7. Token Revocation Extension

While JWTs are traditionally stateless, many production environments require a way to instantly invalidate tokens that have been compromised or logged out at the Identity Provider (IdP) level. To support this, the handler includes a Token Revocation Extension.

This extension provides a dedicated interface, allowing you to implement your own custom revocation logic. By plugging into this extension, the handler can check each incoming token against your specific revocation source, such as a database, a distributed cache (like Redis), or a direct API call to your IdP's revocation endpoint.

The interface for this extension is defined as follows:

package org.wso2.micro.integrator.security.handler.oauth;

import java.util.Map;

public interface TokenRevocationHandler {

  /**
   * Checks if the given token has been revoked or invalidated.
   *
   * @param token The raw string token or a parsed JWT object.
   * @param context Additional metadata (e.g., claims) that might aid in the check.
   * @return true if the token is revoked/invalid; false if it is still active.
   * @throws RevocationCheckException if the check fails due to system errors.
   */
  boolean isRevoked(String token, Map<String, Object> context) throws RevocationCheckException;
}

If your custom implementation returns true, the handler will immediately reject the request, ensuring that revoked tokens cannot be used even if they have not yet reached their expiration time.

Handler Configuration Reference

The following table provides a reference for the configurable parameters of the JWT access token handler.

Validation Properties

Parameter Name Description Required/
Optional
Default
Value
jwksEndpoint The URL of the JWKS endpoint where the handler can retrieve the public keys for signature verification.

<property name="jwksEndpoint" value="https://idp.example.com/.well-known/jwks.json"/>
Required None
authorizationHeader The HTTP header containing the token.

<property name="authorizationHeader" value="Authorization"/>
Optional "Authorization"
trustedIssuers A comma-separated list of trusted token issuers. The handler will only accept tokens that have an iss claim matching one of these values.

<property name="trustedIssuers" value="https://idp.example.com,https://sts.windows.net/tenant-id/"/>
Optional None
allowedAlgorithms A comma-separated list of allowed signing algorithms (e.g., RS256, ES256). Tokens signed with algorithms not in this list will be rejected.

<property name="allowedAlgorithms" value="RS384,RS512"/>
Optional RS256
audience The expected audience value that must be present in the aud claim of the JWT. This ensures the token is intended for this API.

<property name="audience" value="https://api.orders.com"/>
Optional None
maxIssuedAtAgeSeconds Defines the maximum lifespan allowed for a token since it was issued (iat), regardless of the expiration time.

<property name="maxIssuedAtAgeSeconds" value="18000"/>
Optional None
removeOAuthHeadersFromOutMessage A flag to indicate whether to remove the OAuth-related headers (e.g., Authorization header) from the message before sending it to the backend. This can help prevent sensitive information from being exposed to backend services.

<property name="removeOAuthHeadersFromOutMessage" value="true"/>
Optional true
tokenRevocationHandler The fully qualified class name of a custom token revocation handler that implements the TokenRevocationHandler interface. This allows you to plug in custom logic to check if a token has been revoked (e.g., by checking a database or cache).

<property name="tokenRevocationHandler" value="org.sample.customRecovationHandler"/>
Optional None

Sender-Constrained Properties

When cnf validation is enabled, the handler will enforce sender constraint by performing a Proof-of-Possession check. In this case, the following additional properties are relevant:

Parameter Name Description Required/
Optional
Default Value
disableCNFValidation Set to false to enable Proof-of-Possession checks. It validates the cnf claim against the client's certificate. Optional false
enableClientCertificateValidation Toggles the extraction and validation of the client certificate from the transport layer. Optional true
clientCertificateHeader The HTTP header from which to extract the client certificate. This is typically used in scenarios where the client certificate is forwarded by a reverse proxy or LB. Optional "X-Client-Certificate"
clientCertificateEncode This property specifies the encoding format used for the client certificate when it is passed through HTTP headers (via the clientCertificateHeader). It ensures the handler can correctly decode the certificate string back into its original X.509 format before performing the cnf (confirmation) thumbprint validation. Optional false

HTTP Client & Proxy Configuration

The handler uses an internal HTTP client to retrieve public keys from the Identity Provider's JWKS metadata. Proper configuration of these settings is vital to prevent latency issues or connection failures during the token validation process.

By defining these properties within the handler tag of a specific API definition, you can override the global settings here. This is useful for APIs that need to connect to an internal IdP (bypassing the proxy) or for critical services that require shorter timeout durations to fail fast.

Property Name Description Required/
Optional
Default Value
connectionTimeout The timeout (in milliseconds) for establishing a connection to the JWKS endpoint. Optional 5000 ms
socketTimeout The timeout (in milliseconds) for waiting for data from the JWKS endpoint after a connection is established. Optional 5000 ms
connectionRequestTimeout The timeout (in milliseconds) for waiting to obtain a connection from the internal connection pool. Optional 5000 ms
enableProxy Set to true to route JWKS requests through a proxy server. Optional false
proxyHost The hostname of the proxy server to use when connecting to the JWKS endpoint. Optional None
proxyPort The port number of the proxy server. Optional None
proxyProtocol The protocol to use when connecting to the proxy server (e.g., http or https). Optional http
proxyUsername The username for authenticating with the proxy server, if required. Optional None
proxyPassword The password for authenticating with the proxy server, if required. Optional None
<handler class="org.wso2.micro.integrator.security.handler.oauth.OAuthAuthenticationHandler">
    ...
    <property name="connectionTimeout" value="3000"/>
    <property name="socketTimeout" value="3000"/>
    <property name="connectionRequestTimeout" value="3000"/>
    <property name="enableProxy" value="false"/>
</handler>

Global Server Configuration Reference

While the handler can be configured at the API level, the following properties can be managed globally. This ensures that all APIs on the server follow a consistent security baseline. These global values serve as the fallback if a specific handler-level property is missing.

Token Validation Settings

Parameter Name Description Required/
Optional
Default
Value
trusted_issuers A comma-separated list of trusted token issuers. The handler will only accept tokens that have an iss claim matching one of these values. Optional None
allowed_algorithms A comma-separated list of allowed signing algorithms (e.g., RS256, ES256). Tokens signed with algorithms not in this list will be rejected. Optional RS256
audience The expected audience value that must be present in the aud claim of the JWT. This ensures the token is intended for this API. Optional None
max_issued_at_age_seconds Defines the maximum lifespan allowed for a token since it was issued (iat), regardless of the expiration time. Optional None
clock_skew_seconds The amount of clock skew (in seconds) to allow when validating the iat and exp claim. This accounts for minor time discrepancies between the token issuer and the WSO2 Integrator: MI. Optional 60 seconds

[rest_api.jwt_security_handler]
trusted_issuers = ["https://idp.example.com","https://sts.windows.net/tenant-id/"]
allowed_algorithms = ["RS256","RS384"]
audience = "https://api.orders.com"
max_issued_at_age_seconds = 18000
clock_skew_seconds = 60

Note

Trusted Issuer Configuration

The trustedIssuers property defines the valid iss values that the handler will accept. For maximum flexibility, this can be configured at both the global and handler levels.

  • Global Configuration (Recommended): If you have multiple APIs that need to accept tokens from the same set of Identity Providers, it is better to maintain a list of trusted issuers at the global level (within deployment.toml). This way, you can avoid redundant configurations in each API and ensure consistency across your API ecosystem.
  • Handler-Level Override: You can also define trustedIssuers directly at the handler level for a specific API. This is ideal for specialized APIs that require a unique or more restricted set of issuers.
Precedence: The handler will always prioritize the handler level configuration. If a specific list is provided in the API definition, it will completely override the global list for that specific API.

Log Masking & Data Privacy Settings

To prevent the exposure of sensitive Bearer tokens in system logs (such as wire logs or audit logs), the handler supports a set of global masking configurations. These settings define how a JWT is truncated and obscured before being printed to any log file.

Parameter Name Description Required/
Optional
Default
Value
log_masking.token_max_len The maximum number of characters from the token to printed in logs. If the token exceeds this length, it will be truncated and suffixed with an ellipsis (...). Optional 10 characters
log_masking.token_max_visible_len The number of characters to remain visible at the end of the token after truncation. This allows for partial identification of the token without exposing the full value. Optional 4 characters
log_masking.token_min_visible_len_ratio The minimum percentage of the token that must remain visible if it is very short. Optional 0.3 (30%)
log_masking.token_mask_char The character used to replace the masked portion of the token. Optional "X"
[rest_api.jwt_security_handler]
log_masking.token_max_len = 12
log_masking.token_max_visible_len = 5
log_masking.token_min_visible_len_ratio = 0.2
log_masking.token_mask_char = "X"

Cache Settings

To optimize performance and reduce latency during token validation, the handler can cache the parsed JWT tokens and JWKS responses from the Identity Provider. The following global settings control the caching behavior:

Parameter Name Description Required/
Optional
Default
Value
cache_expiry The duration (in seconds) for which a cached entry remains valid. After this period, the token will be removed from the cache. Optional 900 seconds (15 minutes)
[rest_api.jwt_security_handler]
cache_expiry = 600

HTTP Client & Proxy Configuration

The handler requires an HTTP client to fetch Public Keys from the Identity Provider's JWKS endpoint. If the HTTP client properties are not explicitly defined at the Handler Level for a specific API, the handler will automatically fall back to these global settings. This is the recommended place for corporate proxy settings that apply to the whole network.

[mediation]
http_client.global_connection_timeout = 3000
http_client.global_socket_timeout = 3000
http_client.global_connection_request_timeout = 3000
http_client.global_proxy_enabled = false
Global Level Configuration Name Description Required/
Optional
Default Value
http_client.global_connection_timeout The timeout (in milliseconds) for establishing a connection to the JWKS endpoint. Optional 5000 ms
http_client.global_socket_timeout The timeout (in milliseconds) for waiting for data from the JWKS endpoint after a connection is established. Optional 5000 ms
http_client.global_connection_request_timeout The timeout (in milliseconds) for waiting to obtain a connection from the internal connection pool. Optional 5000 ms
http_client.global_proxy_enabled Set to true to route JWKS requests through a proxy server. Optional false
http_client.global_proxy_host The hostname of the proxy server to use when connecting to the JWKS endpoint. Optional None
http_client.global_proxy_port The port number of the proxy server. Optional None
http_client.global_proxy_protocol The protocol to use when connecting to the proxy server (e.g., http or https). Optional http
http_client.global_proxy_username The username for authenticating with the proxy server, if required. Optional None
http_client.global_proxy_password The password for authenticating with the proxy server, if required. Optional None

Build and Run

Follow the instructions below to secure APIs with JWT (Self Contained) access tokens for delegate access for REST APIs in WSO2 Integrator: MI.

Step 1: Configure the OAuth2 Authorization Handler

  1. Follow the steps in create integration project guide to set up the Integration Project.
  2. Define the OpenAPI Specification with Scopes.

    To enforce scope validation for a specific API resource, you must use the security keyword at the operation level. The handler will look for these definitions to determine if the incoming token has the necessary permissions.

    The Security Key: Under the security block, you must specify the key oauth2.

    Note

    The security key is case -insensitive. Whether you write oauth2, OAuth2, or OAUTH2, the handler will correctly identify it.

    The Scope List: Under that key, list the specific scopes required to access that resource. Ex: read:orders, write:orders, etc.

    Check this sample OpenAPI definition that includes the security definitions for scope validation:

    openapi: 3.0.1
    info:
      title: Order Management API
      description: API for managing customer orders with OAuth2 scope validation.
      version: 1.0.0
    
    paths:
      /orders:
        get:
          summary: Retrieve all orders
          responses:
            '200':
              description: A list of orders
          security:
            - OAuth2:           # Must match the name "oauth2"
                - read:orders   # Requirement: Token must have this scope
        post:
          summary: Create a new order
          responses:
            '201':
              description: Order created
          security:
            - OAuth2:
                - write:orders  # Requirement: Token must have this scope
    
  3. Create the REST API with the OpenAPI definition given above.

  4. To configure the OAuth2Authorization handler for the API, click the Edit button of the created API and navigate to the Handlers section.
  5. Click on the Add Handler button and type org.wso2.micro.integrator.security.handler.oauth.OAuthAuthenticationHandler as the class name.
  6. Click on Add Property button to add the necessary properties as below.

<api name="OrderService" context="/v1" publishSwagger="conf:/swagger/orders.yaml">
    <resource methods="GET" uri-template="/orders">
        <inSequence>
            <payloadFactory media-type="json">
                <format>{"status": "Success", "data": "Order list retrieved"}</format>
            </payloadFactory>
            <respond/>
        </inSequence>
    </resource>
    <resource methods="POST" url-mapping="/orders">
        <inSequence>
            <payloadFactory media-type="json">
              <format>{"status": "Success", "data": "Order created"}</format>
              <args/>
            </payloadFactory>
            <respond/>
        </inSequence>
        <faultSequence/>
    </resource>
    <handlers>
        <handler class="org.wso2.micro.integrator.security.handler.oauth.OAuth2AuthorizationHandler">
            <property name="jwksEndpoint" value="https://idp.example.com/.well-known/jwks.json"/>
            <property name="audience" value="https://api.orders.com"/>
            <property name="authorizationHeader" value="Authorization"/>
            <property name="disableCNFValidation" value="false"/>
        </handler>
    </handlers>
</api>

Step 3: Configure Global Settings

The global settings for the OAuth2AuthorizationHandler handler can be defined in the deployment.toml file. These settings will apply to all APIs that use the OAuth2AuthorizationHandler handler, unless overridden at the handler level within a specific API definition.

  1. To manage trusted issuers at the server level, specify the following configurations in your deployment.toml file.
[rest_api.jwt_security_handler]
trusted_issuers = ["https://idp.example.com","https://sts.windows.net/tenant-id/"]