Skip to content

feat: add should_handle hook for JWT client auth algorithm routing#894

Open
liudonggalaxy wants to merge 1 commit into
authlib:mainfrom
liudonggalaxy:Dongliu/jwt_client_auth_algorithm_routing
Open

feat: add should_handle hook for JWT client auth algorithm routing#894
liudonggalaxy wants to merge 1 commit into
authlib:mainfrom
liudonggalaxy:Dongliu/jwt_client_auth_algorithm_routing

Conversation

@liudonggalaxy

@liudonggalaxy liudonggalaxy commented May 15, 2026

Copy link
Copy Markdown
Contributor

What kind of change does this PR introduce?

This is a feature implementation.

Description

Add a should_handle(headers, claims) method to JWTBearerClientAssertion that subclasses can override to filter JWT assertions by algorithm type. This enables registering separate handlers for client_secret_jwt (symmetric) and private_key_jwt (asymmetric) on the same authorization server.

When both auth methods use the same client_assertion_type (urn:ietf:params:oauth:client-assertion-type:jwt-bearer), the server must inspect the JWT alg header to route to the correct handler. Without this hook, the first registered handler may attempt verification with the wrong key type and raise InvalidClientError, preventing the correct handler from being tried.

Usage:

SYMMETRIC_ALGS = {"HS256", "HS384", "HS512"}

class ClientSecretJWTAuth(JWTBearerClientAssertion):
    CLIENT_AUTH_METHOD = "client_secret_jwt"

    def should_handle(self, headers, claims):
        return headers.get("alg") in SYMMETRIC_ALGS

class PrivateKeyJWTAuth(JWTBearerClientAssertion):
    CLIENT_AUTH_METHOD = "private_key_jwt"

    def should_handle(self, headers, claims):
        return headers.get("alg") not in SYMMETRIC_ALGS

The default should_handle() returns True, maintaining full backward compatibility.

Checklist

  • The commits follow the conventional commits specification.
  • You ran the linters with prek.
  • You wrote unit test to demonstrate the bug you are fixing, or to stress the feature you are bringing.
  • You reached 100% of code coverage on the code you edited, without abusive use of pragma: no cover
  • If this PR is about a new feature, or a behavior change, you have updated the documentation accordingly.

  • You consent that the copyright of your pull request source code belongs to Authlib's author.

@liudonggalaxy liudonggalaxy force-pushed the Dongliu/jwt_client_auth_algorithm_routing branch 6 times, most recently from 09777d6 to 7151349 Compare May 16, 2026 03:14
@liudonggalaxy liudonggalaxy changed the title Add should_handle hook for JWT client auth algorithm routing feat: add should_handle hook for JWT client auth algorithm routing May 16, 2026
Add a 'should_handle(headers, claims)' method to JWTBearerClientAssertion
that subclasses can override to filter JWT assertions by algorithm type.
This enables registering separate handlers for symmetric (client_secret_jwt)
and asymmetric (private_key_jwt) algorithms on the same authorization server.

When should_handle returns False, the handler returns None, allowing the
authentication framework to try the next registered method. The default
implementation returns True, maintaining full backward compatibility.

This pattern is useful for servers that need to support both
client_secret_jwt (HS256/384/512) and private_key_jwt (RS256, ES256,
EdDSA) simultaneously with different key resolution logic for each.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@liudonggalaxy liudonggalaxy force-pushed the Dongliu/jwt_client_auth_algorithm_routing branch from 7151349 to 5181148 Compare May 16, 2026 03:35
@liudonggalaxy liudonggalaxy marked this pull request as ready for review May 16, 2026 03:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant