What Is a User in Keycloak?
The single record at the center of every login, every role assignment, and every access decision in a Keycloak-secured system — understood from the ground up.
Every time someone logs into a Keycloak-protected application — a company intranet, a customer portal, an internal admin tool — there’s one record behind the scenes that makes it all possible: the User. It sounds almost too simple to deserve a deep dive, but the “User” object in Keycloak is actually a rich, carefully designed entity that carries credentials, roles, group memberships, custom attributes, and links to external identity sources. Understanding it properly is the foundation for understanding everything else Keycloak does. This guide walks through exactly what a Keycloak User is, how it’s structured internally, how it flows through a login, and how real teams use it in production.
ACore Concepts: What Exactly Is a Keycloak User?
Keycloak is an open-source Identity and Access Management (IAM) server. Its job is to sit in front of your applications and handle login, single sign-on, and permission decisions centrally, so individual apps don’t have to build their own authentication systems. And within Keycloak, a User is simply the digital record representing one real person (or sometimes a service) who is allowed to authenticate against a specific Keycloak Realm.
A User record isn’t just a username and password. In Keycloak it’s a structured object made up of several parts working together:
Username, Email, Name
The basic identifying details — username, email address, first name, last name — used to recognize and address the user.
Password, OTP, WebAuthn
One or more ways the user proves their identity — a password, a one-time code, or a hardware/biometric security key.
What the user can do
Realm-level and client-level roles assigned directly to the user, or inherited through groups.
Custom fields
Free-form extra data — a department name, an employee ID, a preferred language — that applications can read after login.
Think of a Keycloak User the way you’d think of an employee file in an HR system. It’s not just a name on a badge — it includes how the person clocks in (credentials), which departments and access badges they hold (roles and groups), and extra notes about them (attributes). The badge itself (the login session) is just the visible tip of a much richer underlying record.
Crucially, every User in Keycloak belongs to exactly one Realm — an isolated security domain. A Realm is like a separate, self-contained tenant: users in the “Employees” realm are completely invisible to and separate from users in a “Customers” realm, even if both realms run on the very same Keycloak server. This means the same email address can exist as two entirely different, unrelated Users if it’s registered in two different realms.
A Keycloak User is not the same as a Keycloak Client. A User represents a person (or service account) that logs in. A Client represents an application — like a website or API — that Keycloak protects and issues tokens to. Users log into Clients; Clients don’t log in themselves (except for a special case called service-account clients, covered later).
Where does a User record actually come from? There are three broad origins, and Keycloak treats all three uniformly once the user exists:
- Local users — created and stored directly inside Keycloak’s own database, either by an admin or via self-registration.
- Federated users — pulled in from an external directory like LDAP or Active Directory through Keycloak’s User Federation feature, so the source of truth stays outside Keycloak.
- Brokered users — created automatically the first time someone logs in through an external Identity Provider Keycloak trusts (like Google or a partner company’s own Keycloak), a pattern called Identity Brokering.
BArchitecture & Core Components
flowchart TB
Realm["Realm (Security Domain)"] --> User["User"]
Realm --> Client["Client (Application)"]
Realm --> RoleDef["Realm Roles"]
User -->|"has"| Credential["Credentials (password / OTP / WebAuthn)"]
User -->|"assigned"| RoleMap["Role Mappings"]
User -->|"member of"| Group["Groups"]
Group -->|"grants"| RoleMap
User -->|"carries"| Attribute["Custom Attributes"]
LDAP["LDAP / Active Directory"] -.->|"User Federation"| User
ExternalIdP["External IdP (Google, Partner Keycloak)"] -.->|"Identity Brokering"| User
Let’s unpack each connected piece shown in the diagram, one at a time.
Realm
The outermost container. Every User, Client, Role, and Group lives inside exactly one Realm. Realms are the mechanism Keycloak uses to fully isolate one organization or product’s users from another’s on the same server.
Credentials
A User can hold multiple credential types simultaneously — a password, a one-time password (OTP) generator, a WebAuthn hardware key, or a recovery code. Keycloak stores these separately from the rest of the profile, and passwords are always stored as salted hashes, never in plain text.
Role Mappings
Roles describe permissions — for example, admin, editor, or viewer. Roles can be defined at the Realm level (shared across every app in that realm) or at the Client level (specific to one application). A User can have roles assigned directly, or inherit them automatically through group membership.
Groups
A Group is a named collection of users that can have roles and attributes assigned to it in bulk. Instead of assigning the same five roles to fifty individual users one by one, an admin assigns those roles to a Group once, and every current and future member of that group inherits them automatically.
Custom Attributes
Beyond the built-in fields, every User can carry arbitrary custom attributes — a cost-center code, a job title, a preferred locale — which applications can request and read after login via the identity token.
User Federation & Identity Brokering
These are the two ways a User record can originate outside Keycloak’s own database, shown as dashed lines in the diagram above. Federation pulls users from an external directory in near real time; Brokering creates a local shadow record the first time someone authenticates through a trusted external IdP.
People sometimes assume every Keycloak User is stored in Keycloak’s own database. In a federated setup, Keycloak may only cache minimal local data and delegate the actual password check back to the external LDAP/AD server on every login — the “source of truth” for that user’s credentials never actually moves into Keycloak at all.
CHow the User Object Works Internally
Internally, Keycloak represents a User as a structured record with a unique internal ID (a UUID), independent of the username itself — this matters because it means a username can technically be changed later without breaking every reference to that user elsewhere in the system, since everything else links to the stable internal ID, not the display name.
Storage: Local vs. Federated Lookup
When a login request comes in, Keycloak’s User Storage SPI (Service Provider Interface) decides where to look. For a purely local user, it queries its own internal database directly. For a federated user, it instead calls out to the configured LDAP or Active Directory server, using that external system to validate the password, while still keeping a lightweight local cache of non-sensitive profile data for performance.
The Admin REST API
Every operation you can perform on a User in the Keycloak Admin Console — creating one, resetting a password, assigning a role — is backed by a well-documented Admin REST API. This is what lets organizations automate user provisioning from scripts, HR systems, or infrastructure-as-code pipelines instead of manually clicking through an admin UI.
Required Actions
A User record can carry one or more Required Actions — flags that force something to happen the next time that user logs in, such as “update password,” “verify email,” or “configure OTP.” This is how Keycloak enforces onboarding steps or security remediation without needing custom application code.
Think of Required Actions like a sticky note attached to an employee’s badge file that says “must complete security training before entering the building again.” The very next time that badge is scanned, the system pauses and insists on that step before letting the person through — regardless of which door (application) they tried to use.
User Consent and Client Scopes
When a User authenticates for a particular Client, Keycloak can be configured to ask for explicit consent — “This application wants to access your email and profile, allow?” — before issuing a token that includes those details. This is governed by Client Scopes, which define exactly which pieces of a User’s data get bundled into the token for a given application.
DData Flow & the User Lifecycle
flowchart LR
A["1. User account created (local, federated, or brokered)"] --> B["2. Credentials + roles + groups attached"]
B --> C["3. User attempts login at a Client app"]
C --> D["4. Keycloak locates the User record"]
D --> E["5. Credential verified (locally or via LDAP)"]
E --> F["6. Required Actions checked / resolved"]
F --> G["7. Roles + group memberships + attributes gathered"]
G --> H["8. Token issued with mapped claims"]
H --> I["9. Client app grants access based on token"]
User Creation
A record is created — by an admin, through self-registration, via the Admin REST API, through LDAP sync, or automatically on first login through a brokered external IdP.
Enrichment
Credentials are set, roles are mapped (directly or through group membership), and any custom attributes are populated.
Login Attempt
The user tries to access a Client application, which redirects them to Keycloak’s login page for that Realm.
Lookup & Verification
Keycloak locates the matching User record (locally or via federation) and verifies the submitted credential against it.
Claims Assembly
Keycloak gathers the User’s roles, group memberships, and requested attributes, shaping them according to the target Client’s configured scopes.
Token Issuance
A signed token (typically an OpenID Connect ID Token and Access Token) is issued, carrying the User’s identity and permission claims back to the Client application.
Once issued, the Client application never needs to query Keycloak’s database directly to know who the user is or what they can do — everything it needs is already embedded, verifiably, inside the signed token it received.
EAdvantages, Disadvantages & Trade-offs
Advantages
- One consistent User model across every connected application — no per-app password tables to secure separately.
- Roles and groups let permissions be managed in bulk instead of user-by-user across dozens of apps.
- Federation lets existing LDAP/AD directories stay the source of truth, avoiding duplicated, drifting user data.
- The Admin REST API makes user provisioning fully automatable from HR systems or scripts.
- Required Actions enforce security steps (password reset, MFA setup) centrally, without custom code in every app.
Disadvantages / Trade-offs
- A poorly tuned federated LDAP lookup can add noticeable login latency, since Keycloak calls out to an external directory on each authentication.
- Realm and role design mistakes made early are painful to restructure later, once hundreds of users and apps depend on them.
- Because so much trust concentrates in one User record, a compromised admin account can affect every connected application at once.
- Custom attribute sprawl, if left unmanaged, can make User records cluttered and inconsistent across large organizations.
A single, well-organized employee file cabinet is far easier to manage than fifty separate departmental files that all drift out of sync — but it also means a fire in that one cabinet is a much bigger problem than a fire in just one department’s drawer. Centralizing User records buys consistency at the cost of concentrated importance.
FSecurity Considerations
Credential Storage
Keycloak never stores passwords in plain text. Passwords are hashed with a strong, salted algorithm before storage, so that even a full database compromise doesn’t directly expose usable passwords.
Brute-Force Protection
Keycloak includes built-in brute-force detection at the User level — repeated failed login attempts against a specific account trigger temporary lockouts, slowing down password-guessing attacks without requiring custom application logic.
Role and Attribute Exposure
Not every Client should see every attribute a User carries. Client Scopes let administrators precisely control which roles and attributes get included in the token issued to a given application, following the principle of least privilege — a payroll app might see a cost-center code that a chat app never needs to.
Keycloak’s own admin console is itself protected by Keycloak Users with administrative roles. If an attacker compromises an overly broad admin account, they can create new users, reset passwords, or grant themselves roles across the entire realm — this is why realm-admin accounts deserve the strongest available protection: MFA, tight audit logging, and minimal standing privilege.
Federated Credential Handling
In a federated setup, Keycloak typically never stores the user’s real password at all — every login is validated live against the external LDAP/AD server, meaning that directory’s own security posture directly determines the security of every federated Keycloak User.
The Idea
Design fine-grained roles and assign them through Groups rather than granting broad, catch-all roles directly to individual Users.
Why It Matters
When permissions are modeled precisely and assigned through groups, revoking or auditing access becomes a matter of adjusting group membership once, instead of hunting down scattered direct role assignments across thousands of User records.
GDesign Patterns & Anti-Patterns
Good Pattern: Groups Over Direct Role Assignment
Modeling permissions primarily through Groups, with roles attached to the group rather than the individual, keeps large user bases manageable and makes bulk permission changes trivial and auditable.
Good Pattern: One Realm per Trust Boundary
Separating genuinely distinct populations — employees versus customers, or one product line versus another — into different Realms keeps User data cleanly isolated and prevents accidental cross-application access.
Good Pattern: Federation for Existing Directories
When an organization already maintains an authoritative LDAP or Active Directory, federating Keycloak Users to it (rather than duplicating everyone into Keycloak’s own database) keeps a single source of truth and avoids painful data drift.
What It Looks Like
Putting employees, external customers, and partner-company users all into a single shared Realm to save initial setup effort.
Why It’s a Problem
This blurs the trust boundary between very different populations, makes role and client-scope design far more error-prone, and increases the blast radius if any one group of Users or Clients is compromised.
What It Looks Like
Different teams adding ad-hoc custom attributes to the User model over time with no shared naming convention or ownership.
Why It’s a Problem
Over months and years, this produces inconsistent, undocumented User records that are hard to audit, hard to migrate, and prone to leaking unnecessary data to Client applications that only requested a broad scope.
HBest Practices & Common Mistakes
Automate User Provisioning
Use the Admin REST API to create and update Users from an authoritative HR or identity system, rather than manual admin-console entry.
Enforce Required Actions for Security Hygiene
Use built-in Required Actions to force password resets or MFA enrollment for new or flagged accounts, rather than relying on informal reminders.
Review Client Scopes Regularly
Periodically audit which attributes and roles each Client actually receives, trimming any that are no longer needed.
Document Realm and Group Structure
Keep a clear, current map of which Realms and Groups exist and why, so new team members don’t recreate overlapping structures.
Common Mistakes to Avoid
- Assigning roles directly instead of through groups: This makes later audits and bulk changes far harder than they need to be.
- Forgetting federated login latency in capacity planning: Every federated login means a live call to an external directory — under-provisioned LDAP servers can become a bottleneck at peak login times.
- Leaving default admin credentials unchanged: A fresh Keycloak install’s default administrative account is a common, entirely avoidable point of compromise if left as-is.
- Not planning Realm boundaries up front: Splitting a single overloaded Realm into properly separated ones later is a significant, disruptive migration.
IReal-World & Industry Examples
Large Enterprises: LDAP-Federated Employee Users
Many large organizations already run Active Directory internally. Rather than migrating every employee record into Keycloak, they configure User Federation so Keycloak transparently authenticates against the existing directory, letting employees keep using their familiar corporate credentials while every connected application gains SSO.
SaaS Platforms: Customer-Facing Realms
Software-as-a-service companies commonly run a dedicated Realm just for their external customers, with self-registration enabled and roles like free-tier or premium assigned automatically based on subscription status, kept entirely separate from any internal-employee Realm.
Partner Integrations: Identity Brokering
When two companies need to collaborate on a shared internal tool, Identity Brokering lets each partner’s employees log in using their own existing Keycloak (or other IdP), with Keycloak automatically creating a brokered local User record on first login — no duplicate account creation required.
Microservices: Service Account Users
Beyond human users, Keycloak also supports service account Users tied to a Client — allowing one backend microservice to authenticate to another using client credentials rather than a human ever being involved, while still going through the same underlying role and permission model.
JFrequently Asked Questions
employee alongside a narrower Client Role like billing-admin that only matters to one app.KSummary & Key Takeaways
Key Takeaways
- A Keycloak User is the structured record — identity fields, credentials, roles, groups, and attributes — representing one person or service that can authenticate within a given Realm.
- Every User belongs to exactly one Realm, which isolates it completely from Users in any other Realm, even on the same Keycloak server.
- Users can originate as local records, be pulled in via User Federation from LDAP/Active Directory, or be created via Identity Brokering from a trusted external IdP.
- Permissions flow through Roles (Realm-level or Client-level), most cleanly managed through Groups rather than direct per-user assignment.
- On login, Keycloak verifies the User’s credential, resolves any pending Required Actions, gathers roles/attributes according to Client Scopes, and issues a signed token carrying that identity.
- Well-run Keycloak deployments favor group-based role design, federation for existing directories, tightly scoped Client attribute exposure, and automated provisioning — avoiding giant catch-all Realms and unmanaged attribute sprawl.