diff --git a/docs/self-hosted/oel/oauth2/stateless-jwt.mdx b/docs/self-hosted/oel/oauth2/stateless-jwt.mdx new file mode 100644 index 000000000..edf681e39 --- /dev/null +++ b/docs/self-hosted/oel/oauth2/stateless-jwt.mdx @@ -0,0 +1,172 @@ +--- +id: stateless-jwt +title: Stateless JWT access tokens +sidebar_label: Stateless JWT tokens +--- + +This document explains how to configure stateless JWT access tokens in Ory Hydra. When enabled, JWT access tokens are issued as +self-contained tokens without persisting them to the database, significantly improving performance for high-throughput workloads. + +```mdx-code-block +import Help from '@site/docs/_common/need-help.mdx' + + +``` + +## Overview + +By default, Ory Hydra persists all access tokens to the database, regardless of the token strategy (opaque or JWT). This +persistence enables features like token introspection, revocation, and userinfo endpoint support. However, for workloads using JWT +access tokens that do not require these stateful operations, database writes introduce unnecessary overhead. + +The stateless JWT feature optimizes performance by skipping database persistence for JWT access tokens. When enabled, access +tokens are issued as self-contained JWTs with a configurable boolean claim that identifies them as stateless. Operations that +require token state (introspection, revocation, and userinfo) will return an error for these tokens. + +This feature applies when either the OAuth2 client is configured to use the JWT access token strategy or the global access token +strategy is set to JWT instead of opaque. + +## How it works + +When stateless JWT tokens are enabled: + +1. Token Generation: JWT access tokens are issued with an additional boolean claim (default: `sl`) set to `true`. This claim + identifies the token as stateless. + +2. No Database Writes: Access token sessions are not written to the database, eliminating write operations and improving + performance. + +3. Stateful Operations Unavailable: Operations that require token state return HTTP 501 (Not Implemented) with error + `unsupported_token_type`: + + - Token Introspection (`/oauth2/introspect`): Returns 501 for stateless JWT tokens + - Token Revocation (`/oauth2/revoke`): Returns 501 for stateless JWT tokens + - Userinfo Endpoint (`/userinfo`): Returns 501 for stateless JWT tokens + +4. Standard JWT Validation: Token validation continues to work through standard JWT signature verification and claims validation. + +## Configuration + +Configure stateless JWT access tokens using the `strategies.jwt.stateless` configuration namespace. + +### Configuration keys + +Two configuration keys control stateless JWT behavior: + +- `strategies.jwt.stateless.enabled`: Boolean flag to enable or disable stateless JWT tokens. Default: `false` +- `strategies.jwt.stateless.claim_name`: String value specifying the claim name used to identify stateless tokens. Default: `sl` + +### Example configuration + +```yaml +strategies: + jwt: + stateless: + enabled: true + claim_name: sl +``` + +In this configuration: + +- Stateless JWT tokens are enabled +- JWT access tokens will include a top-level claim `"sl": true` +- Database writes for JWT access token sessions are skipped + +### Custom claim name + +You can customize the claim name used to identify stateless tokens: + +```yaml +strategies: + jwt: + stateless: + enabled: true + claim_name: stateless +``` + +With this configuration, JWT access tokens will contain `"stateless": true` instead of the default `"sl": true`. + +## Token format + +When stateless JWT tokens are enabled, the generated JWT access token includes the configured stateless claim as a top-level +boolean claim. + +### Example JWT payload + +```json +{ + "iss": "https://your-hydra-instance.com", + "sub": "user-id", + "aud": ["api-resource"], + "exp": 1735689600, + "iat": 1735686000, + "scope": "openid profile email", + "sl": true +} +``` + +The `sl` claim (or your custom claim name) with a boolean value of `true` identifies this token as stateless. + +## Functional limitations + +Enabling stateless JWT tokens disables certain OAuth2 and OpenID Connect features that require access to a persisted token state. + +### Token introspection + +Endpoint: `/oauth2/introspect` + +When introspecting a stateless JWT access token, the endpoint returns: + +- HTTP Status: 501 Not Implemented +- Error: `unsupported_token_type` + +Standard opaque and JWT access tokens (with stateless disabled) continue to support introspection normally. + +### Token revocation + +Endpoint: `/oauth2/revoke` + +Attempting to revoke a stateless JWT access token returns: + +- HTTP Status: 501 Not Implemented +- Error: `unsupported_token_type` + +Since stateless tokens are not persisted in the database, they cannot be revoked. Token expiration is enforced through the JWT +`exp` claim during validation. + +### Userinfo endpoint + +Endpoint: `/userinfo` + +Requesting user information with a stateless JWT access token returns: + +- HTTP Status: 501 Not Implemented +- Error: `unsupported_token_type` + +The `/userinfo` endpoint requires database lookups to retrieve the consent session data associated with the access token. + +## When to use stateless JWT tokens + +Stateless JWT access tokens are suitable for scenarios where: + +- High throughput is required: Applications with high token issuance rates benefit from eliminating database writes +- Token revocation is not needed: Workloads that rely solely on JWT expiration for token lifecycle management, or have a dedicated mechanism for revoking tokens +- Introspection is not used: Resource servers validate tokens using JWT signature verification rather than introspection +- Userinfo endpoint is not required: Client applications do not call the userinfo endpoint for user information +- JWT access tokens are used: The feature only applies when clients or the global strategy is configured for JWT tokens + +## When not to use stateless JWT tokens + +Do not enable stateless JWT tokens if your application requires: + +- Token revocation: Immediate invalidation of access tokens before expiration +- Token introspection: Validating tokens through the introspection endpoint +- Userinfo endpoint support: Retrieving user information associated with access tokens +- Audit trail of active tokens: Database records of issued tokens for compliance or auditing purposes + +## Performance considerations + +Enabling stateless JWT tokens provides performance benefits by: + +- Eliminating database write operations for access token sessions +- Decreasing storage requirements by not persisting JWT access tokens diff --git a/src/sidebar.ts b/src/sidebar.ts index 8dd49c751..c5d8afba0 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -1236,6 +1236,7 @@ const oel: SidebarItemsConfig = [ "self-hosted/oel/oauth2/upgrade", "self-hosted/oel/oauth2/changelog", "self-hosted/oel/oauth2/token-prefix", + "self-hosted/oel/oauth2/stateless-jwt", "self-hosted/oel/oauth2/migrate-postgresql-ttl", "self-hosted/oel/oauth2/revert-database-migrations", "self-hosted/oel/oauth2/configuration",