Add design proposal for native encrypted access tokens

[csfreitas]

Overview

This PR introduces a Draft #1 design proposal for native encrypted Access Token support in Keycloak using JSON Web Encryption (JWE).

The proposal is related to:

• Encrypt Access and Refresh Tokens keycloak#19464
• Native encrypted access tokens with single and multi-recipient JWE keycloak#51721

The primary goal is to add opt-in confidentiality for Access Token claims while preserving the existing signed Access Token behavior by default.

Scope

The proposal evaluates:

• Signed-then-encrypted Access Tokens using Nested JOSE
• JWE Compact Serialization for single-recipient encryption
• Resource Server-specific encryption recipients
• Keycloak as an optional independent JWE recipient
• General JWE JSON Serialization for multi-recipient scenarios
• Resource-aware recipient resolution
• Public SPA, BFF, gateway, Token Exchange, and M2M scenarios
• Compatibility with existing Access Token consumers and features such as UserInfo, Introspection, Revocation, UMA, DPoP, mTLS, and Token Exchange
• Access Token handling in keycloak-js and keycloak-admin-client
• Security, key rotation, token-size, and parsing considerations
• Incremental implementation milestones and open design questions

The proposed implementation remains fully opt-in and is intended to preserve current Keycloak behavior when Access Token encryption is not configured.

Design discussion

The architecture and open questions are being discussed in:

keycloak/keycloak#51721

The existing feature request is:

keycloak/keycloak#19464

This PR is intentionally submitted as a Draft to collect feedback on the architecture and public protocol/configuration surface before implementation begins.

AI assistance disclosure

AI-assisted tooling was used during the research, review, and drafting of this design proposal. All submitted content was reviewed, understood, and validated by the contributor.