Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Realms, Users and Roles

Required Actions and User Federation (LDAP and Active Directory)

Use required actions to verify email, force password changes or set up OTP, and connect Keycloak to LDAP or Active Directory with user federation, mappers and sync modes.

Two features decide how users get into good standing: required actions, tasks a user must complete at their next login, and user federation, which connects Keycloak to an existing user directory so you do not have to copy thousands of accounts by hand. This lesson covers both.

Keycloak and LDAP servers cannot run on this site. The settings are described exactly as they appear in the admin console, and the runnable blocks are labelled stand-ins that model the logic (the action queue, LDAP filters, attribute mapping).

Required actions

A required action is something Keycloak makes the user do after authentication but before sending them back to the app. Typical ones:

Required action Purpose
Verify Email Sends a link; the user must click it to confirm the address
Update Password Choose a new password (used by "Temporary" and by expiry policies)
Update Profile Fill missing profile attributes
Configure OTP Register an authenticator app
Webauthn Register / Passwordless Register a security key or passkey
Terms and Conditions Accept terms (enable it first under Authentication > Required actions)
Update Email Change the email with verification
Verify Profile Check that the profile satisfies the user profile rules
Delete Account Let users delete themselves (disabled by default)

Enable and order them in Authentication > Required actions. Each can be Enabled and marked Set as default action, which attaches it to every new user. You can add one to a single user in Users > (user) > Details > Required user actions.

Admins can also trigger actions by email: Credential reset on a user sends a link with a chosen action list. Links expire according to Action token lifespan in Realm settings > Tokens.

Common recipe for self-registration: turn on Verify email in Realm settings > Login, set up SMTP in the Email tab, and make Configure OTP a default action for staff realms.

Why federation

Many organizations already keep users in LDAP (OpenLDAP, 389 Directory, Active Directory). User federation makes Keycloak read them so existing people can log in without migration. Keycloak ships providers for LDAP/Active Directory and Kerberos; you can write your own with the User Storage SPI (see the customization chapter).

Two strategies:

  • Import (default for LDAP): Keycloak copies user records into its database on first login or on a schedule and keeps a link to LDAP. Fast lookups, works offline from LDAP for reads.
  • No import: Keycloak queries LDAP each time and stores nothing locally. Slower, more consistent.

Add an LDAP provider

In the console: User federation > Add LDAP provider. Important fields:

Field Example Meaning
Vendor Active Directory / Other Sets sensible defaults
Connection URL ldaps://ldap.example.com:636 Always prefer LDAPS or StartTLS
Bind type / Bind DN / credentials cn=keycloak,ou=svc,dc=example,dc=com A read-only service account to search users
Users DN ou=people,dc=example,dc=com Where users live
Username LDAP attribute uid (OpenLDAP) or sAMAccountName (AD) Becomes the Keycloak username
RDN LDAP attribute uid / cn Naming attribute in the DN
UUID LDAP attribute entryUUID / objectGUID Stable unique ID
User object classes inetOrgPerson, organizationalPerson Filters which entries are users
Edit mode READ_ONLY / WRITABLE / UNSYNCED Whether Keycloak can write back
Import users On Copy to local DB
Sync registrations Off Create new Keycloak users in LDAP

Use Test connection and Test authentication buttons before saving. Then Synchronize all users pulls everyone in; Periodic full sync and Periodic changed users sync keep them aligned.

Passwords stay in LDAP: Keycloak performs a bind with the user's DN and password to verify them and does not copy hashes.

Mappers: translating attributes

An LDAP provider has mappers that translate LDAP attributes to Keycloak ones: givenName to firstName, sn to lastName, mail to email. Other mapper types:

  • role-ldap-mapper / group-ldap-mapper: map LDAP groups to Keycloak groups or roles.
  • hardcoded-ldap-role-mapper: grant a fixed role to every LDAP user.
  • user-attribute-ldap-mapper: map any custom attribute.
  • msad-user-account-control-mapper: respect disabled accounts in Active Directory.

Group mapping is the powerful one: mapping cn=engineering,ou=groups,... to a Keycloak group means directory membership drives roles automatically.

Operational notes

  • A federated user is shown in the console with a Federation link; deleting the provider removes imported users unless you Unlink users.
  • Users that disappear in LDAP are not deleted automatically by default; use the Remove invalid users sync action or disable the provider mapping.
  • Network access, timeouts and connection pooling matter: LDAP outages break logins for federated users.
  • Use a dedicated read-only bind account and LDAPS with a trusted certificate (configure the Keycloak truststore).
  • Kerberos / SPNEGO enables silent login from domain-joined computers; set it up only if your environment truly needs it.

Required actions as a queue (stand-in)

This runnable stand-in processes a user's pending actions in a fixed order before issuing a "login complete" result, like Keycloak's login pipeline. It is a model, not Keycloak.

Node.js Stand-in: required action pipeline

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.

LDAP filters and attribute mapping (stand-in)

LDAP searches use filters like (&(objectClass=inetOrgPerson)(uid=alice)). A common bug is unescaped user input in a filter (LDAP injection). This stand-in builds filters safely and maps an LDAP entry to a Keycloak user.

Node.js Stand-in: safe LDAP filter and attribute mapper

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 is a required action?

    Required actions interrupt the login until the user completes them.
  2. 2. Where does the password of an LDAP-federated user get verified?

    Keycloak validates by an LDAP bind and does not store the password hash itself.
  3. 3. Which attribute usually becomes the username for Active Directory users?

    AD uses sAMAccountName or userPrincipalName; OpenLDAP typically uses uid.
  4. 4. Why escape user input before putting it in an LDAP filter?

    Characters such as * ( ) and backslash have meaning in filters and must be escaped.

Summary

  • Required actions (Verify Email, Update Password, Configure OTP, Terms, and more) interrupt login until the user completes them.
  • Mark default actions in Authentication > Required actions; trigger one-off actions per user.
  • User federation connects LDAP, Active Directory and Kerberos so existing users can log in without migration.
  • LDAP provider settings: connection URL (use LDAPS), bind account, users DN, username and UUID attributes, edit mode, sync.
  • Mappers translate attributes and map directory groups to Keycloak groups and roles.

Next: OAuth 2.0 Grants Overview