Issue with Linking Social Account to an Existing Keycloak User #38615

Andruxa36rus · 2025-04-02T15:36:20Z

Andruxa36rus
Apr 2, 2025

Keycloak Version

Keycloak 26.0.8 (Docker)

Description

When attempting to generate a link for associating a social account with an existing Keycloak user using /realms/{realm}/broker/{provider}/link, the Keycloak API requires the session_state parameter. However, this parameter is missing in OpenID tokens and is not returned in responses from introspect.

In my case the user on the social network has a different email.

Documentation and code samples (including Java code in the official documentation) indicate that session_state is necessary for generating the hash. However, in the current versions of Keycloak, this parameter is unavailable.

Steps to Reproduce

A user is already registered in Keycloak.
We need to generate a link to associate a social account using /broker/{provider}/link.
Decode the user's access_token using decode_token() in python-keycloak.
The session_state parameter is missing.
Use introspect(), but session_state (or sid) is also missing there.
Attempt to pass id_token or access_token in the KEYCLOAK_IDENTITY cookie, but Keycloak rejects the tokens with errors like Expected '[Serialized-ID]' but was 'Bearer' or Expected '[Serialized-ID]' but was 'ID'.

Expected Behavior

The Keycloak API should provide session_state or sid for generating a social account linking URL.
There should be a way to retrieve this parameter via introspect() or admin API.
Clear documentation should explain which token should be used in KEYCLOAK_IDENTITY and how to format it correctly.

Actual Behavior

session_state is missing from access_token, id_token, and introspect().
A request to /users/{user_id}/sessions via admin API also does not return session_state.
Setting KEYCLOAK_IDENTITY = access_token results in Failed to verify identity token.

Environment

Keycloak 26.0.8
python-keycloak 4.6.2
Python 3.8.10

Questions

How can I use this link to link a user to a social network?

How can we retrieve session_state or sid for linking a social account?
What about Cookies?

What are the alternative ways to link a social network to an existing user with different emails?

Oluwatobi-Mustapha · 2026-04-03T02:32:22Z

Oluwatobi-Mustapha
Apr 3, 2026

Hi @Andruxa36rus, I dug into this properly since a few people are running into the same thing.

What you're seeing on Keycloak 26.0.8 is mostly a legacy-flow mismatch, not a social-email mismatch.

The /broker/{provider}/link endpoint is the legacy client-initiated linking protocol. In that flow, Keycloak validates the hash against the current browser user session (the identity cookie session), not a raw JWT passed as KEYCLOAK_IDENTITY.

Code path in 26.0.8:

IdentityBrokerService.clientInitiatedAccountLinking
hash input: nonce + cookieResult.session().getId() + clientId + providerAlias

So passing an access token or ID token into KEYCLOAK_IDENTITY won't work. That cookie field isn't for Bearer tokens - it expects Keycloak's own signed session cookie format.

Worth noting: from Keycloak 25+, session_state was removed from token claims (equivalent claim: sid), but session_state is still present in the token endpoint response.

If you must stay on 26.0.8 legacy flow, capture the session identifier from the token endpoint response (session_state) at login time, not by decoding JWT claims or introspection.

Removed session_state claim

Also, legacy linking requires an active browser SSO cookie session and proper account-link permissions (account.manage-account or account.manage-account-links).

The legacy endpoint is deprecated in current versions (AIA idp_link is available from 26.3+). The recommended path:

Use AIA: kc_action=idp_link:<provider-alias>
Docs: Client initiated account linking
Implementation: #38952

On your specific questions:

How to link with a different social email?

Different email is fine. Linking goes off the authenticated Keycloak user + broker identity, not email equality.

How to get session_state / sid for the legacy flow?

Prefer not using legacy flow now. If you must use it, use the real user session ID from the same active browser SSO session (identity cookie session).

0 replies

Navigation Menu

Repository navigation

Issue with Linking Social Account to an Existing Keycloak User #38615

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Issue with Linking Social Account to an Existing Keycloak User #38615

Uh oh!

Uh oh!

Andruxa36rus Apr 2, 2025

Keycloak Version

Description

Steps to Reproduce

Expected Behavior

Actual Behavior

Environment

Questions

Replies: 1 comment

Uh oh!

Oluwatobi-Mustapha Apr 3, 2026

Andruxa36rus
Apr 2, 2025

Oluwatobi-Mustapha
Apr 3, 2026