Support Post-Quantum Cryptography (ML-DSA) OIDC token signing and key… by arnabnandy7 · Pull Request #50358 · keycloak/keycloak

arnabnandy7 · 2026-06-25T22:06:47Z

Description

This PR implements support for Post-Quantum Cryptography (PQC) signature algorithms (ML-DSA-44, ML-DSA-65, ML-DSA-87) in Keycloak. It extends Keycloak's core JWK, JWS, and SPI providers to support OIDC token signing and verification using these FIPS 204 standardized algorithms.

Key Changes

Core Algorithm Mappings: Integrated ML-DSA-44, ML-DSA-65, and ML-DSA-87 constants and mapped them to KeyType.AKP in JavaAlgorithm.java.
JWK & Thumbprint: Configured JWKSUtils to support AKP JWK thumbprints (using alg and pub claims) and updated JWKSServerUtils to format AKP keys into JWK representations.
Signer/Verifier SPI Providers: Implemented new SignatureProvider and ClientSignatureVerifierProvider factories for ML-DSA and registered them via ServiceLoader.
Admin Console Key Generation: Created a new generated ML-DSA key provider GeneratedMlDsaKeyProvider and factory so that administrators can generate and rotate ML-DSA keys directly from the Realm Keys management page.

Testing & Verification

All modifications have been thoroughly validated with existing and updated test cases:

DefaultCryptoAKPJWKTest: Passed (verified AKP JWK decoding/encoding).
DefaultCryptoJWKSUtilsTest: Passed (verified thumbprint calculations for AKP).
CryptoUtilsTest: Passed (verified ML-DSA signature providers retrieval).

Test execution command:

mvn test -pl crypto/default,services -am "-Dtest=DefaultCryptoAKPJWKTest,DefaultCryptoJWKSUtilsTest,CryptoUtilsTest"

AI Agent Disclosure

In accordance with Keycloak's generative AI usage guidelines (Section 11.4 of CONTRIBUTING.md), this PR was generated and verified using Antigravity, an autonomous AI coding assistant. The agent analyzed the codebase, proposed the implementation plan, created the new provider classes, and executed tests to verify correctness.

Closes #50355

Copilot

Pull request overview

This PR adds support for post-quantum ML-DSA (FIPS 204) signature algorithms in Keycloak for OIDC/JWS by introducing AKP key handling, new signature/verifier SPI providers, and an admin key-provider for generated ML-DSA realm keys.

Changes:

Added ML-DSA-44/65/87 algorithm → JCA mapping and associated KeyType.AKP wiring (signing/verifying + JWKS thumbprints).
Introduced ML-DSA SignatureProvider and ClientSignatureVerifierProvider implementations and registered them via ServiceLoader.
Added an admin-console key provider to generate/rotate ML-DSA keys and updated tests to ensure provider discovery.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
services/src/test/java/org/keycloak/crypto/CryptoUtilsTest.java	Extends provider-discovery test coverage to ML-DSA algorithms.
services/src/main/resources/META-INF/services/org.keycloak.keys.KeyProviderFactory	Registers the generated ML-DSA key provider factory.
services/src/main/resources/META-INF/services/org.keycloak.crypto.SignatureProviderFactory	Registers ML-DSA signature provider factories.
services/src/main/resources/META-INF/services/org.keycloak.crypto.ClientSignatureVerifierProviderFactory	Registers ML-DSA client signature verifier factories.
services/src/main/java/org/keycloak/protocol/oidc/utils/JWKSServerUtils.java	Emits AKP keys into JWKS responses.
services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProviderFactory.java	Adds generated ML-DSA key provider factory + fallback key generation logic.
services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProvider.java	Loads persisted/generated ML-DSA keys into `KeyWrapper`.
services/src/main/java/org/keycloak/keys/AbstractMlDsaKeyProviderFactory.java	Defines shared ML-DSA key provider factory config/validation building blocks.
services/src/main/java/org/keycloak/keys/AbstractMlDsaKeyProvider.java	Implements common ML-DSA `KeyProvider` behavior and `KeyWrapper` creation.
services/src/main/java/org/keycloak/crypto/MLDSASignatureProvider.java	Implements server-side ML-DSA signing/verifying via the Signature SPI.
services/src/main/java/org/keycloak/crypto/MLDSAClientSignatureVerifierProvider.java	Implements client assertion verification entry-point for ML-DSA.
services/src/main/java/org/keycloak/crypto/MLDSA44SignatureProviderFactory.java	Factory for ML-DSA-44 SignatureProvider.
services/src/main/java/org/keycloak/crypto/MLDSA65SignatureProviderFactory.java	Factory for ML-DSA-65 SignatureProvider.
services/src/main/java/org/keycloak/crypto/MLDSA87SignatureProviderFactory.java	Factory for ML-DSA-87 SignatureProvider.
services/src/main/java/org/keycloak/crypto/MLDSA44ClientSignatureVerifierProviderFactory.java	Factory for ML-DSA-44 ClientSignatureVerifierProvider.
services/src/main/java/org/keycloak/crypto/MLDSA65ClientSignatureVerifierProviderFactory.java	Factory for ML-DSA-65 ClientSignatureVerifierProvider.
services/src/main/java/org/keycloak/crypto/MLDSA87ClientSignatureVerifierProviderFactory.java	Factory for ML-DSA-87 ClientSignatureVerifierProvider.
services/src/main/java/org/keycloak/crypto/ClientMLDSASignatureVerifierContext.java	Adds ML-DSA-specific client signature verification context.
core/src/main/java/org/keycloak/util/KeyWrapperUtil.java	Enables generic asymmetric signer/verifier contexts for AKP keys.
core/src/main/java/org/keycloak/util/JWKSUtils.java	Adds AKP thumbprint member handling (including `alg`).
core/src/main/java/org/keycloak/crypto/JavaAlgorithm.java	Adds ML-DSA algorithm and hash mappings; maps ML-DSA to `KeyType.AKP`.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 57 out of 57 changed files in this pull request and generated no new comments.

keycloak-github-bot · 2026-08-21T08:06:59Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.cluster.GroupInvalidationClusterTest#crudWithoutFailover

Keycloak CI - Clustering IT

org.opentest4j.AssertionFailedError: expected: <false> but was: <true>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertFalse.failNotFalse(AssertFalse.java:63)
	at org.junit.jupiter.api.AssertFalse.assertFalse(AssertFalse.java:36)
...

Report flaky test

org.keycloak.testsuite.cluster.GroupInvalidationClusterTest#crudWithFailover

Keycloak CI - Clustering IT

jakarta.ws.rs.WebApplicationException: Create method returned status Forbidden (Code: 403); expected status: Created (201). Response body: {"error":"HTTP 403 Forbidden"}
	at org.keycloak.testsuite.admin.ApiUtil.getCreatedId(ApiUtil.java:38)
	at org.keycloak.testsuite.cluster.GroupInvalidationClusterTest.createEntity(GroupInvalidationClusterTest.java:70)
	at org.keycloak.testsuite.cluster.GroupInvalidationClusterTest.createEntity(GroupInvalidationClusterTest.java:32)
	at org.keycloak.testsuite.cluster.AbstractInvalidationClusterTest.createEntityOnCurrentFailNode(AbstractInvalidationClusterTest.java:111)
...

Report flaky test

keycloak-github-bot

Unreported flaky test detected, please review

Copilot

Pull request overview

Copilot reviewed 53 out of 53 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 53 out of 53 changed files in this pull request and generated no new comments.

Suppressed comments (1)

services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProviderFactory.java:151

A missing or malformed persisted public key lets the Base64 decoder's runtime exception escape the component-validation path, producing either a generic “invalid provider type” response or a server error instead of an ML-DSA key validation error. Wrap decoding in ComponentValidationException, as the generated EdDSA provider does.

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2026-08-21T09:24:52Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.cluster.JGroupsCertificateRotationClusterTest#testCoordinatorHasScheduleTask

Keycloak CI - Clustering IT

org.awaitility.core.ConditionTimeoutException: Assertion condition defined as a Lambda expression in org.keycloak.testsuite.cluster.JGroupsCertificateRotationClusterTest expected: <2> but was: <1> within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.AssertionCondition.await(AssertionCondition.java:119)
	at org.awaitility.core.AssertionCondition.await(AssertionCondition.java:31)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1160)
...

Report flaky test

Copilot

Copilot review overview

🟡 Changes recommended

Existing exact-list integration tests will fail when the newly registered ML-DSA providers are available.

Review effort: Balanced
Findings: 1

Open (1)

Update algorithm list assertions for ML-DSA providers · New

Resolved since last review (2)

ML-DSA attestations never reach this verifier call because validateJwsHeader runs first and maps…
ML-DSA proofs are still rejected before this raw-name value is used. validateJwsHeader maps the…

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>

Copilot

Copilot review overview

🔵 Needs a closer look

The security-sensitive cryptographic changes span multiple token-verification paths and require final human interoperability and provider review.

Review effort: Balanced
Findings: None

Resolved since last review (1)

Update algorithm list assertions for ML-DSA providers

Copilot AI balanced review requested due to automatic review settings June 25, 2026 22:06

arnabnandy7 requested a review from a team as a code owner June 25, 2026 22:06

Copilot started reviewing on behalf of arnabnandy7 June 25, 2026 22:07

View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

arnabnandy7 force-pushed the feature/post-quantum-keys branch from 56e7462 to 7017ed6 Compare June 25, 2026 22:24

arnabnandy7 requested a review from Copilot June 25, 2026 22:25

Copilot started reviewing on behalf of arnabnandy7 June 25, 2026 22:25

View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread services/src/main/java/org/keycloak/crypto/MLDSASignatureProvider.java Resolved

Comment thread services/src/main/java/org/keycloak/protocol/oidc/utils/JWKSServerUtils.java Resolved

Copilot AI review requested due to automatic review settings June 25, 2026 22:48

Copilot started reviewing on behalf of arnabnandy7 June 25, 2026 22:49

View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread services/src/main/java/org/keycloak/protocol/oidc/utils/JWKSServerUtils.java Resolved

Comment thread services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProviderFactory.java Resolved

Copilot AI review requested due to automatic review settings June 26, 2026 09:24

Copilot started reviewing on behalf of arnabnandy7 June 26, 2026 09:24

View session

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Comment thread core/src/main/java/org/keycloak/util/KeyWrapperUtil.java Resolved

Copilot AI review requested due to automatic review settings June 26, 2026 09:35

Copilot started reviewing on behalf of arnabnandy7 June 26, 2026 09:35

View session

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Comment thread services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProviderFactory.java Resolved

Comment thread core/src/main/java/org/keycloak/util/KeyWrapperUtil.java Resolved

mposolda mentioned this pull request Jun 30, 2026

Investigate and plan what is needed for OpenID Connect and OAuth 2.0 to be PQC ready #48824

Open

Copilot AI review requested due to automatic review settings July 10, 2026 16:50

Copilot started reviewing on behalf of arnabnandy7 July 10, 2026 16:50

View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 18:14

Copilot started reviewing on behalf of arnabnandy7 July 10, 2026 18:15

View session

arnabnandy7 force-pushed the feature/post-quantum-keys branch from 75fb3bf to 66bc1cd Compare July 10, 2026 18:16

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread services/src/test/java/org/keycloak/crypto/CryptoUtilsTest.java Resolved

Comment thread core/src/main/java/org/keycloak/util/JWKSUtils.java Resolved

Copilot AI review requested due to automatic review settings July 10, 2026 18:18

Copilot started reviewing on behalf of arnabnandy7 July 10, 2026 18:19

View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread services/src/main/java/org/keycloak/crypto/MLDSAClientSignatureVerifierProvider.java Resolved

Comment thread core/src/main/java/org/keycloak/crypto/JavaAlgorithm.java Resolved

Comment thread services/src/main/java/org/keycloak/keys/GeneratedMlDsaKeyProviderFactory.java Resolved

Copilot AI review requested due to automatic review settings July 10, 2026 18:25

Copilot started reviewing on behalf of arnabnandy7 July 10, 2026 18:25

View session

arnabnandy7 requested a review from a team as a code owner August 21, 2026 07:06

Copilot started reviewing on behalf of arnabnandy7 August 21, 2026 07:06

View session

Copilot AI reviewed Aug 21, 2026

View reviewed changes

keycloak-github-bot Bot added the flaky-test label Aug 21, 2026

keycloak-github-bot Bot reviewed Aug 21, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 21, 2026 08:22

arnabnandy7 force-pushed the feature/post-quantum-keys branch from a55b302 to ed0d9b2 Compare August 21, 2026 08:22

Copilot started reviewing on behalf of arnabnandy7 August 21, 2026 08:22

View session

arnabnandy7 force-pushed the feature/post-quantum-keys branch from afc29ec to a9132e0 Compare August 21, 2026 08:24

Copilot AI reviewed Aug 21, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 21, 2026 08:26

Copilot started reviewing on behalf of arnabnandy7 August 21, 2026 08:26

View session

Copilot AI reviewed Aug 21, 2026

View reviewed changes

keycloak-github-bot Bot reviewed Aug 21, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings September 30, 2026 04:36

arnabnandy7 force-pushed the feature/post-quantum-keys branch from a9132e0 to 8d7bafc Compare September 30, 2026 04:36

Copilot started reviewing on behalf of arnabnandy7 September 30, 2026 04:36

View session

Copilot AI reviewed Sep 30, 2026

View reviewed changes

Comment thread .../main/resources/META-INF/services/org.keycloak.crypto.ClientSignatureVerifierProviderFactory Resolved

Support ML-DSA OIDC token signing and key generation

6878ee0

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>

Copilot AI balanced review requested due to automatic review settings September 30, 2026 08:37

arnabnandy7 force-pushed the feature/post-quantum-keys branch from 8d7bafc to 6878ee0 Compare September 30, 2026 08:37

Copilot started reviewing on behalf of arnabnandy7 September 30, 2026 08:38

View session

Copilot AI reviewed Sep 30, 2026

View reviewed changes

This was referenced Oct 1, 2026

Allow JWS header with algorithms not in the Algorithm enum #53413

Open

Allow JWS header with algorithms not in the Algorithm enum #53415

Open

Conversation

arnabnandy7 commented Jun 25, 2026

Description

Key Changes

Testing & Verification

AI Agent Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

keycloak-github-bot Bot commented Aug 21, 2026

Unreported flaky test detected

org.keycloak.testsuite.cluster.GroupInvalidationClusterTest#crudWithoutFailover

org.keycloak.testsuite.cluster.GroupInvalidationClusterTest#crudWithFailover

Uh oh!

keycloak-github-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!