Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Realms, Users and Roles

Users, Credentials and Password Policies in Keycloak

Manage Keycloak users: creation, attributes, user profile, password hashing, password policies, OTP and WebAuthn, temporary passwords, lockouts and the admin REST API.

Users are the reason Keycloak exists. This lesson covers how users are created and described, how their credentials are stored and protected, how password policies work, and how to automate user management with the admin REST API.

Keycloak's own server cannot run on this site, so the policy and hashing blocks below are runnable stand-ins that implement the same ideas (a policy checker, salted slow hashing). Real Keycloak does the work for you inside the server.

Creating users

There are four common ways:

  1. Admin console: Users > Create new user.
  2. Self-registration: enable User registration in Realm settings > Login; users fill a form themselves.
  3. Admin REST API or kcadm.sh for scripts and bulk loads.
  4. Federation or brokering: users are read from LDAP or created when someone first signs in with an external provider.

A user has a username, which must be unique in the realm and is stored lower-case, plus optional email, first name and last name. If Email as username is on, the email address doubles as the username.

The user profile

Since Keycloak 24 the realm has a declarative user profile (Realm settings > User profile). It lists every attribute the realm knows about: username, email, firstName, lastName and any you add, such as phone or department. For each you set:

  • the display name and the validators (length, regex, email format, options list),
  • whether it is required, and for whom (users, admins),
  • who can view and edit it (user, admin).

Attributes not declared in the profile are unmanaged: depending on the realm's Unmanaged attributes setting they are disabled (default), visible only to admins, or editable. Declaring attributes gives validation, forms and a clean contract with the apps that read them.

Credentials

A user can hold several credentials, shown on the Credentials tab:

Type Notes
Password Hashed with a slow algorithm and a per-user salt; the plain text is never stored
OTP (TOTP/HOTP) Authenticator app codes; configured by the user or via a required action
WebAuthn and passkeys Security keys, platform authenticators
Recovery codes One-time backup codes (feature)

When an admin sets a password, the Temporary switch forces the user to choose a new one at the next login. Use Temporary on for passwords you generated and told someone; use off only for passwords the user set.

Password hashing

Keycloak stores a salted hash of the password with a slow algorithm so that stolen hashes are expensive to crack. Recent versions default to Argon2; older versions use PBKDF2 with many iterations (pbkdf2-sha512). The algorithm and iteration count are part of the Hashing algorithm and Hashing iterations password policies. When you raise the strength, existing hashes are upgraded transparently the next time each user logs in. This is why you should not export password hashes into other systems casually.

Password policies

Set them in Authentication > Policies > Password policy. Each policy has a value.

Policy Effect
Minimum length At least N characters (prefer length over complexity, 12 or more)
Not username / Not email Password may not contain them
Uppercase, Lowercase, Digits, Special characters Require at least N of each
Password history Cannot reuse the last N passwords
Expire password Force a change after N days (use sparingly; modern guidance discourages routine rotation)
Not recently used / Blacklist Reject common passwords from a list file
Hashing algorithm / iterations Choose how new hashes are produced
Force expired password change Days before a forced change on login

Current guidance (for example from NIST) prefers long passphrases, a blocklist of known-bad passwords and MFA over composition rules and forced rotation. Combine length 12+ with a blacklist and offer OTP or passkeys.

Brute-force protection

Passwords can be guessed unless attempts are limited. In Realm settings > Security defenses > Brute force detection you choose permanent or temporary lockout, the number of failures before locking, the wait increment and the maximum wait. Temporary lockout is usually better: permanent lockout lets an attacker lock out real users on purpose.

The admin REST API

Everything in the console is available over REST. Get an admin token from the master realm, then manage users in the target realm.

Terminal
TOKEN=$(curl -s -d client_id=admin-cli -d username=admin -d password="$ADMIN_PW" \
  -d grant_type=password http://localhost:8080/realms/master/protocol/openid-connect/token \
  | jq -r .access_token)

# create a user
curl -i -X POST http://localhost:8080/admin/realms/demo/users \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"username":"bob","email":"[email protected]","enabled":true,"emailVerified":true,
       "credentials":[{"type":"password","value":"a-long-passphrase","temporary":true}]}'

# search
curl -s "http://localhost:8080/admin/realms/demo/users?username=bob&exact=true" \
  -H "Authorization: Bearer $TOKEN"

A successful create returns 201 Created with the new user's URL in the Location header. For automation prefer a dedicated service account client with only the manage-users role, not the bootstrap admin (see Client Credentials and Service Accounts).

A policy checker (stand-in)

This runnable stand-in implements the policies above. Add your own rules to see how a policy engine works.

Node.js Stand-in: password policy checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Slow hashing (stand-in)

Why does Keycloak spend time hashing? This stand-in uses Node's scrypt (a slow, memory-hard function similar in purpose to Argon2 and PBKDF2) with a random salt, and shows that the same password gives different hashes and that verification is constant-time.

Node.js Stand-in: salted slow password hashing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the Temporary switch do when an admin sets a password?

    Temporary adds the Update Password required action, so the admin-chosen password is replaced by the user's own.
  2. 2. Which approach matches current password guidance?

    Length, blocklists and MFA protect better than composition rules and routine rotation.
  3. 3. Why does Keycloak hash passwords with a slow algorithm and a per-user salt?

    Salt prevents precomputed tables and equal outputs; slowness limits guessing speed.
  4. 4. Which HTTP status does a successful POST /admin/realms/{realm}/users return?

    Creation returns 201 and the new user's URL in Location.

Summary

  • Users come from the console, self-registration, the admin API or federation and brokering.
  • The user profile declares attributes, validation, requiredness and who may edit them.
  • Credentials include hashed passwords, OTP, WebAuthn and recovery codes; Temporary forces a change.
  • Policies enforce length, history, blocklists and hashing strength; prefer length and MFA over rotation.
  • Brute-force detection limits guessing; the admin REST API automates everything with a scoped service account.

Next: Realm and Client Roles