Issue 38664 contextual mac algorithm by jimmychakkalakal · Pull Request #54482 · keycloak/keycloak

jimmychakkalakal · 2026-10-30T12:40:00Z

Summary

• Clarifies algorithm labels in the client’s advanced OpenID Connect settings.
• Shows “MAC algorithm” for symmetric choices, “signature algorithm” for asymmetric choices, and a neutral label
when no algorithm is selected.
• Updates the tooltips to explain which key is used for each algorithm type.

This addresses the terminology concern raised in PR #48988 (#48988) for client settings that offer both algorithm types.

Closes #38664.

Co-authored by Palash Thakur (@palasht75) (https://github.com/palasht75).

Copilot

🟡 Changes recommended

Switching from private_key_jwt to client_secret_jwt can retain and submit an incompatible RS256 value despite a blank selection, while the shared tooltip misstates the default and contextual label tests remain incomplete.

3 open issues

What changed in this PR

Updates Admin Console terminology to distinguish symmetric MAC algorithms from asymmetric signature algorithms, extending the clarification from #48988 to contextual client settings and related documentation.

Changes:

Adds selection-dependent labels and tooltips to advanced OpenID Connect settings.
Uses MAC terminology for client-secret JWT authentication and filters identity-provider options to symmetric algorithms.
Updates administrator documentation and adds Credentials-tab regression tests.

File	Description
`js/apps/admin-ui/test/clients/details.ts`	Adds helpers for algorithm labels and options.
`js/apps/admin-ui/test/clients/details.spec.ts`	Tests MAC versus signature terminology in Credentials.
`js/apps/admin-ui/src/identity-providers/add/OIDCAuthentication.tsx`	Adjusts assertion labels and options by authentication method.
`js/apps/admin-ui/src/clients/credentials/SignedJWT.tsx`	Uses MAC labels for client-secret JWT authentication.
`js/apps/admin-ui/src/clients/advanced/FineGrainOpenIdConnect.tsx`	Makes algorithm labels and tooltips selection-dependent.
`js/apps/admin-ui/maven-resources/theme/keycloak.v2/admin/messages/messages_en.properties`	Adds contextual labels and key-usage explanations.
`docs/documentation/server_admin/topics/identity-broker/oidc.adoc`	Clarifies OIDC client assertion algorithms and defaults.
`docs/documentation/server_admin/topics/identity-broker/oauth2.adoc`	Clarifies OAuth2 client assertion algorithms and defaults.
`docs/documentation/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc`	Explains shared-secret JWT authentication using MAC terminology.

_{Review effort: Balanced}

Copilot

🟢 Approval recommended

No active review issues block the contextual algorithm-label and broker algorithm-selection updates.

No open issues 🎉

3 resolved since last review

_{Review effort: Balanced}

mposolda

@jimmychakkalakal Thanks!

IMO the PR is a bit too far. In both client "Advanced setting" options or in the OIDC/OAuth2 Identity provider, I would rather prefer to keep it simpler and use always single label and tooltip.

So for example for "request" object, it is OK for me to keep label like Request object signature algorithm . I agree that Request object algorithm might be more clear as it is more universal, but at the same time, the OIDC specification uses name like request_object_signing_alg . At the same time, it might be good to just update tooltips and make them more clear that in case of HS algorithms, the term "signing" is maybe not so accurate? So maybe the tooltip could be something like:

JWA algorithm used to sign/authenticate an OIDC request object sent in the 'request' or 'request_uri' parameter. Asymmetric algorithms use a client private key to sign request object; HS algorithms use the client secret to create HMAC of a request object.

For OIDC/OAuth2 identity providers, it is maybe OK to use single option and just change it for the universal Client assertion algorithm . So basically align the behavior according to how you documented it (see my inline comments for the documentation).

mposolda · 2026-11-11T09:19:55Z

-|Client Assertion Signature Algorithm
-|Signature algorithm to create JWT assertion as client authentication.
-In the case of JWT signed with private key or Client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. `RS256` is adapted in the case of JWT signed with private key.  `HS256` is adapted in the case of Client secret as jwt.
+|Client Assertion Algorithm


This documentation looks correct to me. However the behavior in the admin console is not aligned with that. It seems what admin console does is that option name is changing dynamically between Client assertion signature algorithm or Client assertion MAC algorithm according to which "Client authentication" method is selected.

IMO it would be easier to keep the documentation and rather simplify the logic in the admin console. So that the admin console in the IDP page will have just option Client Assertion Algorithm with the tooltip aligned to what you mentioned in this documentation. The option will allow both signing and MAC algorithms.

mposolda · 2026-11-11T09:20:08Z

-|Client Assertion Signature Algorithm
-|Signature algorithm to create JWT assertion as client authentication.
-In the case of JWT signed with private key or Client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. `RS256` is adapted in the case of JWT signed with private key.  `HS256` is adapted in the case of Client secret as jwt.
+|Client Assertion Algorithm


Same like previous comment from oauth2.adoc

Closes keycloak#38664 Signed-off-by: Palash Thakur <117917450+palasht75@users.noreply.github.com> # Conflicts: # js/apps/admin-ui/test/clients/details.spec.ts # Conflicts: # js/apps/admin-ui/test/clients/details.spec.ts

Signed-off-by: Jimmy Chakkalakal <jimmy.chakkalakal@ibm.com>

Copilot

🟢 Approval recommended

No active review issues remain with the terminology and algorithm-selection changes.

No open issues 🎉

_{Review effort: Balanced}

Co-authored-by: Palash Thakur <117917450+palasht75@users.noreply.github.com> Signed-off-by: Jimmy Chakkalakal <jimmy.chakkalakal@ibm.com>

Copilot

🟡 Changes recommended

Advanced OIDC settings still use fixed “signature algorithm” labels for HMAC and empty selections instead of the promised selection-dependent MAC, signature, or neutral labels.

1 open issue

Use selection-dependent labels in Advanced OIDC settings · New

_{Review effort: Balanced}

 membershipUserLdapAttributeHelp=Used only if the Membership Attribute Type is UID. It is the name of the LDAP attribute on the user, which is used for membership mappings. It is typically 'uid'. For example, if the value of 'Membership User LDAP Attribute' is 'uid' and the LDAP group has 'memberUid\: john', it is expected that particular LDAP user will have the attribute 'uid\: john'.
 samlCapabilityConfig=SAML capabilities
-accessTokenSignatureAlgorithmHelp=JWA algorithm used for signing access tokens.
+accessTokenSignatureAlgorithmHelp=JWA algorithm used to sign/authenticate access tokens. Asymmetric algorithms create a digital signature with a realm private key; HS algorithms create an HMAC with a realm secret key.


keycloak-github-bot Bot added the team/core-protocols label Oct 30, 2026

jimmychakkalakal force-pushed the issue-38664-contextual-mac-algorithm branch from 96e854d to 091508b Compare October 30, 2026 12:45

jimmychakkalakal force-pushed the issue-38664-contextual-mac-algorithm branch 2 times, most recently from 037b06e to 04e6726 Compare November 6, 2026 14:57

jimmychakkalakal requested a balanced review from Copilot November 6, 2026 14:58

Copilot started reviewing on behalf of jimmychakkalakal November 6, 2026 14:58

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Comment thread js/apps/admin-ui/src/identity-providers/add/OIDCAuthentication.tsx Resolved

Comment thread js/apps/admin-ui/maven-resources/theme/keycloak.v2/admin/messages/messages_en.properties Resolved

Comment thread js/apps/admin-ui/src/clients/advanced/FineGrainOpenIdConnect.tsx Resolved

jimmychakkalakal force-pushed the issue-38664-contextual-mac-algorithm branch from 04e6726 to 374ffb6 Compare November 6, 2026 15:47

jimmychakkalakal requested a balanced review from Copilot November 6, 2026 15:48

Copilot started reviewing on behalf of jimmychakkalakal November 6, 2026 15:48

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

jimmychakkalakal marked this pull request as ready for review November 6, 2026 16:32

jimmychakkalakal requested review from a team as code owners November 6, 2026 16:32

mposolda reviewed Nov 11, 2026

View reviewed changes

mposolda self-assigned this Nov 11, 2026

palasht75 and others added 2 commits November 12, 2026 13:27

Use MAC terminology for client secret JWT algorithms

17cb638

Closes keycloak#38664 Signed-off-by: Palash Thakur <117917450+palasht75@users.noreply.github.com> # Conflicts: # js/apps/admin-ui/test/clients/details.spec.ts # Conflicts: # js/apps/admin-ui/test/clients/details.spec.ts

Clarify MAC terminology for client secret JWT auth

c854b6d

Signed-off-by: Jimmy Chakkalakal <jimmy.chakkalakal@ibm.com>

jimmychakkalakal force-pushed the issue-38664-contextual-mac-algorithm branch from 374ffb6 to 80fa460 Compare November 12, 2026 13:27

Copilot AI balanced review requested due to automatic review settings November 12, 2026 13:27

Copilot started reviewing on behalf of jimmychakkalakal November 12, 2026 13:28

View session

Copilot AI reviewed Nov 12, 2026

View reviewed changes

Clarify algorithm labels in client settings

69dfe4e

Co-authored-by: Palash Thakur <117917450+palasht75@users.noreply.github.com> Signed-off-by: Jimmy Chakkalakal <jimmy.chakkalakal@ibm.com>

jimmychakkalakal force-pushed the issue-38664-contextual-mac-algorithm branch from 80fa460 to 69dfe4e Compare November 12, 2026 15:27

Copilot AI balanced review requested due to automatic review settings November 12, 2026 15:27

Copilot started reviewing on behalf of jimmychakkalakal November 12, 2026 15:28

View session

Copilot AI reviewed Nov 12, 2026

View reviewed changes

Navigation Menu

Repository navigation

Issue 38664 contextual mac algorithm - #54482

Issue 38664 contextual mac algorithm#54482
jimmychakkalakal wants to merge 3 commits into
keycloak:mainfrom
jimmychakkalakal:issue-38664-contextual-mac-algorithm

jimmychakkalakal commented Oct 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

mposolda left a comment

Uh oh!

mposolda Nov 11, 2026

Uh oh!

mposolda Nov 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jimmychakkalakal commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

mposolda left a comment

Choose a reason for hiding this comment

Uh oh!

mposolda Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

mposolda Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jimmychakkalakal commented Oct 30, 2026 •

edited

Loading