Migrating from Opaque to Json Web Tokens

Overview

MuleSoft Auth Server now supports signed JSON Web Tokens (JWTs) for application authentication (App Auth). This feature replaces the traditional unsigned opaque access tokens, enabling clients and downstream services to validate access tokens locally without contacting the Auth Server for every request.

Note: This enhancement applies only to Application Authentication (Client Credentials flow). User Authentication continues to use unsigned opaque tokens and is unaffected by this change.

Previous Behavior: Opaque Tokens

Previously, App Auth access tokens were issued as unsigned opaque tokens. Since these tokens contained no verifiable information, every protected service had to send the token back to the Auth Server for validation (token introspection) before processing the request.

This approach introduced:

• Additional network calls for every token validation

• Increased latency for API requests

• Higher load on the Auth Server

• Dependency on Auth Server availability during request processing

New Behavior: Signed JWT Tokens

With this feature, the Auth Server issues signed JWT access tokens for App Auth.

Services can validate these tokens locally using the Auth Server's public signing keys, which are periodically downloaded and cached. This eliminates the need to call the Auth Server during normal token validation.

Benefits

• Lower latency by eliminating token introspection calls

• Improved scalability by reducing Auth Server traffic

• Higher availability since token validation continues even if the Auth Server is temporarily unavailable

• Reduced infrastructure costs associated with validation requests

• Standards-based JWT validation using public/private key cryptography

Risks

• Larger Token size: JWT tokens (2048 bytes or less) are larger than opaque (UUID4 or 36 bytes) tokens.

  • No assumptions (including token-size) should be implemented or they need to be reviewed and addressed.

The Auth Server's public keys should be refreshed periodically and cached by clients to ensure smooth key rotation while minimizing network traffic.

Important Consideration: Permission Changes

Because JWTs are self-contained and validated locally, any changes made to an application's roles or permissions are not reflected until the currently issued access token expires.

The default access token lifetime is 60 minutes.

Examples include:

• Removing an application's role

• Revoking permissions

• Updating assigned scopes

These changes become effective only after the application obtains a new access token.

Workaround for Immediate Permission Updates

If permission changes need to take effect immediately, use the following process:

1. Remove the required roles or permissions from the application.

2. Restart the affected application.

3. During startup, the application requests a new access token.

4. The newly issued JWT contains the updated roles and permissions.

This forces the application to discard its existing token and obtain a fresh token reflecting the latest authorization state.

Scope

Summary

The move from opaque tokens to signed JWTs significantly improves the performance, scalability, and resilience of App Auth by enabling local token validation using cached Auth Server public keys. While authorization changes are no longer reflected immediately during a token's lifetime, the impact is limited to the token validity period (60 minutes). When immediate enforcement is required, restarting the affected application after updating its permissions forces issuance of a new token with the latest authorization information.