8000 Add client OIDC compatibility mode setting for configuring the header type in access tokens. by laurids · Pull Request #37573 · keycloak/keycloak · GitHub
[go: up one dir, main page]
Skip to content

Add client OIDC compatibility mode setting for configuring the header type in access tokens. - #37573

Merged
mposolda merged 1 commit into
keycloak:mainfrom
laurids:issue-36696-client-compatibility-setting
Mar 24, 2025
Merged

Add client OIDC compatibility mode setting for configuring the header type in access tokens.#37573
mposolda merged 1 commit into
keycloak:mainfrom
laurids:issue-36696-client-compatibility-setting

Conversation

@laurids
@laurids laurids commented Feb 21, 2025
Copy link
Copy Markdown
Contributor

Add client OIDC compatibility mode setting for configuring the header type in access tokens.

If this setting is off, the access token header type will be "at+jwt" in compliance with RFC 9068, see rfc9068#section-2.1. If the setting is on, the access token header type will be "JWT". The setting is on per default, meaning existing clients will issue access tokens with header type "JWT", whereas the setting is off for new clients such that the access token header type is "at+jwt".

Closes #36696

Thank you @thomasdarimont for the idea for this solution: #34183 (comment)

@laurids
laurids requested review from a team as code owners February 21, 2025 11:40
@laurids laurids mentioned this pull request Feb 21, 2025
Closed
This was referenced Feb 21, 2025
Closed
Closed
Closed
thomasdarimont
thomasdarimont approved these changes Feb 21, 2025
View reviewed changes
@thomasdarimont thomasdarimont left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@laurids laurids mentioned this pull request Feb 21, 2025
Closed
@mposolda mposolda self-assigned this Feb 24, 2025
@mposolda
mposolda commented Feb 28, 2025
Copy link
Copy Markdown
Contributor

@laurids Thanks for the addition! This is good stuff, but unfortunately Keycloak needs to be backwards compatible and not introduce any breaking changes in the behaviour for supported features (unless necessary for security reasons etc).

Considering this, will this be possible to rename the option to something like Use at+jwt type for access tokens and make it OFF for both new and existing clients? This means we don't need to care about migration and backwards compatibility. When doing this, you won't need to change anything in the "Upgrading guide", however you can instead document this in the "Release notes of Keycloak 26.2.0" .

@laurids
laurids commented Mar 3, 2025
Copy link
Copy Markdown
Contributor Author

Hi @mposolda, thank you.
Just for clarification, when exporting or importing a realm, existing clients will keep their behavior with the current proposed solution. I assume this is what is used e.g. when migrating?
But are you saying that we also must avoid changing the default behavior for newly created clients? If so, then I will make the change you suggested.

edewit
edewit previously approved these changes Mar 7, 2025
View reviewed changes
@edewit edewit left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mposolda
mposolda commented Mar 12, 2025
Copy link
Copy Markdown
Contributor

@laurids The thing is, that when someone creates new client in the admin console, he would now have different behaviour and the token would be at+jwt instead of the old type (unless he explicitly update the switch, which he did not needed to do in previous versions). Which might be also considered unexpected change in the behaviour... In Keycloak, there is an attempt to be more strict in backwards compatibility and no change the previous behaviour to avoid compatibility issues for the people. So the changes in the behaviour should ideally be always "opt-in" due to this :-/

Hopefully we have options how to improve on that in the future. For example ability to introduce "Client types" feature will make it possible that in the new versions, people will have at+jwt on their clients by default. But that is for the future...

@laurids
laurids commented Mar 12, 2025
Copy link
Copy Markdown
Contributor Author

@mposolda Ok, I understand. I will implement the change when I get time, hopefully soon:)

@mposolda
mposolda commented Mar 13, 2025
Copy link
Copy Markdown
Contributor

@laurids Thanks a lot!

@laurids
laurids commented Mar 18, 2025
Copy link
Copy Markdown
Contributor Author

@mposolda If I flip the setting so that On sets at+jwt, I am thinking it makes sense to move it to another section than "OpenID Connect Compatibility Modes". In my opinion, it would no longer align with the description:

This section is used to configure settings for backward compatibility with older OpenID Connect / OAuth 2 adaptors. It is useful especially if your client uses an older version of Keycloak / RH-SSO adapter.

Instead, it could for example be placed here:
image
It could also be a drop-down menu, but as long as it only has two values I guess a toggle is fine?

Another option would be to keep it under "OpenID Connect Compatibility Modes" with On being JWT, and keeping the default as true, but just not setting it to false for new clients (i.e. removing these lines: OIDCLoginProtocolFactory.java). This way, the behavior change is also completely opt-in.

What do you prefer?

@mposolda
mposolda commented Mar 20, 2025
Copy link
Copy Markdown
Contributor

@laurids Thanks for the ideas. My vote is to do like you did in the screenshot. So have it as on/off switch Use "at+jwt" as access token header type in the Fine grained OpenID Connect Configuration section.

@laurids
laurids force-pushed the issue-36696-client-compatibility-setting branch from ac62b2d to 1b2b0f8 Compare March 21, 2025 10:14
@laurids
Add client OIDC configuration for setting the header type in access t…
0b60585 
…okens.

If this setting is On, the access token header type will be "at+jwt" in compliance with RFC 9068, see https://datatracker.ietf.org/doc/html/rfc9068#section-2.1. If the setting is Off, the access token header type will be "JWT". The setting is Off per default.

Closes keycloak#36696

Signed-off-by: Laurids Møller Jepsen <laurids.jepsen@cryptomathic.com>
@laurids
laurids force-pushed the issue-36696-client-compatibility-setting branch from 1b2b0f8 to 0b60585 Compare March 21, 2025 10:58
@laurids
laurids commented Mar 21, 2025
Copy link
Copy Markdown
Contributor Author

@mposolda PR has been updated.

mposolda
mposolda approved these changes Mar 24, 2025
View reviewed changes
@mposolda mposolda left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@laurids Thanks!

@mposolda
mposolda merged commit 8f7c187 into keycloak:main Mar 24, 2025
@laurids laurids mentioned this pull request Mar 31, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mposolda mposolda mposolda approved these changes
@edewit edewit edewit left review comments
+1 more reviewer
@thomasdarimont thomasdarimont thomasdarimont approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

@mposolda mposolda

Labels

flaky-test team/cloud-native team/core-clients team/core-iam

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Support token type "at+jwt" for OAuth 2 access tokens

4 participants

@laurids @mposolda @edewit @thomasdarimont
0