Repository navigation
Description
Enhancement Description
When an OpenID Connect v1.0 or OAuth v2 identity provider uses JWT client authentication (private_key_jwt or client_secret_jwt), Keycloak signs a client assertion and sends it to the token endpoint of the external IDP. The JOSE header of this assertion always contains typ: JWT. The value is hardcoded in AbstractOAuth2IdentityProvider.authenticateTokenRequest (new JWSBuilder().type(OAuth2Constants.JWT)) and no identity provider setting can change it. This is the same in 26.7.5, 26.8.2 and on main.
RFC 10070 (November 2026, updates RFC 7523) says in section 4 that client authentication JWTs SHOULD be explicitly typed by using the typ header parameter value client-authentication+jwt, or a more specific explicit type defined by a profile. This request is to make the typ value of the outbound client assertion configurable, so that Keycloak can follow this recommendation when it acts as a client of an external IDP.
Value Proposition
Interoperability. Some authorization servers validate the typ header of client authentication JWTs when it is present. For example, PingFederate 13.1 with its default settings accepts an assertion without typ or with client-authentication+jwt, but not one typed with the generic JWT, and OpenIddict 7 was reported to accept only client-authentication+jwt (openiddict-core issue 2539). With such an IDP, brokering with private_key_jwt or client_secret_jwt fails at the code exchange with invalid_client, even when "Client Assertion Audience" is set to the issuer, and nothing in the identity provider configuration can fix it. The only workaround I can see is a custom identity provider extension that overrides authenticateTokenRequest.
Standards alignment. RFC 10070 explains that explicit typing lets a client signal that its assertion follows the updated requirements. The audience can already be aligned with the existing "Client Assertion Audience" setting. The type cannot.
Goals
- A setting on OpenID Connect v1.0 and OAuth v2 identity providers to choose the
typheader value of the client assertion, for bothprivate_key_jwtandclient_secret_jwt. - The solution is generic: it supports
client-authentication+jwtand is not tied to one external IDP or to a single value, because RFC 10070 also allows more specific explicit types defined by profiles. - No change for existing identity providers:
typ: JWTstays the default, unless maintainers prefer another default. - The setting is available in the admin console next to "Client Assertion Audience", in the admin REST API and in realm import and export, and it is documented.
Non-Goals
- Changing how Keycloak validates the client assertions it receives as an authorization server (see Align JwtClient authentication with latest OIDC spec updates #38751).
- Changing the default audience of the outbound client assertion.
- Federated client authentication and JWT authorization grants.
Discussion
No response
Notes
Implementation idea: a new string in OAuth2IdentityProviderConfig (for example clientAssertionType), read in authenticateTokenRequest instead of the constant, next to clientAssertionAudience and clientAssertionSigningAlg. An on/off switch for client-authentication+jwt would be simpler but would not cover profile specific types.
Side note: RFC 10070 section 4 also requires the issuer identifier of the authorization server as the sole audience value, while the default audience of the outbound assertion is still the token endpoint URL. That could be a separate follow-up.
I am happy to contribute a pull request with tests and documentation if the approach is acceptable.
Metadata
Metadata
Assignees
Labels
Type
Fields
Value
Effort
Votes
Projects
- StatusShow more project fieldsOpen
Activity