RFC 7523 JWTs as Authorization Grants

[jbman]

Summary

Keycloak supports "Using JWTs for Client Authentication" from RFC 7523.
The same RFC also defines "Using JWTs as Authorization Grants":

This document defines how a JWT Bearer Token can be used to request
an access token when a client wishes to utilize an existing trust
relationship, expressed through the semantics of the JWT, without a
direct user-approval step at the authorization server.
from RFC 7523 - Section 1

When this is supported, the client can use grant_type urn:ietf:params:oauth:grant-type:jwt-bearer. The client sends a JWT token as assertion and may request a specific OAuth scope. The JWT token contains the sub claim which specifies the user for the resulting access token.

In this discussion we would like to receive feedback on the idea to support this grant at Keycloak and also on the options how it could be supported.

Option 1: Generic support

Use case: Trust a client application to handle user authentication

The grant is useful if user authentication should be handled completely by a client instead of the authorization server. The client can issue the tokens on its own and get an access token for any user.

Possible implementation at Keycloak:

Support at Keycloak requires configuration of a trusted issuer and its public key or public Key JWKS endpoint. The JWT bearer grant would be enabled at a client by configuring a set of trusted issuer configurations

Benefits:

• Implementation could be fully compliant with RFC, but has additional restriction of client authentication.

Option 2: Support for OIDC ID tokens of configured Identity providers

Use case: Allow silent authorization by accepting OpenId Connect ID tokens

In this use case a client wants to use a valid OpenId Connect ID token to prove user authentication, without the need of any user interaction like login or consent.

The client can not just get an access token for any use. It needs to obtain an ID token through regular OIDC login.

Possible implementation at Keycloak:

Keycloak already has OIDC IdP configurations for identity brokering. The JWT bearer grant would be enabled at a client by configuring a set of Keycloak OIDC IdPs. Such a client can then use a valid IdP ID token frokm one of these IdPs to get an access token for a user.

Benefits:

• Minimal configuration at Keycloak needed.
• Usage of grant restricted to configured IdPs, so that it is not required to trust the client to have a secure authentication process but the client is only trusted in secure ID token handling.

[jbman]

Other authorization servers supporting the grant

We could find the following servers supporting the grant:

• Ory Hydra – This documentation defines configuration and constraints: https://www.ory.sh/docs/hydra/guides/oauth2-grant-type-jwt-bearer#oauth2-jwt-bearer-grant-type-validation
• Authlete – Authlete does only receive the request and does generic request validation. Actual authorization is added with custom implementation: https://www.authlete.com/developers/jwt_authorization_grant/
• PingFederate Server - Supports the grant but unclear how trust is configured: https://docs.pingidentity.com/bundle/pingfederate-111/page/klo1564002964192.html

[jbman]

Any feedback on that?

Here is another summary what it is for:
"RFC 7523 JWTs as Authorization Grants" basically allows a client to impersonate any user and get an access token. One specific client is trusted to handle authentication completely on its own.
Existing resource servers usually expect the resource owner as subject in the JWT. A service account client is not enough because it can't a current user into the token.

Here is the case how we would use it:
We have multiple parties who use Keycloak as authorization server. They want to work together as partners and want to provide one application to the user, where all the resources show up. The app could use the OAuth 2.0 auth code flow at each authorization server to get the users resources, but this means the user is directed to the login of each authorization server.
The goal is to get that working without user interaction. The partners want to trust the application to handle login. The application can go to every authentication server and issue an access token as defined by "RFC 7523 JWTs as Authorization Grants" from machine to machine.

[ben95cd]

I work for MITRE and one of my projects has the need to utilize JWTs as authorization grants much like the use case described above. We have a reference implementation for this feature that we'd like to push up to the community.
 
The implementation matches option 1 above where we trust an application to handle user authentication and is compliant with RFC 7523.
 
Implementation Summary
 
The implementation includes 3 major changes:
 

1. Add a configuration block in the client Advanced tab that enables administrators to configure trusted issuer, audience, and certificate combinations.
    
   This configuration will be used to validate the signed JWTs sent to the token endpoint.
    
2. Add a handler for the jwt-bearer grant type on the token endpoint, as described in RFC-7523.
    
   When a client specified jwt-bearer in the grant_type claim of the token request, Keycloak will load a provider from the newly created assertion grant SPI.
    
3. Default assertion grant provider for the assertion grant SPI
    
   A default assertion grant provider was implemented. This provider verifies the JWT as described in RFC-7523. First, it confirms the client is confidential. It will then verify the provided JWT by looping through each configured trusted issuer for the client and attempt to verify the JWT using the certificate, checking that the audience and issuer also match the configuration. If the JWT successfully verifies, Keycloak then checks if the client has the 'impersonate' permission for the user specified in the JWT 'sub' claim. Assuming all checks pass, Keycloak creates a session for the user and returns the generated tokens.
    

In this implementation the existing 'impersonate' permission is utilized to determine if the client is authorized to perform this grant type.

[pedroigor]

@ben95cd Can't we solve this better by building it on top of the token exchange?

The mechanics in 7523 look kinda similar to how 8693 works. In fact, the SPI you are proposing is something we need to enable in token exchange so that people can extend the feature without having to base their implementation on top of the default token exchange provider.

The impersonate permission you are referring to is also available when doing token exchanges already. It also addresses client authentication in addition to authorization grant (sub in https://www.rfc-editor.org/rfc/rfc7523#section-3).

I don't know but there is an overlap between the two. For instance, both are based on 7521. Being 8693 a more recent standard, don't you think it supersedes 7523?

[ben95cd]

Hey @pedroigor I appreciate the feedback!

In my implementation I actually did convert the TokenExchangeContext into a more generic abstract class representing an OIDC token request context, and then extend that to create the AssertionGrantContext.

I didn't want to refactor too much of the original TokenExchange code but if we wanted to build it off token exchange we could convert the TokenExchangeSpi into a generic OIDCTokenRequestSpi where the supports() function would take the requested grant type as part of the context, and determine if its supported. The handler for the token endpoint TokenEndpoint.java could then have a default case then would find the first OIDCTokenRequestProvider supporting that grant type and process the request.

Is that something that would be in scope for this PR? Or should I submit this PR with the assertion grant changes and then start a new issue to clean up the token exchanger and assertion grant code into a unified Spi?

[pedroigor]

@ben95cd Perhaps we can start with what you have and then figure out how it overlaps with the token exchange.

I'm not really thinking about unifying both SPI but include the set of interfaces you are using to handle different assertion types as part of the Token Exchange SPI.

Wdyt?

[pedroigor]

Btw, this feature is definitely useful as you can see from the comments you are getting.

Once you send the PR or link to a branch, I can start writing a design document based on your requirements as well as give others the chance to provide more information about their use cases and requirements.

[ben95cd]

@pedroigor that sounds great! I'm just working on cleaning up some final changes and then will open up a PR.

[ben95cd]

@pedroigor just wanted to let you know that i opened up the PR. #24512

[schlomo]

I'm trying to implement https://circleci.com/docs/openid-connect-tokens/ with Keycloak, so that code running in a CI pipeline can exchange a CircleCI token for a JWT impersonating a user or for an auto-generated user matching the metadata in the CircleCI token (which has all the info on git repo, branch etc.).

Can this proposal solve that use case too? Or what would be right way to implement that? Much appreciated!

[ben95cd]

Hey @schlomo this feature would definitely be able to address that use case. The CI pipeline could mint a signed JWT and present it to Keycloak with the sub specifying the user you want to impersonate. Keycloak would then respond with an access token for that user. The RFC doesn't specifically cover just in time provisioning of users, however, you could always create the user right before you send the assertion grant request with the Keycloak API.

[schlomo]

I also added #24286 in an attempt to describe where I got stuck with the current Keycloak.

Creating users via API is very much an anti-thesis to the whole motivation for doing this, which is to create a trust relationship between a single git repo and its related CI pipelines and our Keycloak. That means that the OIDC ID token from CircleCI (GitHub Actions works just the same way) is the only means of authentication and also authorization here.

Would it be possible to create some kind of mapping rules in Keycloak to control the automatic user generation and to define the scopes or roles or groups that can be granted based on the claims that are encoded in the OIDC token?

This feature is really important to get rid of static credentials for "test users" that get hard-coded or shared around.

[Waterstraal]

We have a use case where we want to generate a PDF by visiting a webpage with Puppeteer from within an API. To be able to do this, Puppeteer must be authorized for the given page. We want to reuse the session / token of the user that requests the PDF.

Will this RFC address such a use case? Or are there alternative methods of solving this issue? Thank you!

[glennlod]

Hi,

I have a usecase where I need to be able to support both client credentials as the JWT Bearer Authorization grant. However this is not yet implemented I believe ? JWT Bearer assertion (authentication) does not cover our needs.
Is there any idea on timeline ?

Thank you!