Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ public AuthorizationResponse() {

public AuthorizationResponse(AccessTokenResponse response, boolean upgraded) {
setToken(response.getToken());
setTokenType("Bearer");
setTokenType(response.getTokenType());
setRefreshToken(response.getRefreshToken());
setRefreshExpiresIn(response.getRefreshExpiresIn());
setExpiresIn(response.getExpiresIn());
Expand Down
8 changes: 8 additions & 0 deletions core/src/main/java/org/keycloak/util/DPoPGenerator.java
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
import org.keycloak.jose.jws.JWSBuilder;
import org.keycloak.jose.jws.JWSHeader;
import org.keycloak.jose.jws.crypto.HashUtils;
import org.keycloak.representations.IDToken;
import org.keycloak.representations.dpop.DPoP;

import static org.keycloak.OAuth2Constants.DPOP_DEFAULT_ALGORITHM;
Expand Down Expand Up @@ -64,7 +65,14 @@ public static JWK createEcJwk(Key publicKey) {
}

public static String generateSignedDPoPProof(String jti, String htm, String htu, Long iat, JWSHeader jwsHeader, KeyWrapper keyWrapper, String accessToken) {
return generateSignedDPoPProof(jti, htm, htu, iat, jwsHeader, keyWrapper, accessToken, null);
}

public static String generateSignedDPoPProof(String jti, String htm, String htu, Long iat, JWSHeader jwsHeader, KeyWrapper keyWrapper, String accessToken, String nonce) {
DPoP dpop = generateDPoP(jti, htm, htu, iat, accessToken);
if (nonce != null) {
dpop.setOtherClaims(IDToken.NONCE, nonce);
}
return sign(jwsHeader, dpop, keyWrapper);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ indicates that the `claim_token` parameter references an access token. The `http
+
This parameter is *optional*. A previously issued RPT whose permissions should also be evaluated and added in a new one. This parameter
allows clients in possession of an RPT to perform incremental authorization where permissions are added on demand.
For a DPoP-bound RPT, the request proof must include the hash of that RPT in the `ath` claim.
For a certificate-bound RPT, present its matching client certificate.
+
* **permission**
+
Expand Down
5 changes: 5 additions & 0 deletions docs/documentation/release_notes/topics/27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ This protects brokered logins against assertion replay, in particular in IdP-ini
How long a consumed assertion is remembered is bounded by the new *OneTimeUse maximum age* setting of the SAML identity provider, which defaults to 1 hour.
See the upgrading guide for details.

== Consistent validation of DPoP and certificate-bound access tokens

{project_name} now consistently validates DPoP and certificate-bound access tokens across its REST endpoints, including client registration and Authorization Services.
See the upgrading guide for client requirements.

== Credential ID in credential update events

The `UPDATE_CREDENTIAL` events emitted by built-in required actions now carry the `credential_id` detail when a credential was created or updated in the {project_name} credential store, as the `REMOVE_CREDENTIAL` event already did. The detail is omitted when an external user-storage provider handles the update because there is no {project_name} credential ID to report.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,14 @@ If verification fails, {project_name} rejects the token.
In the following cases, {project_name} will verify the client sending the access token or the refresh token:

* A token refresh request is sent to the token endpoint with a holder-of-key refresh token.
* A UserInfo request is sent to UserInfo endpoint with a holder-of-key access token.
* A request is sent to the UserInfo, Admin REST, Account REST, client registration, identity brokering, Authorization Services, or credential endpoints with a holder-of-key access token.
* A logout request is sent to non-OIDC compliant {project_name} proprietary Logout endpoint with a holder-of-key refresh token.

See https://datatracker.ietf.org/doc/rfc8705/[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.

[NOTE]
====
Sender-constrained tokens like X.509 certificate-bound tokens (mTLS tokens with the `x5t#S256` confirmation claim), cannot be used as the `subject_token` parameter in link:{securing_apps_token_exchange_link}#_standard-token-exchange[Standard Token Exchange].
Certificate-bound tokens can be used as the `subject_token` in link:{securing_apps_token_exchange_link}#_standard-token-exchange[Standard Token Exchange] only by the client to which they were issued, presenting the matching certificate. Token introspection does not require the token holder's certificate.
====


Expand Down
19 changes: 19 additions & 0 deletions docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,25 @@ Existing V1 clients without this configuration receive an HTTP 403 response when

While V1 is enabled, these settings are also shown in the Admin Console for public clients. V2 hides them for public clients because it only supports confidential clients.

=== Holder-of-key access token validation
// https://github.com/keycloak/keycloak/issues/54277

{project_name} now validates mTLS certificate bindings when access tokens are used with the Admin REST, Account REST, client registration, identity brokering, Authorization Services, and credential endpoints, in addition to UserInfo.
Applications using certificate-bound tokens must present the matching client certificate when calling these endpoints.
Disabling the client's certificate-bound token setting does not remove the binding from tokens already issued.

DPoP-bound access tokens are now supported for client registration and UMA permission grants.
When sent in the `Authorization` header, these tokens require the `DPoP` scheme.
A request presenting a DPoP-bound access token requires a proof containing the access token hash, including when the token is sent in the UMA `claim_token`, `subject_token`, or `rpt` parameter.
Omit the `Authorization` header for anonymous client registration.
Malformed credentials produce an authentication error.
Token introspection continues to work without proof of possession from the token holder.

The built-in `dpop` and `mtls` providers of the `oauth2-token-verifier` SPI are required by OIDC.
Startup fails if either provider is disabled.
Existing implementations of the internal `TokenVerifierProvider` SPI and callers of the original manager method retain their token validation behavior.
Extensions authenticating requests to protected resources should pass an explicit `TokenVerificationContext` so the manager can also verify sender binding.

=== Realm-level default client scopes require `manage-realm`
// https://github.com/keycloak/keycloak/issues/50588

Expand Down
5 changes: 5 additions & 0 deletions docs/guides/securing-apps/client-registration.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,11 @@ The bearer token can be issued on behalf of a user or a Service Account. The fol

If you are using a bearer token to create clients it's recommend to use a token from a Service Account with only the `create-client` role (see link:{adminguide_link}[{adminguide_name}] for more details).

DPoP-bound access tokens are also supported. Send the token using the `DPoP` authorization scheme and include a valid `DPoP` proof header for the request.
For mTLS-bound access tokens, present the client certificate to which the token is bound. The same permissions apply to these tokens.
Initial access tokens and registration access tokens continue to use the `Bearer` authorization scheme.
Omit the `Authorization` header when registering anonymously.

[[_initial_access_token]]
=== Initial Access Token

Expand Down
9 changes: 9 additions & 0 deletions docs/guides/securing-apps/dpop.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,15 @@ When {project_name} acts as a Resource Server, it strictly enforces DPoP checks
* **UserInfo Endpoint:** Requires a valid DPoP proof matching the access token.
* **Logout Endpoint:** For public clients, the logout request (using a refresh token) requires a DPoP proof.
* **Admin & Account APIs:** Any request to {project_name}'s internal REST APIs using a DPoP token must include a valid proof.
* **Client Registration:** DPoP-bound access tokens require the `DPoP` authorization scheme and a matching proof. Initial access tokens and registration access tokens continue to use `Bearer`.
* **Authorization Services:** Requests authenticated with a DPoP access token, including UMA permission grants, require a matching proof containing the access token hash (`ath`). This also applies to DPoP access tokens passed as `subject_token`, `claim_token`, or a previous `rpt`.
A single proof covers one access token hash.
* **Identity Brokering:** Retrieving stored identity provider tokens requires a matching proof. With the V2 API, the access token is sent in the `token` form parameter; the `Authorization` header can be used for client authentication.
* **Credential Endpoint:** Requests authenticated with a DPoP access token require a matching proof.

Token introspection does not require a DPoP proof. Standard Token Exchange validates the token binding as described below.

For UMA permission grants using only client authentication, without an access token, the DPoP proof binds the issued token and does not require an `ath` claim.

=== Client Policies

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/*
* Copyright 2026 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.protocol.oidc.verifier;

import org.keycloak.common.VerificationException;

/** A binding failure with the event error to report, independent of the binding mechanism. */
public class TokenBindingException extends VerificationException {

private final String error;

public TokenBindingException(String error, String message) {
super(message);
this.error = error;
}

public TokenBindingException(String error, VerificationException cause) {
super(cause.getMessage(), cause);
this.error = error;
}

public String getError() {
return error;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
/*
* Copyright 2026 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.protocol.oidc.verifier;

import java.util.Objects;

import jakarta.ws.rs.core.UriInfo;

import org.keycloak.http.HttpRequest;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;

/**
* Request data shared by token validation and binding verification. It deliberately contains no verifier:
* a grant can verify the binding of an already validated token after authorizing its use.
*
* @param tokenString the serialized token, required when verifying the access token hash in a resource proof
* @param authorizationScheme the scheme used to present this token, not the scheme used for client authentication
*/
public record TokenVerificationContext(KeycloakSession session, RealmModel realm, UriInfo uriInfo, HttpRequest request,
String tokenString, String authorizationScheme, VerificationMode mode) {

public TokenVerificationContext {
Objects.requireNonNull(mode, "mode");
}

public enum VerificationMode {
/** Resource authentication with an explicit authorization scheme. */
RESOURCE_HEADER,
/** A resource access token in a parameter, independently of client authentication. */
RESOURCE_PARAMETER,
/** Standard token exchange checks binding after authorizing the client. */
TOKEN_EXCHANGE,
/** Run the provider's token restrictions without requiring proof from the token holder. */
VALIDATION_ONLY;

public boolean isResourceRequest() {
return switch (this) {
case RESOURCE_HEADER, RESOURCE_PARAMETER -> true;
case TOKEN_EXCHANGE, VALIDATION_ONLY -> false;
};
}
}

public static TokenVerificationContext forResource(KeycloakSession session, String tokenString, String authorizationScheme) {
return forResource(session, session.getContext().getRealm(), session.getContext().getUri(), session.getContext().getHttpRequest(), tokenString, authorizationScheme);
}

public static TokenVerificationContext forResource(KeycloakSession session, RealmModel realm, UriInfo uriInfo, HttpRequest request,
String tokenString, String authorizationScheme) {
return new TokenVerificationContext(session, realm, uriInfo, request, tokenString, authorizationScheme, VerificationMode.RESOURCE_HEADER);
}

public static TokenVerificationContext forResourceParameter(KeycloakSession session, String tokenString) {
return fromSession(session, tokenString, VerificationMode.RESOURCE_PARAMETER);
}

public static TokenVerificationContext forTokenExchange(KeycloakSession session, String tokenString) {
return fromSession(session, tokenString, VerificationMode.TOKEN_EXCHANGE);
}

public static TokenVerificationContext forIntrospection(KeycloakSession session) {
return fromSession(session, null, VerificationMode.VALIDATION_ONLY);
}

public static TokenVerificationContext forAuthenticationChannel(KeycloakSession session) {
return fromSession(session, null, VerificationMode.VALIDATION_ONLY);
}

public static TokenVerificationContext forIdentityToken(KeycloakSession session, RealmModel realm, UriInfo uriInfo, String tokenString) {
return new TokenVerificationContext(session, realm, uriInfo, session.getContext().getHttpRequest(), tokenString, null, VerificationMode.VALIDATION_ONLY);
}

private static TokenVerificationContext fromSession(KeycloakSession session, String tokenString, VerificationMode mode) {
return new TokenVerificationContext(session, session.getContext().getRealm(), session.getContext().getUri(),
session.getContext().getHttpRequest(), tokenString, null, mode);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import jakarta.ws.rs.core.UriInfo;

import org.keycloak.TokenVerifier;
import org.keycloak.common.VerificationException;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.provider.Provider;
Expand All @@ -20,11 +21,30 @@ public interface TokenVerifierProvider extends Provider {
*/
void additionalAccessTokenVerifications(TokenVerifierProviderContext context);

/** Verifies sender binding after token validation and, for token exchange, client authorization. */
default void verifyTokenBinding(AccessToken token, TokenVerificationContext context) throws VerificationException {
}

@Override
default void close() {
}

// Add more fields if needed...
record TokenVerifierProviderContext(TokenVerifier<AccessToken> accessTokenVerifier, KeycloakSession session, RealmModel realm, UriInfo uriInfo) {
record TokenVerifierProviderContext(TokenVerifier<AccessToken> accessTokenVerifier, TokenVerificationContext verificationContext) {

public TokenVerifierProviderContext(TokenVerifier<AccessToken> accessTokenVerifier, KeycloakSession session, RealmModel realm, UriInfo uriInfo) {
this(accessTokenVerifier, new TokenVerificationContext(session, realm, uriInfo, null, null, null, TokenVerificationContext.VerificationMode.VALIDATION_ONLY));
}

public KeycloakSession session() {
return verificationContext.session();
}

public RealmModel realm() {
return verificationContext.realm();
}

public UriInfo uriInfo() {
return verificationContext.uriInfo();
}
}
}
Original file line number Diff line number Diff line change
@@ -1,14 +1,40 @@
package org.keycloak.protocol.oidc.verifier;

import java.util.Set;

import org.keycloak.TokenVerifier;
import org.keycloak.common.VerificationException;
import org.keycloak.models.KeycloakSession;
import org.keycloak.protocol.oidc.verifier.TokenVerifierProvider.TokenVerifierProviderContext;
import org.keycloak.representations.AccessToken;

public class TokenVerifierProviderManager {

/**
* Additional verifications of access token provided by {@link TokenVerifierProvider}
*
* @param context for the token verification
*/
public void additionalAccessTokenVerifications(TokenVerifierProvider.TokenVerifierProviderContext context) {
context.session().getAllProviders(TokenVerifierProvider.class)
.forEach(tokenVerifierProvider -> tokenVerifierProvider.additionalAccessTokenVerifications(context));
/** Adds token restrictions and, for resource authorization, the binding check. */
public void additionalAccessTokenVerifications(TokenVerifier<AccessToken> verifier, TokenVerificationContext context) {
additionalAccessTokenVerifications(new TokenVerifierProviderContext(verifier, context));
}

public void additionalAccessTokenVerifications(TokenVerifierProviderContext checks) {
TokenVerificationContext context = checks.verificationContext();
Set<TokenVerifierProvider> providers = context.session().getAllProviders(TokenVerifierProvider.class);
providers.forEach(provider -> provider.additionalAccessTokenVerifications(checks));
if (context.mode().isResourceRequest()) {
checks.accessTokenVerifier().withChecks(token -> {
verifyTokenBinding(providers, token, context);
return true;
});
}
}

/** The standard exchange grant calls this after authorizing the requesting client. */
public void verifyTokenExchangeBinding(KeycloakSession session, AccessToken token) throws VerificationException {
verifyTokenBinding(session.getAllProviders(TokenVerifierProvider.class), token, TokenVerificationContext.forTokenExchange(session, null));
}

private void verifyTokenBinding(Set<TokenVerifierProvider> providers, AccessToken token, TokenVerificationContext context) throws VerificationException {
for (TokenVerifierProvider provider : providers) {
provider.verifyTokenBinding(token, context);
}
}
}
Loading
Loading