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.

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

Custom User Attributes

Extend user profiles with custom data:

  1. Add custom attributes as key-value pairs
  2. Use attributes in:
    • Token claims
    • Application logic
    • User segmentation
    • Conditional access

Common attributes:

  • department - User’s department
  • employee_id - Internal ID
  • subscription_tier - Service level
  • preferences - JSON user settings

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