Skip to content

Centralize DPoP and mTLS access token binding verification - #55402

Draft
graziang wants to merge 1 commit into
keycloak:mainfrom
graziang:issue-54277-shared-verification-context
Draft

graziang wants to merge 1 commit into
keycloak:mainfrom
graziang:issue-54277-shared-verification-context

Conversation

@graziang

Copy link
Copy Markdown
Contributor

Closes #54277

Closes keycloak#54277

Signed-off-by: Giuseppe Graziano <g.graziano94@gmail.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Security-maintainer review and integration validation are needed for sender-constraint enforcement across authentication paths, particularly proof exemptions, DPoP/mTLS behavior, and third-party verifier compatibility.

No open issues 🎉

What changed in this PR

This PR addresses #54277 by centralizing DPoP and mTLS token-binding verification through Keycloak’s token verifier SPI, reducing endpoint-specific checks and extending protection across access-token consumers.

Changes:

  • Adds shared verification contexts and DPoP/mTLS providers, with separate handling for resource requests, token exchange, and validation-only operations.
  • Integrates binding checks into registration, authorization, brokering, and other endpoints while preserving proof-free introspection.
  • Adds regression coverage and documents client requirements and upgrade implications.
File Description
tests/​utils-shared/​src/​main/​java/​org/​keycloak/​testsuite/​util/​oauth/​PermissionGrantRequest.java Adds previous-RPT request support.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oid4vc/​OID4VCBasicWallet.java Supports nonce-bearing DPoP proofs.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oid4vc/​abca/​HAIPIssuerConformanceTest.java Tests credential-request DPoP nonce validation.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oauth/​tokenexchange/​ClientDelegationCibaTest.java Tests callbacks for binding-enabled clients.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oauth/​HolderOfKeyTokenTest.java Adds mTLS binding integration coverage.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oauth/​DPoPTokenBindingTest.java Tests resource binding, replay rejection, registration, and exchange.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oauth/​DPoPTest.java Tests bound-token logout and updates exchange proofs and cookie cleanup.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​client/​ClientRegistrationAuthTest.java Tests registration-token authorization schemes.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​broker/​IdentityProviderStoreTokenV2Test.java Tests DPoP-protected broker token retrieval.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​authz/​services/​uma/​UmaGrantTypeTest.java Expands UMA token-binding and identity coverage.
services/​src/​test/​java/​org/​keycloak/​protocol/​oidc/​verifier/​TokenVerifierProviderTest.java Tests verification modes and DPoP restrictions.
services/​src/​main/​resources/​META-INF/​services/​org.keycloak.protocol.oidc.verifier.TokenVerifierProviderFactory Registers DPoP and mTLS providers.
services/​src/​main/​java/​org/​keycloak/​services/​util/​DPoPUtil.java Reuses validated proofs within a request.
services/​src/​main/​java/​org/​keycloak/​services/​resources/​IdentityBrokerService.java Uses shared token-parameter verification.
services/​src/​main/​java/​org/​keycloak/​services/​managers/​AuthenticationManager.java Adds context-aware token verification entry points.
services/​src/​main/​java/​org/​keycloak/​services/​managers/​AppAuthManager.java Passes resource authentication context to verification.
services/​src/​main/​java/​org/​keycloak/​services/​clientregistration/​ClientRegistrationTokenUtils.java Applies shared verification to registration access-token authentication.
services/​src/​main/​java/​org/​keycloak/​services/​clientregistration/​ClientRegistrationAuth.java Supports DPoP authentication and rejects invalid schemes.
services/​src/​main/​java/​org/​keycloak/​services/​clientregistration/​AbstractClientRegistrationProvider.java Recognizes DPoP access tokens for privileged operations.
services/​src/​main/​java/​org/​keycloak/​services/​clientpolicy/​condition/​ClientUpdaterContextCondition.java Recognizes DPoP-authenticated client updates.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​MtlsTokenVerifierProviderFactory.java Provides the mTLS verifier factory.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​MtlsTokenVerifierProvider.java Centralizes certificate-binding checks.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​DPoPTokenVerifierProviderFactory.java Provides the DPoP verifier factory.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​DPoPTokenVerifierProvider.java Centralizes DPoP restrictions and proof checks.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​tokenexchange/​TokenExchangeDelegationProvider.java Uses exchange-context actor-token validation.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​tokenexchange/​StandardTokenExchangeProvider.java Delegates binding checks to shared providers.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​OIDCLoginProtocolFactory.java Requires both binding providers at startup.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​grants/​PermissionGrantType.java Verifies UMA token bindings and reuses authenticated tokens.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​grants/​ciba/​endpoints/​BackchannelAuthenticationCallbackEndpoint.java Uses validation-only authentication-channel context.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​endpoints/​UserInfoEndpoint.java Replaces local binding checks with shared verification.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​endpoints/​LogoutEndpoint.java Processes DPoP proofs before refresh-token verification.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​AccessTokenIntrospectionProvider.java Uses proof-free introspection context.
services/​src/​main/​java/​org/​keycloak/​protocol/​oid4vc/​issuance/​OID4VCIssuerEndpoint.java Reads verified resource proofs for nonce validation.
services/​src/​main/​java/​org/​keycloak/​authorization/​authorization/​AuthorizationTokenService.java Refactors identity resolution and verifies subject access tokens.
server-spi-private/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​TokenVerifierProviderManager.java Coordinates context-aware validation and binding checks.
server-spi-private/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​TokenVerifierProvider.java Adds a binding hook and preserves legacy context accessors.
server-spi-private/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​TokenVerificationContext.java Defines request data and verification modes.
server-spi-private/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​verifier/​TokenBindingException.java Carries binding failures with event error codes.
docs/​guides/​securing-apps/​dpop.adoc Documents endpoint proof requirements.
docs/​guides/​securing-apps/​client-registration.adoc Documents bound-token registration authentication.
docs/​documentation/​upgrading/​topics/​changes/​changes-27_0_0.adoc Explains client and extension migration requirements.
docs/​documentation/​server_admin/​topics/​clients/​oidc/​con-advanced-settings.adoc Updates certificate-binding scope and exchange guidance.
docs/​documentation/​release_notes/​topics/​27_0_0.adoc Announces centralized binding validation.
docs/​documentation/​authorization_services/​topics/​service-authorization-obtaining-permission.adoc Documents proof requirements for bound RPTs.
core/​src/​main/​java/​org/​keycloak/​util/​DPoPGenerator.java Adds optional nonce support to proof generation.
core/​src/​main/​java/​org/​keycloak/​representations/​idm/​authorization/​AuthorizationResponse.java Preserves the issued token type in authorization responses.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review Keycloak endpoints to properly validate DPoP and mTLS bound tokens

2 participants