What Are User Attributes in Keycloak? — The extra fields on every person's file folder
A ground-up, beginner-friendly explanation of how Keycloak lets you store extra information about each user, and how that information travels safely into applications that need it.
Imagine an HR department’s filing cabinet. Every employee’s folder has some standard fields already printed on the cover — name, employee ID, start date. But different companies also need to track different extra details: one company might add a “preferred language” field, another might add “emergency contact,” another might add “badge access level.” Nobody redesigns the entire filing cabinet for these extras — they simply add a labeled sticky note to the folder. A user attribute in Keycloak is exactly that sticky note: a flexible, named piece of extra information attached to a user’s record, beyond the handful of fields Keycloak understands out of the box.
1What Are User Attributes?
Let’s define the term plainly before exploring how it’s used.
A user attribute is a named piece of information stored on a user’s account in Keycloak, beyond the standard built-in fields like username or email. Attributes let organizations attach whatever extra data they need — a department name, an employee ID from another system, a subscription tier, a preferred language — directly to the user record, without requiring changes to Keycloak’s core software.
Think of a library membership card system. Every card already has a name and a library card number printed on it — those are the built-in fields. But the library’s computer system might also let staff add extra notes to your account, like “prefers large-print books” or “has a standing hold request.” These extra notes aren’t part of the card’s fixed design, but they’re just as real and just as useful — that’s exactly what a user attribute is for a Keycloak user account.
Built-in Attribute
A standard field Keycloak understands natively, like username, email, or first name.
Custom Attribute
An additional named field an administrator defines, holding organization-specific information.
Multi-Valued Attribute
An attribute that can hold more than one value at once for a single user, like several phone numbers.
User Profile
Keycloak’s configuration area defining exactly which attributes exist, their validation rules, and who can view or edit them.
User attributes are one of the main reasons Keycloak can adapt to almost any organization’s needs without requiring custom software development — instead of hard-coding a fixed user record, Keycloak treats the user profile as something administrators can extend, shaping it to match exactly the information their applications actually need.
2Why User Attributes Exist — The Problem They Solve
To appreciate user attributes, imagine trying to manage identity without any flexibility at all.
Every organization’s applications need slightly different information about their users. A healthcare scheduling app might need a “preferred clinic location.” A B2B software platform might need a “company account tier.” A university’s system might need a “student ID number.” If Keycloak only supported a rigid, fixed set of fields, none of these organizations could store the information they actually need without building an entirely separate, custom database just to hold the extras.
A fixed, unextendable user record forces organizations to maintain a second, separate system just to store the extra information their applications actually depend on — introducing extra complexity, extra points of failure, and the constant risk of the two systems falling out of sync with each other.
User attributes solve this by making the user record itself extendable. Organizations define exactly the extra fields they need, once, and Keycloak stores, manages, and exposes that information alongside everything else it already knows about each user — all from a single, unified source of truth.
3Core Concepts: Built-in vs Custom, Single vs Multi-Valued
A handful of simple distinctions make up the entire attribute system.
Built-in Attributes
Fields Keycloak already understands and manages specially, such as username, email, first name, and last name. These have dedicated handling throughout the system, including in the login screens themselves.
Custom Attributes
Any additional field an administrator defines, tailored to the organization’s own needs. Custom attributes behave much like built-in ones once defined, but they’re entirely optional and organization-specific.
Single-Valued vs Multi-Valued
Most attributes hold a single value, like one department name. Some attributes are configured to hold multiple values at once, like a list of several skills or certifications a user has earned.
Built-in attributes are like the pre-printed fields on a standardized government form — name, date of birth, address. Custom attributes are like a company-specific form stapled on top, adding fields like “badge number” or “parking spot,” which only matter to that one organization. A multi-valued attribute is like a field on that custom form allowing several entries, such as listing multiple certifications instead of just one.
department
A single-valued custom attribute recording which team or division a user belongs to.
employee_id
A custom attribute linking a Keycloak account back to a record in an external HR system.
certifications
A multi-valued custom attribute listing several professional certifications a user has earned.
preferred_language
A single-valued custom attribute used to personalize an application’s interface language.
4Architecture — Where User Attributes Fit Inside Keycloak
A look at the components involved in defining, storing, and exposing attributes.
User Profile Configuration
The realm-level definition of every attribute that exists, including validation rules and permissions.
Attribute Storage
Where the actual values for each user’s attributes are kept, tied directly to their account record.
Validation Engine
Checks that a submitted attribute value follows any configured rules, like format or length, before it’s saved.
Protocol Mapper
The same mechanism used by client scopes to expose an attribute’s value as a claim inside a token, when configured to do so.
Because attribute definitions live in the user profile configuration at the realm level, every part of Keycloak that touches user data — the admin console, self-registration forms, the account management page — automatically understands and respects the same set of defined attributes, without needing separate configuration in each place.
5How User Attributes Work Internally, Step by Step
Let’s trace exactly what happens when a user attribute is set and later used.
Administrator Defines the Attribute
A new attribute, like “department,” is added to the realm’s user profile configuration, along with any validation rules.
A Value Is Submitted for a User
This might happen through the admin console, a self-registration form, or the user’s own account settings page.
Validation Runs
Keycloak checks the submitted value against any configured rules — required, format, length — before accepting it.
Value Is Stored
Once validated, the attribute value is saved as part of that specific user’s account record.
User Logs In Later
During authentication, if a protocol mapper has been configured to expose this attribute, its value is retrieved.
Attribute Becomes a Token Claim
The value is placed into the issued token as a named claim, ready for the receiving application to read.
flowchart TD
A[Admin Defines Attribute in User Profile] --> B[Value Submitted for a User]
B --> C{Passes Validation Rules?}
C -->|No| D[Rejected, Error Shown]
C -->|Yes| E[Value Stored on User Record]
E --> F[Protocol Mapper Configured to Expose It]
F --> G[Attribute Appears as Token Claim on Login]
6Data Flow — From Storage to an Application’s Use
A closer look at how a stored attribute actually reaches and helps a real application.
sequenceDiagram
participant Admin as Administrator
participant KC as Keycloak
participant U as User
participant App as Application
Admin->>KC: Define "department" attribute
U->>KC: Log in
KC->>KC: Retrieve stored attribute value
KC-->>App: Issue token including "department" claim
App->>App: Read claim, show department-specific dashboard
Not every attribute needs to be exposed inside a token — many are used purely for administrative purposes, like internal reference data an administrator needs to see but no application ever reads. Whether an attribute becomes a token claim is a deliberate configuration choice, not an automatic side effect of simply defining it.
7Controlling Who Can View and Edit Each Attribute
Attributes aren’t just about what data exists — they’re also about who’s allowed to see or change it.
| Permission | Meaning |
|---|---|
| Admin View | Whether administrators can see this attribute’s value in the admin console |
| Admin Edit | Whether administrators are allowed to change this attribute’s value |
| User View | Whether the user themselves can see this attribute on their own account page |
| User Edit | Whether the user themselves can change this attribute’s value directly |
Think of a personnel file. An employee can usually view and update their own home address, but they typically can’t see or change their own performance review notes — only HR can. User attributes work the same way, letting each field independently decide whether the account owner, an administrator, both, or neither can view or edit it.
An attribute like “internal-risk-score” might reasonably be configured as visible and editable only by administrators, never by the user themselves — while an attribute like “preferred-language” makes sense as something the user can freely view and update on their own.
8Advantages, Disadvantages, and Trade-offs
Flexibility here is powerful, but it still comes with real design considerations.
Advantages
- Extends the user record without needing a separate custom database
- Configurable validation keeps stored data clean and consistent
- Fine-grained view/edit permissions per attribute, per audience
- Automatically respected across the admin console, registration, and account pages
- Can be exposed selectively into tokens through protocol mappers, when needed
Disadvantages / Trade-offs
- Too many loosely defined attributes can become disorganized and hard to maintain
- Sensitive attributes require careful visibility configuration to avoid overexposure
- Attribute values are a stored snapshot and must be actively kept in sync with any external source
- Overexposing attributes into tokens can unnecessarily bloat token size
Just because an attribute can be exposed into every token doesn’t mean it should be — each attribute placed inside a token adds to its size and expands what any application receiving that token can see, whether or not it actually needs that information.
9Security Considerations for User Attributes
Since attributes can hold genuinely sensitive information, their configuration deserves careful thought.
Never Store Highly Sensitive Secrets as Attributes
User attributes are convenient for descriptive information, but they are not designed as a secure vault for things like unencrypted financial details or highly sensitive personal records — a dedicated, properly secured system is a better home for that kind of data.
A sticky note on a filing cabinet folder is handy for jotting down “prefers email contact,” but nobody would tape their bank PIN to the outside of the folder. Some information simply belongs in a more carefully guarded place, not a general-purpose extra field.
Restrict Edit Permissions Appropriately
An attribute like “role tier” or “internal notes” should almost certainly not be user-editable, since allowing a user to change it themselves could let them grant themselves unintended benefits or privileges.
Validate Input Carefully
Attributes accepting free-form text should have sensible validation rules in place, both to keep data clean and to reduce the risk of unexpected or malformed values causing problems downstream.
Problem
Making a sensitive, business-critical attribute — like “subscription tier” or “account credit limit” — editable directly by the user themselves.
Why It’s Harmful
A user could simply change the value of this attribute on their own account page to grant themselves a higher tier or artificial privilege the application would then trust as genuine.
Correct Approach
Restrict edit permissions on sensitive, business-critical attributes to administrators only, letting users view them if appropriate, but never change them directly.
10Monitoring, Logging, and Metrics
Keeping visibility into how attributes are used and changed helps catch problems early.
Attribute Update Events
Tracking when and by whom a sensitive attribute was changed provides an important accountability trail.
Validation Failure Rate
A high rate of rejected attribute submissions may indicate a confusing form or overly strict validation rules.
Token Size Impact
Monitoring how many attributes are exposed into tokens helps catch unnecessary bloat before it becomes a real performance issue.
Unused Attributes
Periodically reviewing which defined attributes are actually populated or referenced helps identify stale definitions worth cleaning up.
Attribute changes made through the admin console are recorded in Keycloak’s administrative event log, giving a clear, reviewable trail of who changed what, on which user’s account, and when.
11Design Patterns and Anti-Patterns
A few tested habits for designing attributes well, and a few traps to avoid.
Pattern: Name Attributes Clearly and Consistently
Use a consistent naming convention across attributes, making their purpose obvious to anyone reviewing the user profile configuration later.
Pattern: Only Expose What Applications Actually Need
Add a protocol mapper for an attribute only when a specific application genuinely needs to read it inside a token, rather than exposing everything by default.
Pattern: Use Multi-Valued Attributes Sparingly
Reserve multi-valued attributes for genuinely list-like data, keeping simpler single-valued attributes for everything else to avoid unnecessary complexity.
Problem
Creating many overlapping, inconsistently named custom attributes over time, without any shared naming convention or documentation.
Why It’s Harmful
This leads to a confusing, hard-to-audit user profile where nobody is quite sure which attribute is the “real” source of a given piece of information, increasing the risk of applications reading inconsistent or outdated data.
Correct Approach
Establish a clear naming convention early, document each attribute’s purpose, and periodically review the full attribute list to retire anything no longer needed.
12Best Practices and Common Mistakes
A practical checklist for anyone defining or managing user attributes.
Set Appropriate Validation Rules
Define reasonable format and length constraints for each attribute to keep stored data clean and predictable.
Review View/Edit Permissions Deliberately
Decide, for every attribute, exactly who should be able to see or change it — never leave this as an afterthought.
Keep Tokens Lean
Expose only the attributes each specific application genuinely requires, rather than surfacing everything into every token by default.
Document the Source of Truth
If an attribute mirrors data from another system, document that relationship clearly to avoid confusion about which system is authoritative.
Frequent mistakes include leaving sensitive attributes user-editable by default, skipping validation on free-form fields, exposing far more attributes into tokens than any application actually reads, and letting the attribute list grow without documentation or periodic cleanup.
13Real-World Examples
Seeing user attributes applied to concrete situations makes the concept tangible.
Multi-Tenant SaaS Platform
A “tenant_id” custom attribute links each user account to the specific customer organization they belong to, letting applications correctly scope data per tenant.
Corporate Intranet with HR Sync
An “employee_id” attribute stores the matching identifier from the company’s separate HR system, letting internal applications cross-reference records reliably.
Localized Customer Portal
A “preferred_language” attribute, user-editable and exposed into the ID token, lets applications automatically display content in the language each customer prefers.
Professional Certification Tracking
A multi-valued “certifications” attribute lists every professional certification a user holds, used by an internal compliance dashboard to verify required qualifications.
14Frequently Asked Questions
No. An attribute must be explicitly connected to a protocol mapper before its value is included as a claim in an issued token. Simply defining an attribute doesn’t expose it anywhere by default.
Yes. Each attribute has independent view and edit permission settings for both administrators and the user themselves, allowing fine-grained control over visibility.
Built-in attributes, like email or first name, have special handling throughout Keycloak, including dedicated fields on login and registration screens. Custom attributes are additional fields an administrator defines for organization-specific needs.
Yes, if it’s configured as multi-valued. This is useful for list-like data, such as several certifications or phone numbers belonging to the same user.
It depends on the sensitivity. Ordinary descriptive information is generally fine, but highly sensitive data deserves careful visibility restrictions, and extremely sensitive secrets are better kept in a dedicated, purpose-built secure system instead.
Changing validation rules or permissions applies going forward, but it doesn’t automatically alter values already stored for existing users — those remain as they were until explicitly updated.
15Summary and Key Takeaways
User attributes in Keycloak let organizations extend the standard user record with exactly the extra information their applications actually need, without building a separate custom database just to hold it. Defined once through the realm’s user profile configuration, each attribute can carry its own validation rules and independent view/edit permissions for both administrators and users, and can optionally be exposed into tokens through a protocol mapper when an application genuinely needs to read it. This flexibility is one of the reasons Keycloak adapts smoothly to such a wide range of organizations and use cases — but it also means attribute design deserves real care: sensitive fields need carefully restricted permissions, exposed claims should stay lean, and a growing attribute list benefits from consistent naming and periodic review, just like any other piece of shared infrastructure.
Key Takeaways
- User attributes extend the user record beyond Keycloak’s built-in fields. — They let organizations store exactly the extra information their applications need.
- Attributes can be single-valued or multi-valued. — Multi-valued attributes suit list-like data, such as several certifications for one user.
- Every attribute has its own view and edit permissions. — Administrators and users can each be independently allowed or restricted from seeing or changing a given attribute.
- Attributes don’t automatically appear in tokens. — A protocol mapper must be explicitly configured to expose an attribute’s value as a claim.
- Validation keeps stored data clean and predictable. — Format and length rules can be applied per attribute to avoid messy or malformed values.
- Sensitive or business-critical attributes need restricted edit access. — Letting users freely edit certain attributes can allow them to grant themselves unintended privileges.
- Clear naming and periodic review keep the attribute list manageable. — Without discipline, custom attributes can sprawl into a confusing, hard-to-audit mess over time.