What is Cross-Realm Trust in Keycloak?
Keycloak builds walls between realms on purpose. Cross-realm trust is the deliberate, carefully controlled gate you cut into that wall when two separate identity worlds genuinely need to talk to each other.
Imagine two separate countries, each with its own passport office, its own citizens, and its own laws about who’s allowed in. By default, a passport from one country means nothing at the other’s border — that separation is the whole point of having two countries in the first place. But sometimes two countries sign a treaty: “if our passport office vouches for someone, let them in without a full new application.” Keycloak’s realms work exactly like those separate countries — each one is a fully isolated space with its own users, clients, and rules, and nothing crosses that boundary automatically. Cross-Realm Trust is the deliberate, configured “treaty” that lets one realm’s users be recognized and trusted by another realm, without merging the two into one. This guide explains why realms are isolated in the first place, how trust between them is actually built, what happens internally when a cross-realm login happens, and how real organizations design and secure these relationships. No prior background in multi-realm systems is assumed.
1Core Concepts
What is a realm, and why is it isolated?
A realm in Keycloak is a completely self-contained space — its own users, its own clients, its own roles, its own security policies. A user account in one realm simply does not exist, as far as another realm is concerned, unless something is deliberately configured to bridge them. This isolation is a deliberate design choice: it lets a single Keycloak deployment safely host, say, a company’s own employees in one realm and an entirely separate customer base in another, with zero risk of one group accidentally gaining access meant for the other.
So what does “cross-realm trust” actually mean?
Because realms don’t talk to each other by default, organizations that genuinely need one realm’s users to access resources protected by another realm have to explicitly build that connection. Cross-Realm Trust is the umbrella term for the patterns used to do this — most commonly, configuring one realm as an identity provider for another (the same identity brokering mechanism used for external providers like Google, but applied between two realms of the same Keycloak installation), or using token exchange to let a token issued in one realm be swapped for a token valid in another, under tightly controlled conditions.
Picture a large university with separate academic departments, each issuing its own student ID cards, each with its own building access rules. Normally, a Physics department ID card doesn’t open doors in the Chemistry building. But if the two departments agree to a joint research program, the university might set up a specific arrangement: “Chemistry’s door readers will accept a Physics ID card, but only for people on this specific approved list, and only for these particular labs.” That deliberate, narrow arrangement — not a blanket merging of the two departments — is exactly the shape of cross-realm trust.
Why not just use one big realm for everything?
It might seem simpler to avoid the whole problem by putting everyone into a single realm. But realms exist precisely to provide strong isolation boundaries — different security policies, different branding, different administrative teams, different compliance requirements. Organizations often have entirely legitimate reasons to keep populations separate (a customer realm versus an internal workforce realm, or separate realms per business unit or acquired company) while still needing some carefully scoped interaction between them. Cross-realm trust lets an organization keep those boundaries while still enabling the specific, limited cooperation that’s actually needed.
A company that acquired another organization and is gradually merging systems, a platform offering a shared internal tool to employees from several separately-realmed business units, or a system letting a partner company’s realm-based users access a specific shared application are all situations calling for deliberately configured cross-realm trust.
Key vocabulary, explained simply
Realm
A fully isolated space within Keycloak, with its own users, clients, roles, and settings, sharing nothing with another realm by default.
Realm-to-Realm Identity Brokering
Configuring one realm as a recognized external identity provider for another, allowing users from the first to log into applications in the second.
Token Exchange
A protocol allowing a token issued by one realm, under specific conditions, to be exchanged for a token valid in a different realm or for a different audience.
Source Realm / Target Realm
Common terms for the realm a user’s identity originates from, versus the realm whose protected resources they’re ultimately trying to reach.
Trust Policy
The specific, deliberately narrow set of conditions and mappings that define exactly what’s allowed to cross from one realm into another.
Federation (in this context)
The broader architectural pattern of keeping multiple separate realms but establishing specific, controlled trust relationships between them.
2Architecture & Components
graph TB
U[User in Realm A] -->|logs in via brokered IdP| RB["Realm B
configures Realm A as
an Identity Provider"]
RB --> MP[Identity Provider Mappers
translate Realm A claims]
MP --> APP[Application protected
by Realm B]
U2[Token from Realm A] -->|Token Exchange request| TE[Realm B Token Endpoint]
TE --> POL[Trust Policy Check]
POL -->|approved| NEWTOK[New Token valid in Realm B]
POL -->|denied| REJ[Exchange Rejected]
Component breakdown
Realm-as-Identity-Provider Configuration
The target realm registers the source realm’s own OpenID Connect endpoints as an identity provider, exactly as it would register Google or any external system.
Identity Provider Mappers (cross-realm)
The same mapper mechanism used for external providers, here translating the source realm’s claims into the target realm’s user attributes, roles, or groups.
Token Exchange Endpoint
A specific Keycloak capability allowing a client, under permission, to present a token from one context and receive back a token valid in another — including, in supported configurations, across realms.
Trust Policy / Permission Configuration
Administrative settings controlling exactly which clients are allowed to perform a cross-realm token exchange, and under what conditions.
Where this is configured in the admin console
For the identity-brokering approach, an administrator sets it up under the target realm’s Identity Providers section, exactly like configuring any external OIDC or SAML provider, but pointing at the source realm’s own endpoints. For token exchange, configuration typically involves enabling the relevant capability and setting up permissions on the client and realm level that explicitly authorize which exchanges are permitted.
A common real setup
A company with a separate “partners” realm for external contractors and an “internal” realm for employees needs contractors to access one specific shared project-management tool that lives under the internal realm’s protection. Rather than merging the realms, the internal realm is configured to broker logins from the partners realm specifically for that one application, with mappers ensuring partner users land in a distinct, limited role rather than being treated as regular employees.
Why is this built on the same machinery as external identity brokering?
From Keycloak’s perspective, another one of its own realms is architecturally just another OpenID Connect-speaking identity provider — the protocol doesn’t distinguish between “a Keycloak realm” and “Google” as sources of identity. Reusing the same identity brokering and mapper infrastructure for cross-realm trust means administrators apply exactly the same well-understood, well-tested tools and mental model they’d use for any external federation, rather than learning an entirely separate mechanism.
3Internal Working
How brokered cross-realm login works internally
When a user in the target realm’s login flow chooses to authenticate via the source realm (configured as its identity provider), Keycloak redirects them to the source realm’s own login page — the user authenticates there, using their normal source-realm credentials. The source realm then returns signed claims back to the target realm, exactly as any external identity provider would. The target realm’s mappers process these claims, and a new, entirely separate user record and session are established within the target realm itself, tied back to the source-realm identity through the brokering link.
How token exchange works internally
Token exchange follows a different internal path: rather than triggering a fresh login redirect, a client already holding a valid token from the source realm presents that token directly to the target realm’s token endpoint, requesting an exchange. The target realm evaluates this request against its configured trust policy — checking whether the requesting client is permitted to perform this specific exchange, and whether the presented token meets whatever conditions have been set. If approved, a brand-new token, valid within the target realm, is issued directly, without the user needing to interactively log in again at all.
Why the distinction between these two paths matters
Brokered login is well suited to human, interactive logins — a user clicking “sign in” and being sent to their home realm to authenticate. Token exchange is better suited to service-to-service or backend scenarios, where a system already holding a valid token needs to act across a realm boundary without a human present to click through a login screen. Choosing the right mechanism for the right scenario is one of the more consequential early design decisions in building cross-realm trust.
Token exchange, if not tightly scoped through trust policy, can become a much broader and harder-to-audit trust relationship than a simple brokered login, since it can potentially be invoked programmatically, repeatedly, and without the visible checkpoint of a redirected login screen — this makes strict permission configuration especially important here.
Step-by-step: a brokered cross-realm login
User selects cross-realm login
On the target realm’s login page, the user chooses to authenticate via the source realm.
Redirect to source realm
The target realm redirects the user to the source realm’s own login page.
User authenticates in source realm
The user logs in using their normal, source-realm credentials.
Claims returned to target realm
The source realm sends back signed claims describing the authenticated user.
Mappers translate and create/update record
The target realm’s mappers process the claims, creating or updating a linked, target-realm-specific user record.
Session established in target realm
The user is now logged into the target realm, with a session entirely local to it, tied back to their source-realm identity.
4Data Flow & Lifecycle
sequenceDiagram
participant User
participant RealmA as Source Realm
participant RealmB as Target Realm
participant App as Protected Application
User->>RealmB: Attempts to access App
RealmB->>User: Redirects to Realm A login (brokered)
User->>RealmA: Authenticates normally
RealmA->>RealmB: Returns signed claims
RealmB->>RealmB: Applies mappers, trust policy
RealmB->>RealmB: Creates/updates linked user record
RealmB->>App: Issues token scoped to Realm B
App->>User: Grants access per Realm B's own rules
Notice something important in that diagram: the source realm’s job ends at vouching for who the user is. Every decision about what that user is actually allowed to do — which roles they get, which applications they can reach — is made entirely by the target realm, using its own mappers and its own authorization rules. Cross-realm trust delegates authentication outward, but deliberately keeps authorization decisions local to whichever realm is actually protecting the resource in question.
The lifecycle of a cross-realm trust relationship
Relationship established
An administrator configures the brokering or token-exchange relationship, including mappers and trust policy scoping.
Ongoing use
Users or services from the source realm repeatedly authenticate or exchange tokens against the target realm under this established relationship.
Periodic review
The relationship’s scope and mappers are reviewed as organizational needs evolve, ensuring the trust granted still matches what’s actually required.
Narrowed or revoked
If the underlying business relationship changes or ends, the brokering configuration or exchange permissions are tightened or removed entirely, closing the trust relationship.
Removing a cross-realm trust configuration does not retroactively undo access already granted during its active period — existing sessions and previously issued tokens follow their own normal lifecycle and revocation rules, independent of the brokering or exchange configuration being removed.
5Advantages, Disadvantages & Trade-offs
Advantages
- Preserves strong isolation between distinct user populations while enabling exactly the specific cooperation actually needed
- Reuses well-established identity brokering and token exchange mechanisms, rather than requiring entirely custom integration work
- Keeps authorization decisions local to whichever realm actually protects a given resource, even when authentication is delegated
- Supports gradual organizational change — such as a multi-year post-acquisition integration — without forcing an immediate, risky full merge of user bases
Disadvantages & Trade-offs
- Adds real configuration and ongoing maintenance complexity compared to a single, unified realm
- Requires careful, deliberate scoping — an overly broad trust policy can quietly grant far more access than intended
- Creates two administrative teams (one per realm) who both need to understand and coordinate around the trust relationship
- Can complicate troubleshooting, since a login or access problem might originate in either the source or target realm’s configuration
Building a supervised, single doorway between two otherwise separate, secured buildings gives you exactly the controlled cooperation you need without knocking down the walls between them entirely. But that doorway itself now needs its own lock, its own guard, and its own maintenance — a small, deliberate opening still requires real, ongoing attention to keep it working safely.
6Security
The principle of least trust
Just as authorization design favors least privilege, cross-realm trust design should favor least trust — granting only the specific, minimum access genuinely required, rather than a broad, convenient blanket relationship between two realms. A brokering configuration that maps every source-realm user into a powerful target-realm role, simply because it was the easiest configuration to set up, defeats much of the purpose of having kept the realms separate in the first place.
Context
It’s tempting, when setting up realm-to-realm brokering, to map incoming users into an existing, convenient role rather than designing a distinct, narrowly scoped role specifically for brokered users.
Decision
Create distinct roles and groups specifically for users arriving through cross-realm trust, scoped to exactly what that relationship is meant to enable, rather than reusing existing internal roles designed for a different population.
Consequence
A misconfiguration or an unexpectedly broad claim from the source realm cannot accidentally grant brokered users access equivalent to a realm’s own native, more privileged population.
Auditing who trusts whom
As organizations grow, it’s easy for cross-realm trust relationships to accumulate — a partnership here, an acquisition integration there — without anyone maintaining a clear, current picture of exactly which realms trust which other realms, and for what purpose. Periodically auditing and documenting every active cross-realm trust relationship helps prevent a forgotten, overly broad configuration from becoming an unnoticed security gap.
Leaving a cross-realm trust relationship active long after the business reason for it has ended — a completed short-term project, a partnership that concluded — because removing it wasn’t part of any documented offboarding checklist.
Token exchange permission scoping
Because token exchange can operate without a visible, interactive login step, its permission configuration deserves particular scrutiny — restricting exactly which clients may perform which exchanges, and under what conditions, prevents this powerful, largely invisible mechanism from becoming a much broader trust relationship than originally intended.
7Monitoring, Logging & Metrics
Cross-realm login/exchange volume
Tracking how often the brokered login or token exchange path is actually used, helping confirm whether an established trust relationship is still genuinely needed or has quietly become dormant.
Role/group assignment distribution for brokered users
Periodically reviewing what roles brokered users actually end up with, to catch any drift toward broader access than originally intended.
Token exchange denial rate
Monitoring how often exchange requests are rejected by trust policy, since a rising rate can indicate either a misconfigured client or active probing of the trust boundary.
Active trust relationship inventory
Maintaining and periodically reviewing a simple, up-to-date list of every configured cross-realm brokering and exchange relationship, alongside its documented business justification.
A practical monitoring habit
Organizations with several realms often schedule a recurring, quarterly review specifically covering every active cross-realm trust configuration, checking usage volume against the original justification for each one, and treating a relationship with unexpectedly low or zero recent usage as a strong candidate for tightening or removal entirely.
8Design Patterns & Anti-patterns
Proven patterns
Purpose-built brokered roles
Create distinct, narrowly scoped roles specifically for cross-realm brokered users, rather than folding them into existing native roles designed for a different population.
Documented trust inventory
Maintain a clear, centrally accessible record of every active cross-realm trust relationship, its purpose, its scope, and who owns it on each side.
Time-boxed trust for temporary needs
For project-based or short-term cooperation, treat cross-realm trust as something with a planned expiration or review date, rather than an indefinitely standing configuration.
Gradual migration path
Use cross-realm trust as a deliberate, temporary bridging tool during a longer-term migration (like a post-acquisition consolidation) toward an eventual, simpler single-realm or clearly separated end state.
Anti-patterns to avoid
Anti-pattern
- Mapping brokered users directly into a realm’s existing, broadly privileged internal roles for convenience
- Leaving cross-realm trust relationships active indefinitely with no scheduled review
- Granting overly broad token exchange permissions to avoid the effort of precisely scoping which clients and conditions are actually needed
- Treating cross-realm trust as a permanent architectural solution when it was originally intended as a temporary bridge during a migration
Instead, do this
- Design distinct, narrowly scoped roles specifically for each cross-realm trust relationship
- Schedule and follow through on periodic reviews of every active trust relationship
- Scope token exchange permissions tightly to specific clients and specific, justified conditions
- Treat temporary cross-realm bridges as genuinely temporary, with a planned path toward a cleaner end state
9Best Practices & Common Mistakes
Best practices
Start from the narrowest possible scope
Design the initial trust relationship to grant exactly the minimum access needed, expanding deliberately later only if a genuine, justified need arises.
Coordinate explicitly across both realm administration teams
Ensure the teams responsible for the source and target realms both understand and agree on exactly what the trust relationship allows, avoiding one side assuming a broader or narrower scope than actually configured.
Test the boundary, not just the happy path
Deliberately verify that users or tokens outside the intended scope are correctly denied, not just that intended users can successfully authenticate.
Document the business reason alongside the technical configuration
Record not just how a trust relationship is configured, but why it exists, making future review and eventual decommissioning far easier.
Common mistakes
Assuming that because two realms belong to the same organization, a broad, convenient trust relationship between them carries less risk than trusting a genuinely external identity provider — internal realm boundaries exist for real reasons and deserve the same careful scoping.
Setting up cross-realm trust as a quick, one-off fix for an immediate need without documenting it clearly, leaving future administrators unsure why the relationship exists or whether it’s still needed.
Confusing cross-realm trust with simply merging two realms’ populations, leading to a configuration that grants far broader access than the actual underlying business relationship justifies.
10Real-world & Industry Examples
Mergers and acquisitions
Companies integrating an acquired organization’s Keycloak deployment often use cross-realm trust as a gradual bridging mechanism, allowing shared tool access well before, or sometimes instead of, a full identity system merger.
Multi-business-unit enterprises
Large organizations with separately realmed business units use cross-realm trust to grant limited access to shared internal platforms without collapsing each unit’s own distinct identity management into one.
Managed service providers with customer isolation
Providers that keep each customer in their own isolated realm sometimes use limited, carefully scoped cross-realm mechanisms for their own internal support staff to access customer environments under controlled conditions.
Partner and contractor ecosystems
Organizations granting external contractors or partners access to specific shared tools use cross-realm brokering to keep those external identities cleanly separated from internal employee accounts, while still enabling the specific access needed.
A representative scenario
Following an acquisition, a company needed employees from the newly acquired organization’s separate Keycloak realm to access a shared internal collaboration tool immediately, well before a planned, multi-year full systems integration could be completed. Rather than rushing a risky, premature merger of the two realms, the internal collaboration tool’s realm was configured to broker logins from the acquired company’s realm, with a distinct, limited role ensuring these users received exactly the collaboration-tool access intended, and nothing more, while both organizations’ identity systems otherwise remained fully separate during the longer integration timeline.
11FAQ
12Summary and Key Takeaways
Key Takeaways
- Cross-Realm Trust is the deliberate practice of bridging two otherwise fully isolated Keycloak realms, without merging them into one.
- It’s typically built using either realm-to-realm identity brokering (one realm acting as an identity provider for another) or token exchange (swapping a token from one realm for one valid in another).
- Realms are isolated by design — cross-realm trust exists specifically to enable controlled exceptions to that isolation, not to eliminate it.
- Authorization decisions remain firmly with the target realm, even when authentication is delegated to a source realm through brokering.
- Good design follows the principle of least trust — granting only the narrow, specific access genuinely justified, through purpose-built roles rather than reused, broadly privileged ones.
- Token exchange deserves particularly tight permission scoping, since it can operate without a visible, interactive login checkpoint.
- Trust relationships should be documented, reviewed periodically, and removed once their underlying business justification ends, rather than left standing indefinitely.
- Real-world use spans mergers and acquisitions, multi-business-unit enterprises, and partner ecosystems — anywhere separate identity populations need carefully scoped, temporary or ongoing cooperation.