Relax/track draft changes to RFC7523 client authentication processing

[antonypetras]

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

Hi Kévin,

As you note in the source of OpenIddictServerHandlers.Protection.cs and similar, based on proposed changes to RFC7523:

Client authentication JWTs MUST be explicitly typed by using the typ header parameter value client-authentication+jwt another more specific explicit type value defined by a specification profiling this specification. Client authentication JWTs not using the explicit type value MUST be rejected by the authorization server.

However, I was caught out by this when using the popular JS package openid-client as it does not set any typ header.

I was going to propose this addition to openid-client, but after reviewing the latest version 11 of this draft, they appear to have backpedaled this one to a SHOULD. Further, the text of this version of the draft explains that this explicit typ serves to indicate that the client is operating in accordance with all of the updates incorporated into the standard up until this point, so simply populating this field from the client in order to comply with openiddict may send the wrong signals.

Will you consider revising the behavior of openiddict to maximize compatibility with clients that follow the standard but may be apprehensive about proactively adopting the drafts? Or at least update this to match the latest draft?

I'm happy to take a stab at it if you like.

Cheers,

Additional context

No response

[kevinchalet]

Hey Antony,

Making that configurable via a dedicated option is something I've seriously considered when adopting this breaking change in 7.x but I've decided against it because it obviously weakens the security measures introduced by that draft (which isn't really something I wanted to encourage 😄)

That said, it's clear there are still client stacks - like openid-client - that haven't implemented these security measures and in this case, it indeed hurts interoperability.

As always when there's a compatibility concern, my recommendation is to use the events model to override the default behavior when necessary.

Here, you can easily implement your own event handler - invoked after the built-in ResolveTokenValidationParameters handler - to amend the TokenValidationParameters object when ValidTokenTypes contains TokenTypeIdentifiers.Private.ClientAssertion.

Something like that:

// Note: this custom event handler should be removed once openid-client supports typed client assertions.
options.AddEventHandler<OpenIddictServerEvents.ValidateTokenContext>(builder =>
{
    builder.UseInlineHandler(static context =>
    {
        if (context.ValidTokenTypes.Count is 1 &&
            context.ValidTokenTypes.Contains(TokenTypeIdentifiers.Private.ClientAssertion))
        {
            context.TokenValidationParameters.TypeValidator = static (type, token, parameters) =>
            {
                // Assume that tokens that don't have an explicit "typ" header attached are client assertions.
                if (string.IsNullOrEmpty(type))
                {
                    type = JsonWebTokenTypes.ClientAuthentication;
                }

                if (parameters.ValidTypes is not null && parameters.ValidTypes.Any() &&
                   !parameters.ValidTypes.Contains(type, StringComparer.OrdinalIgnoreCase))
                {
                    throw new SecurityTokenInvalidTypeException(OpenIddictResources.GetResourceString(OpenIddictResources.ID0271))
                    {
                        InvalidType = type
                    };
                }

                return type;
            };
        }

        return ValueTask.CompletedTask;
    });

    builder.SetOrder(OpenIddictServerHandlers.Protection.ResolveTokenValidationParameters.Descriptor.Order + 1);
});

Ideally, you could/should even restrict this workaround to specific clients by only selecting JsonWebTokenTypes.ClientAuthentication as the default token type when (token as JsonWebToken)?.Issuer points to a client known to use the affected stack.

FWIW, I mentioned last year (in https://kevinchalet.com/2025/07/07/openiddict-7-0-is-out/) that I'd keep an eye on the compatibility reports to determine whether compatibility quirks should be added in future versions of OpenIddict but interestingly, I've only received 3 reports so far (including yours): so while it's definitely a concern, the impact isn't as massive as I initially anticipated 😅

Cheers.

[antonypetras]

Thanks Kévin,

JS devs do love to take the easy way out and probably just use client secrets instead!

Without an exhaustive set of examples of overriding every possible token handler it was tough for me to figure out where exactly to do this. I almost cracked just debugging it 😄 Thank you very much for the code, it works great.

This library could not have a better maintainer.

[kevinchalet]

My pleasure! ❤️

JS devs do love to take the easy way out and probably just use client secrets instead!

Or maybe they use mTLS-based client authentication?

(note: full mTLS support - for both client authentication and token binding - was added in 7.4.0, so if you're looking for the strongest client authentication method possible, mTLS is definitely something you may want to adopt: https://documentation.openiddict.com/configuration/mutual-tls-authentication 😃)

Without an exhaustive set of examples of overriding every possible token handler it was tough for me to figure out where exactly to do this. I almost cracked just debugging it 😄 Thank you very much for the code, it works great.

Haha yeah: the events model can definitely be intimidating when you're not familiar with it, but it's really powerful (on the other hand, you need to be careful because you can end up shooting yourself in the foot if you're doing crazy things 🤣)

This library could not have a better maintainer.

Thanks for your kind words and for sponsoring the project! Much appreciated 😍