Features
User Management

User Management

User Management

Manage your application users efficiently with Skycloak’s comprehensive user management system. Create users, assign roles, manage groups, and control access - all from a unified interface that simplifies identity management across your applications.

Overview

User Management in Skycloak provides everything you need to:

  • Create and manage users across all your applications
  • Assign roles and permissions with fine-grained control
  • Organize users into groups for easier management
  • Import users in bulk from existing systems
  • Set password policies and manage credentials
  • Track user sessions and login activity
  • Configure self-registration and user profiles

Prerequisites

  • An active Skycloak cluster
  • A configured realm (default or custom)
  • Admin or user management permissions in your workspace
  • Basic understanding of Keycloak concepts (users, roles, groups)

Getting Started

Accessing User Management

  1. Select your cluster and realm in the sidebar’s context stack
  2. Click Users under the realm’s Identity section
  3. View your user list with search and filter capabilities

Users list view

The user table shows username, email, name, status, and verification state, with search, customizable columns, bulk actions, and pagination. Columns are not limited to the built-in fields: see showing attributes as columns.

Creating Users

Manual User Creation

  1. Click “Create User” button

  2. Fill in user details:

    • Username (required, unique identifier)
    • Email address (for notifications and password resets)
    • First and Last name
    • Initial password or temporary password
    • Email verified status
    • User enabled status

  3. Set initial configuration:

    • Temporary password (forces reset on first login)
    • Email verification requirement
    • Account activation status

Bulk User Import

For migrating existing users or creating multiple accounts:

  1. Click “Import Users” button

  2. Choose import format:

    • CSV file with user data
    • JSON format for advanced imports
    • LDAP/Active Directory sync

  3. Map fields to Keycloak attributes

  4. Review and confirm the import

Managing User Details

User Profile Information

Click on any user to access their detailed profile:

Basic Information Tab:

  • Personal details (name, email, username)
  • Account status and verification
  • User attributes and custom fields
  • Profile completeness indicators

The profile is organized into tabs — Profile, Credentials, Role Mappings, Groups, and Sessions — with actions to edit, reset the password, or delete the user.

Password and Credentials

Manage user authentication methods:

  1. Reset passwords with temporary or permanent options
  2. Configure MFA (TOTP, WebAuthn, etc.)
  3. View credential history and last change dates
  4. Set required actions for next login

Role Management

Assigning Roles to Users

Control what users can do in your applications:

  1. Navigate to Role Mappings tab

  2. View available roles:

    • Realm roles (global across realm)
    • Client roles (application-specific)
    • Composite roles (role groups)

  3. Assign roles by moving from Available to Assigned

  4. Set effective roles including inherited permissions

Understanding Role Hierarchy

Realm Roles - Apply across all applications:

  • admin - Full system access
  • user - Basic user access
  • developer - Development tools access
  • Custom realm roles you create

Client Roles - Application-specific:

  • app-admin - Admin for specific app
  • app-user - User for specific app
  • Application-defined roles

Group Management

Organizing Users into Groups

Groups simplify permission management for multiple users:

  1. Create groups with hierarchical structure
  2. Add users to groups individually or in bulk
  3. Assign roles to groups (inherited by all members)
  4. Set group attributes for additional metadata

Group Strategies

Department-based Groups:

/company
  /engineering
    /frontend
    /backend
    /devops
  /sales
  /support

Permission-based Groups:

/access-levels
  /read-only
  /editors
  /administrators

Project-based Groups:

/projects
  /project-alpha
    /developers
    /testers
  /project-beta

User Sessions and Activity

Monitoring Active Sessions

Track user login activity and manage sessions:

  1. View active sessions per user

  2. See login details:

    • IP addresses
    • Client/browser information
    • Session duration
    • Last activity time

  3. Revoke sessions individually or all at once

User Attributes and Metadata

Attributes are the extra fields you keep on a user beyond username, email, and name: a department, an employee number, a tenant ID, a plan level. Open any user and pick the Attributes tab to see what that user carries.

Attributes tab on a user

Editing attributes

Edit attributes opens every attribute at once. Add a row, rename a key, change a value, or remove one, then save the whole set in a single step.

Editing a users attributes

An attribute can hold more than one value. Use Add value to append to a key rather than replacing what is there. Attributes your identity provider owns are shown but not editable, because writing them here would be overwritten on the user’s next login.

If the tab says the realm hides attributes

A realm can refuse to hand out attributes that its user profile does not declare. This is Keycloak’s default (unmanagedAttributePolicy: disabled), and it is stricter than it sounds: attributes written by an import or by your own code still exist on the user, but the admin API will not return them, so nothing can display them, here or in the Keycloak admin console.

The realm hides undeclared attributes

Allow admins to manage them switches the realm to admin-managed attributes and the tab starts working immediately. It applies to the realm, not to one user, and it lets every admin on that realm read and edit those attributes.

Declaring each attribute in the realm’s user profile instead is the stricter option, and it buys you a display label, validation rules, and a field on the registration form. Reach for the button when you need to see what is already on your users; declare them in the user profile when you want the field to be part of your schema.

Showing attributes as columns

Attributes can sit alongside username and email in the users table. Choose Customize Columns and tick the ones you want.

Choosing attribute columns

The list offers every attribute the realm declares, plus any it finds on the users currently loaded, so an attribute that only exists on a handful of users still shows up as an option. Your choice is remembered per realm.

Attributes as columns in the users table

Two things to know. Sorting and searching still work on the built-in columns only, so you cannot order the table by an attribute. And if a column you enabled turns out to be empty for everyone on the page, the table says so rather than leaving you with a blank stripe.

Common attributes

  • department - the team a user belongs to
  • employee_id - an internal identifier
  • subscription_tier - the plan a user is on
  • tenant_id - which of your customers a user belongs to

To send any of these to an application, add a User attribute mapper on that application so the value lands in its tokens. See Applications.

Password Policies

Configuring Password Requirements

Set security standards for user passwords:

Policy Options:

  • Length - Minimum character count (8-128)
  • Complexity - Uppercase, lowercase, digits, special characters
  • History - Prevent reuse of recent passwords
  • Expiration - Force periodic password changes
  • Blacklist - Prevent common/compromised passwords

User Federation

Connecting External User Sources

Integrate existing user directories:

Supported Sources:

  • LDAP/Active Directory - Enterprise directories
  • Kerberos - Single sign-on
  • Custom Providers - Via SPI

Federation Benefits:

  • Sync existing users automatically
  • Maintain single source of truth
  • Preserve existing passwords
  • Map directory groups to Keycloak

Self-Registration

Enabling User Sign-up

Allow users to create their own accounts:

  1. Enable self-registration in realm settings

  2. Configure registration form:

    • Required fields
    • Custom attributes
    • Terms acceptance

  3. Set up verification:

    • Email verification required
    • Admin approval workflow
    • Domain restrictions

Best Practices

User Management Strategy

  1. Use groups for scale

    • Assign roles to groups, not individual users
    • Create logical group hierarchies
    • Use group attributes for metadata

  2. Implement strong password policies

    • Minimum 12 characters for standard users
    • Minimum 16 for administrators
    • Require MFA for privileged accounts

  3. Regular maintenance

    • Review inactive users quarterly
    • Audit role assignments monthly
    • Clean up test accounts

  4. Security considerations

    • Enable email verification
    • Use temporary passwords for new accounts
    • Monitor failed login attempts
    • Implement account lockout policies

Performance Optimization

For large user bases:

  • Use pagination and filters effectively
  • Implement user federation for external sources
  • Cache user attributes when possible
  • Use bulk operations for mass updates

Common Use Cases

Scenario 1: Onboarding New Employees

  1. Create user with temporary password
  2. Assign to appropriate department group
  3. Group automatically grants necessary roles
  4. User receives welcome email with instructions
  5. First login forces password change and MFA setup

Scenario 2: Customer User Management

  1. Enable self-registration with email verification
  2. Auto-assign “customer” role on registration
  3. Use attributes for subscription tiers
  4. Implement progressive profiling
  5. Track usage via session monitoring

Scenario 3: B2B Multi-tenant Setup

  1. Create groups per organization
  2. Use group attributes for organization metadata
  3. Assign organization-admin roles
  4. Implement domain-based registration
  5. Isolate users via group-based permissions

Troubleshooting

Common Issues and Solutions

User can’t log in:

  • Check user is enabled
  • Verify email if required
  • Check password hasn’t expired
  • Review required actions
  • Verify realm is correct

Roles not working:

  • Check effective roles (including inherited)
  • Verify client/realm role assignment
  • Clear user session/cache
  • Check role scope mappings

Import failures:

  • Validate file format (UTF-8 encoding)
  • Check for duplicate usernames
  • Verify required fields are present
  • Review import size limits

Email not sending:

  • Configure SMTP settings in realm
  • Check email template configuration
  • Verify user email address
  • Review spam filters

Security Considerations

Protecting User Data

  1. Data Privacy:

    • Limit attribute visibility
    • Use minimal data collection
    • Implement data retention policies
    • Enable GDPR compliance features

  2. Access Control:

    • Restrict user management permissions
    • Audit admin actions
    • Use principle of least privilege
    • Implement approval workflows

  3. Account Security:

    • Enforce strong passwords
    • Require MFA for sensitive roles
    • Monitor suspicious activity
    • Implement account lockout

API Integration

Programmatic User Management

Programmatic access to your Keycloak uses the per-cluster automation client with the OAuth2 client credentials grant. See Automating your Keycloak for where to find the credentials and how to obtain a token.

Manage users via Keycloak Admin API:

// Create a user
POST /admin/realms/{realm}/users
{
  "username": "john.doe",
  "email": "[email protected]",
  "enabled": true,
  "firstName": "John",
  "lastName": "Doe"
}

// Assign roles
PUT /admin/realms/{realm}/users/{id}/role-mappings/realm
[
  {
    "id": "role-id",
    "name": "user"
  }
]

// Add to group
PUT /admin/realms/{realm}/users/{id}/groups/{groupId}

Related Features

Next Steps

Last updated on
Migrating from KeycloakApplication Management