English for Keycloak Developers

Keycloak is an open-source identity and access management server, and its vocabulary — “realm,” “client,” “identity broker,” “token exchange” — describes a layered model that’s easy to get tangled up in when a team is used to simpler, single-app auth. Confusing a “realm” with a “client,” or misunderstanding what an “identity broker” actually does, leads to misconfigured integrations that fail in confusing ways. This guide covers the English used when discussing Keycloak with a team.

Key Vocabulary

Realm — an isolated space in Keycloak managing its own set of users, roles, and clients, completely separate from other realms even on the same server instance. “Don’t put the internal admin tool and the customer-facing app in the same realm — they need different password policies and user pools, so they belong in separate realms.”

Client — a registered application or service within a realm that can request authentication on behalf of a user, each with its own protocol settings (confidential, public, bearer-only). “The mobile app should be registered as a public client since it can’t safely hold a secret, while the backend API should be a confidential client that can.”

Identity broker — Keycloak’s role when it delegates authentication to an external identity provider (Google, a corporate SSO, another Keycloak realm) instead of validating credentials itself, presenting a unified login experience regardless of the backing provider. “Users log in through our realm, but Keycloak is acting purely as an identity broker here — the actual credential check happens against the corporate SSO.”

Token exchange — the flow where one already-issued token is exchanged for a different token (often with narrower scope or for a different audience), instead of the user re-authenticating from scratch. “Rather than asking the user to log in again for the downstream service, use token exchange to swap this token for one scoped specifically to that service.”

Client scope — a reusable, named bundle of protocol mappers and role assignments that can be attached to multiple clients, letting a team define token contents once instead of duplicating configuration per client. “Define the tenant-ID claim once as a client scope and attach it to every client that needs it, instead of configuring the same mapper five separate times.”

Common Phrases

• “Should these two applications share a realm, or do they need isolated user pools?”
• “Is this client confidential or public, and does that match how it can actually store secrets?”
• “Is Keycloak acting as the identity broker here, or is it validating credentials itself?”
• “Could token exchange solve this instead of forcing a second login?”
• “Should this claim be defined as a reusable client scope rather than configured per client?”

Example Sentences

Reviewing a pull request: “This registers the single-page app as a confidential client with a secret embedded in frontend code — that’s a public client’s job, since a secret in browser-shipped code isn’t actually confidential.”

Explaining a design decision: “We put every internal team’s app in one realm but each partner integration in its own realm, since partners need separate user pools and can’t see each other’s users.”

Describing an incident: “Users were being asked to log in twice across two internal services because we hadn’t set up token exchange — introducing it removed the redundant second prompt entirely.”

Professional Tips

• Say “realm” and “client” precisely — they’re the two most fundamental Keycloak concepts, and conflating them is the single most common cause of confusing misconfigurations.
• When registering a new application, ask “public or confidential client?” early — the answer depends on whether the app can securely store a secret, not on how sensitive the app is.
• Use “identity broker” correctly when Keycloak delegates to an external provider — it clarifies that Keycloak isn’t the source of truth for credentials in that flow.
• Propose “client scope” when the same claim or role mapping needs to appear on multiple clients — it avoids configuration drift from copy-pasted per-client settings.

Practice Exercise

1. Explain in two sentences the difference between a realm and a client.
2. Write a one-sentence code review comment flagging a client registered with the wrong confidentiality setting.
3. Describe, in your own words, what it means for Keycloak to act as an identity broker.