Skip to content

OIDC IdP Broker: make the typ header of the outbound client assertion configurable (RFC 10070, client-authentication+jwt) #55260

Description

@AdemBaazouzi

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 typ header value of the client assertion, for both private_key_jwt and client_secret_jwt.
  • The solution is generic: it supports client-authentication+jwt and 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: JWT stays 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

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

No one assigned

    Labels

    Fields

    Value

    None yet

    Effort

    None yet

    Votes

    None yet

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions