Experimental feature for JWT Authorization Grant #43624

graziang · 2025-10-21T10:02:29Z

Created a new OAuth2GrantTypeBase implementation named JWTAuthorizationGrantProvider, to be used only with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". This allows future support for other authorization grant types, such as SAML.
Introduced JWTAuthorizationGrantValidationContext, a class that provides context and centralizes JWT assertion validation. It helps avoid code duplication by having a single place for validation logic. Currently, it includes only basic checks. For example signature validation (idp side) and reuse check still to be implemented.
It should be considered a possible refactor to reuse the logic from JWTClientValidator to reduce code duplication in JWT validation. Saving assertion state in this case is probably not needed.
Introduced the JWTAuthorizationGrantProvider interface with two methods:
- isIssuer(): Used to validate the issuer based on the IDP configuration. I added this method because the issuer might be stored differently depending on the identity provider, for example, in OIDCIdentityProvider it’s stored under config node "issuer".
  Should we remove this method and standardize how issuer validation is performed across all identity providers?
- validateAuthorizationGrantAssertion(): Takes a JWTAuthorizationGrantValidationContext to perform all JWT assertion validations (like signature) according to the IDP specification, and returns a BrokeredIdentityContext. In this PR, there is no specific validation implemented for the OIDCIdentityProvider, only a simple implementation that returns the username.
Added JWTAuthorizationGrantTest, using the new test suite, which includes some basic tests.

Closes keycloak#43444 Signed-off-by: Giuseppe Graziano <[email protected]>

rmartinc

Nice @graziang! Just the call to the AlternativeLookupProvider is really requested in my review. The other comments are suggestions or questions I have. 😄

I also remember talking about a replay check for this grant. I suppose we will manage it as a follow-up. But maybe we can create all the related issues (replay check, use username or id to lookup the user or something more complicated,...) to not forget about extra points (we can even not implement them, but we have them into consideration).

rmartinc · 2025-10-22T07:21:14Z

services/src/main/java/org/keycloak/protocol/oidc/grants/JWTAuthorizationGrantType.java

+    private IdentityProviderModel getAuthorizationGrantIdentityProviderModel(KeycloakSession session, String issuer) {
+        return session.identityProviders().getAllStream()
+                .filter(idpModel -> {
+                    IdentityProvider idp = IdentityBrokerService.getIdentityProvider(session, idpModel.getAlias());
+                    return idp instanceof JWTAuthorizationGrantProvider authorizationGrantProvider && authorizationGrantProvider.isIssuer(issuer);
+                })
+                .findFirst()
+                .orElse(null);
+    }


I think that here we need to use the same idea Stian used to locate the IdP in SPIFFE that caches the lookup. It's the AlternativeLookupProvider. Maybe with this the isIssuer method is not needed.

+1, good catch!

Thanks! I missed this provider. Removed isIssuer() and used the AlternativeLookupProvider. I had to make some adjustments to check that the found idp provider is an JWTAuthorizationGrantProvider

rmartinc · 2025-10-22T07:23:47Z

services/src/main/java/org/keycloak/protocol/oidc/grants/JWTAuthorizationGrantType.java

+            //apply identity provider mappers
+            Set<IdentityProviderMapperModel> mappers = session.identityProviders().getMappersByAliasStream(identityProviderModel.getAlias())
+                    .collect(Collectors.toSet());
+            KeycloakSessionFactory sessionFactory = session.getKeycloakSessionFactory();
+            for (IdentityProviderMapperModel mapper : mappers) {
+                IdentityProviderMapper target = (IdentityProviderMapper)sessionFactory.getProviderFactory(IdentityProviderMapper.class, mapper.getIdentityProviderMapper());
+                target.preprocessFederatedIdentity(session, realm, mapper, brokeredIdentityContext);
+            }


Maybe better to execute the mappers in the validateAuthorizationGrantAssertion inside the IdP?

I wonder if we need to call mappers at all? Added also inline comment related to that.

Yes, you are right. If we are just getting the user by the ID, no mapper is needed here. @graziang already removed this part.

Yeah we probably don't need mappers, we only need to find the linked user using the subject from the assertion JWT, at least for now. Removed the mapper block.

rmartinc · 2025-10-22T07:43:47Z

services/src/main/java/org/keycloak/protocol/oidc/grants/JWTAuthorizationGrantType.java

+
+            //user must exist in keycloak
+            FederatedIdentityModel federatedIdentityModel = new FederatedIdentityModel(identityProviderModel.getAlias(), brokeredIdentityContext.getUsername(), brokeredIdentityContext.getUsername(), brokeredIdentityContext.getToken());
+            UserModel user = this.session.users().getUserByFederatedIdentity(realm, federatedIdentityModel);


With this the subject of the token should be the user id in keycloak. Don't remember what was finally decided here. For me it's OK for this first implementation, but probably we need something more (at least I would add the username too, I remember we talked about more complicated ideas).

AFAIR it was decided to go this way initially.

We may need something more just if requested by users though... In that case, we would need some additional configuration on the IDP for how to map the assertion to the Keycloak UserModel ...

mmm I have a doubt if we need just that the subject of the assertion JWT must be the username of the user in keycloak without any link to the idp, or if we need a link between the keyloak user and the idp and the subject of the assertion can be the linked external id of the keycloak user

I think that the link is needed, because the caller is using the ID in the broker to identify the user, so in the JWT authorization grant realm we have only that ID (ID in the original realm) in the link. So I think that it's OK like it is now.

mposolda

@graziang This is good start, Thanks!

I've added few minor comments inline, but I hope we can go with the PR.

Before merging, I suggest to create few sub-issues, which might be done as a follow-up to this (suggesting sub-issues before merging this, so we don't forget about it later).

Those are:

It seems there is not yet validation of the signature on JWT assertion. This will need to be added as a follow-up at least (Together with some tests for test with the invalid signature assertion etc). The validation should be probably done against JWK keys of the identity provider (provided for example from jwks_url of IDP).
The JWTAuthorizationGrantValidationContext seems to have some validation, which duplicates the code, which can be rather re-used from other places. Especially validation of the "token being active" etc. It can be probably good to re-use AbstractJWTClientValidator somehow .
Scopes processing (See the inline comment, which I've added upon your TODO). Not yet sure about the details, but just some issue as a placeholder to doublecheck what we need to do for scopes can be good.

Feel free to create additional sub-issues if you are aware of some follow-up tasks not yet being done in this PR.

mposolda · 2025-10-22T07:56:53Z

services/src/main/java/org/keycloak/protocol/oidc/grants/JWTAuthorizationGrantType.java

+            }
+
+            //apply identity provider mappers
+            Set<IdentityProviderMapperModel> mappers = session.identityProviders().getMappersByAliasStream(identityProviderModel.getAlias())


I am not sure if it makes sense to call preprocessFederatedIdentity on IdentityProviderMapper considering that we don't call any other methods of the mappers (like methods importNewUser or updateBrokeredUser ). Any reason for that? If there is no reason, I vote for remove this block.

Removed the mappers!

mposolda · 2025-10-22T07:58:16Z

services/src/main/java/org/keycloak/broker/oidc/OIDCIdentityProvider.java

+
+    @Override
+    public BrokeredIdentityContext validateAuthorizationGrantAssertion(JWTAuthorizationGrantValidationContext context) {
+        if (!Profile.isFeatureEnabled(Profile.Feature.JWT_AUTHORIZATION_GRANT)) {


Do we need additional feature check here? Considering that the method is invoked from JWTAuthorizationGrantType, which itself is disabled when the feature is disabled, then maybe this additional check might be redundant?

Yeah is not so useful, removed.

mposolda · 2025-10-22T07:59:08Z

services/src/main/java/org/keycloak/protocol/oidc/grants/JWTAuthorizationGrantType.java

+                throw new RuntimeException("User not found");
+            }
+
+            String scopeParam = formParams.getFirst(OAuth2Constants.SCOPE);


It might be good to create follow-up issues for this one.

Closes keycloak#43444 Signed-off-by: Giuseppe Graziano <[email protected]>

graziang · 2025-10-22T10:07:56Z

@mposolda @rmartinc Thanks for the review! I've applied the suggestions in a separate commit and created the follow up tasks!

rmartinc

Thank @graziang!

mposolda

@graziang @rmartinc Thanks for the updates and additional feedback and review! I hope to merge once tests are OK (did re-run the tests as test failures seems unrelated to the changes in this PR).

graziang marked this pull request as ready for review October 21, 2025 13:32

graziang requested a review from a team as a code owner October 21, 2025 13:32

mposolda self-assigned this Oct 22, 2025

Experimental feature for JWT Authorization Grant

aa8d393

Closes keycloak#43444 Signed-off-by: Giuseppe Graziano <[email protected]>

rmartinc suggested changes Oct 22, 2025

View reviewed changes

mposolda reviewed Oct 22, 2025

View reviewed changes

Experimental feature for JWT Authorization Grant

a9b3423

Closes keycloak#43444 Signed-off-by: Giuseppe Graziano <[email protected]>

graziang force-pushed the issue-43444 branch from bdca05b to a9b3423 Compare October 22, 2025 08:57

rmartinc approved these changes Oct 22, 2025

View reviewed changes

mposolda approved these changes Oct 22, 2025

View reviewed changes

mposolda merged commit a25a026 into keycloak:main Oct 22, 2025
125 of 127 checks passed

Experimental feature for JWT Authorization Grant #43624

Experimental feature for JWT Authorization Grant #43624

Uh oh!

Conversation

graziang commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rmartinc left a comment

Choose a reason for hiding this comment

Uh oh!

rmartinc Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mposolda left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

graziang commented Oct 22, 2025

Uh oh!

rmartinc left a comment

Choose a reason for hiding this comment

Uh oh!

mposolda left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

graziang commented Oct 21, 2025 •

edited

Loading

rmartinc Oct 22, 2025 •

edited

Loading

mposolda left a comment •

edited

Loading