Follow RFC for self-contained JWT access token #8646

tnorimat · 2021-10-26T01:18:42Z

tnorimat
Oct 26, 2021
Collaborator

RFC for self-contained JWT access token has been published.

RFC 9068 JSON Web Token (JWT) Profile for OAuth 2.0 Access Token

The current keycloak's access token (and refresh token) is self-contained JWT access token.
It might be good for keycloak's access token to follow this RFC. WDYT?

stianst · 2021-10-26T11:30:57Z

stianst
Oct 26, 2021
Maintainer

Do you know what the state of it is beyond "proposed standard"?

1 reply

tnorimat Oct 26, 2021
Collaborator Author

The next state is Internet Standard.

The standardization process of RFC in standard track is described by RFC 2026 The Internet Standards Process -- Revision 3 . It states that there are three maturity level, Proposed Standard, Draft Standard and Internet Standard at the highest maturity level.

Draft Standard is merged into Proposed Standard by RFC 6410 Reducing the Standards Track to Two Maturity Levels . The current characteristics of Proposed Standard is described by RFC 7127 Characterization of Proposed Standards .

Even if RFC 6749 The OAuth 2.0 Authorization Framework, its state is Proposed Standard.

stianst · 2021-10-26T11:35:46Z

stianst
Oct 26, 2021
Maintainer

If this specification gets real traction and not push-back I'm all for following this RFC, but would like to make sure it is on the road to becoming an official standard.

Wondering also a bit on how we could do it, and how much it conflicts with existing claims we have. A basic approach could just be to have a client-scope for it, which is for example what we did for the Microprofile JWT standard.

4 replies

tnorimat Oct 26, 2021
Collaborator Author

I've not yet investigate the difference between the current keycloak's access token and this RFC completely, but I've found the following points.

JOSE header's "typ" field : RFC states that should be "application/at+jwt" or "at+jwt". The latter is recommended. The current keycloak access token set "JWT" to it.
The fields for meaning group : RFC states that such the field's name should be "groups".
The fields for meaning role: RFC states that such the field's name should be "roles".

stianst Nov 1, 2021
Maintainer

Quite a few breaking changes, which obviously makes it harder to handle. The groups/roles can be solved by having different "RFC" compliant client scopes, while the typ may be harder.

jbman Nov 5, 2021

Note: JSON Web Token RFC 5.2 states that default "typ" of a JSON web token should be "JWT", but Keycloak sets "Bearer", which is only meant to be used in the JSON response but not inside the JWT.
See https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java#L757

lmm-git Apr 17, 2024

The RFC does also state that a client_id attribute is required. As far as I know it is not possible to add such an attribute to all clients beside of configuring a hardcoded claim for each client.

tnorimat · 2021-11-01T08:44:37Z

tnorimat
Nov 1, 2021
Collaborator Author

@stianst I see, IMO, we need not to follow this specification in a hurry. If it is needed in the future, we would resume this discussion.

0 replies

lmm-git · 2024-04-17T13:15:08Z

lmm-git
Apr 17, 2024

Just stumbled on this discussion as we are currently looking for a standardized way to interpret access tokens and RFC 9068 seems to be the only standard documenting a layout, some attributes and verification steps so far. So maybe we could get the adoption going again?

0 replies

jstale · 2024-06-14T13:26:13Z

jstale
Jun 14, 2024

Hi @stianst, is this now officially supported in v25? I saw a change merged that addresses access token type but didn't notice RFC mentioned in release notes.

0 replies

laurids · 2024-08-29T10:46:25Z

laurids
Aug 29, 2024

Hi @tnorimat and @stianst.

According to rfc9068#section-2.1:

JWT access tokens MUST include this media type in the "typ" header parameter

It then says:

it is RECOMMENDED that the "application/" prefix be omitted. Therefore, the "typ" value used SHOULD be "at+jwt".

Therefore, it is not just a recommendation, but a requirement that the typ header is either application/at+jwt or at+jwt.
From these two choices, the recommended one is at+jwt.

There is already a switch in DefaultTokenManager.java#L239 on the token category to set a specific type for logout tokens.

Could we extend this with a case for the ACCESS category? There is already a constant defined for at+jwt in TokenUtil.java#L46.

I realize that this is a breaking change, but without such a change, Keycloak is not compatible with OAuth2 resource servers that verify the typ header according to rfc9068.
In case the ACCESS category is used for other types of tokens than OAuth2, is there any way to only do this for OAuth2 tokens? I would argue that such a solution could be done in a patch version, and not necessarily require a major version bump, but I understand if you think it should still be done in a major version.
I am looking forward to hearing your thoughts.

5 replies

NobodysNightmare Feb 5, 2025

I realize that this is a breaking change, but without such a change, Keycloak is not compatible with OAuth2 resource servers that verify the typ header according to rfc9068.

This is also what I see as a problem. Right now I wouldn't suggest any resource server to perform the typ validation, because IDP support for the new header is not yet there. If now Keycloak is waiting for adoption on the client side, we run into a chicken-and-egg problem.

It would be cool if Keycloak could at least be configured for compliance with the new standard.

laurids Feb 5, 2025

Hi @NobodysNightmare, I created an issue for this here: #36696
I'm also suggesting to add a configuration option like it has already been done for other types of token.
I would appreciate if you upvoted the issue and maybe added a comment about your perspective as well:)

jstale Feb 5, 2025

We opted to fork Keycloak for the time being and implement the change in DefaultTokenManager:

private String type(TokenCategory category) {
        switch (category) {
            case LOGOUT:
                return TokenUtil.TOKEN_TYPE_JWT_LOGOUT_TOKEN;

            case ACCESS:
                return TokenUtil.TOKEN_TYPE_JWT_ACCESS_TOKEN;
            default:
                return "JWT";
        }
    }

This is not ideal but the change is minor and could be a solution for types of projects where at+jwt validation is mandatory.

laurids Mar 31, 2025

@jstale From version 26.2, there will be an option to make the header type "at+jwt" via a per-client configuration. See #37573

jstale Mar 31, 2025

@jstale From version 26.2, there will be an option to make the header type "at+jwt" via a per-client configuration. See #37573

That's great news! Thanks a lot!

Pappmann · 2026-10-16T13:11:45Z

Pappmann
Oct 16, 2026

Follow-up on the typ work from 26.2.0: the client_id claim required by RFC 9068 §2.2 is still missing for user-facing flows.

Since 26.2.0 there is the client option Use "at+jwt" as access token header type, which covers RFC 9068 §2.1. Section 2.2 additionally lists the claims a JWT access token MUST contain: iss, exp, aud, sub, client_id, iat, jti.

On Keycloak 26.8.0, access tokens issued through the authorization code flow carry azp but no client_id, and this does not change when the option is enabled: I turned it on for a client and generated an example access token (Client scopes -> Evaluate), which has the at+jwt header type but still no client_id. The only built-in client_id mapper I could find is the "Client ID" user session note mapper in the service_account scope (OIDCLoginProtocolFactory), which only helps for service account tokens. TokenManager.initToken sets issuedFor (-> azp) and nothing else for the client.

Why it matters in practice. Resource servers that validate according to the RFC 9068 profile and require client_id reject Keycloak tokens. We hit this when connecting claude.ai's remote MCP connector (an OAuth client) to an MCP server acting as a resource server: the login succeeded and the token was issued, but every request was answered with 401 because client_id was absent.

Workaround. A Hardcoded claim mapper client_id = <clientId> in the client's dedicated scope. It works, but it has to be configured per client, the value has to be kept in sync with the client ID, and it is easy to miss when a realm is recreated.

Proposal. When Use "at+jwt" as access token header type is enabled for a client, Keycloak also adds client_id (= the client's clientId) to the access token, for example next to token.issuedFor(...) in TokenManager.initToken. It is opt-in, so existing setups are unchanged. An alternative would be a built-in client_id mapper that can be attached to any client scope. Which would you prefer, or is there a reason to leave this out?

If there is interest, I'm happy to implement it (with a test next to AccessTokenTest.testTokenResponseUsingRfc9068HeaderType and documentation) and follow up with an enhancement request issue and PR as described in CONTRIBUTING.md.

Disclosure: I used an AI assistant (Claude) for research and drafting this comment. I have reviewed it.

0 replies

Follow RFC for self-contained JWT access token #8646

Uh oh!

tnorimat Oct 26, 2021 Collaborator

Replies: 7 comments · 10 replies

Uh oh!

stianst Oct 26, 2021 Maintainer

Uh oh!

tnorimat Oct 26, 2021 Collaborator Author

Uh oh!

stianst Oct 26, 2021 Maintainer

Uh oh!

tnorimat Oct 26, 2021 Collaborator Author

Uh oh!

stianst Nov 1, 2021 Maintainer

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tnorimat Nov 1, 2021 Collaborator Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tnorimat
Oct 26, 2021
Collaborator

Replies: 7 comments 10 replies

stianst
Oct 26, 2021
Maintainer

tnorimat Oct 26, 2021
Collaborator Author

stianst
Oct 26, 2021
Maintainer

tnorimat Oct 26, 2021
Collaborator Author

stianst Nov 1, 2021
Maintainer

tnorimat
Nov 1, 2021
Collaborator Author