Repository navigation
Conversation
Closes keycloak#54277 Signed-off-by: Giuseppe Graziano <g.graziano94@gmail.com>
Contributor
There was a problem hiding this comment.
🔵 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #54277