What Are Required Actions in Keycloak?
The complete beginner-to-production guide to Required Actions — the checkpoints Keycloak inserts into login before it lets a user through.
Picture arriving at an airport with a valid ticket and a valid passport — both proofs check out, and yet the airline still stops you at the gate: “Your passport expires in three weeks, please renew it before your next trip,” or “Please update your emergency contact details before boarding.” You haven’t been denied travel — you’ve correctly proven who you are — but the airline has one more housekeeping step it insists on before letting you all the way through. In Keycloak, that extra insisted-upon step, inserted right in the middle of an otherwise successful login, is called a Required Action.
This guide explains exactly what Required Actions are, why Keycloak needs them, the built-in ones you’ll meet immediately, how to build custom ones, and the mistakes teams commonly make when relying on them. No prior identity or security background is assumed — every term is explained the moment it appears.
1Core Concepts
What Is a Required Action?
A Required Action is a task that Keycloak forces a specific user to complete before their login is allowed to finish — even though they’ve already entered a correct username and password. It’s a mandatory interruption inserted between “credentials verified” and “token issued.” Until the user completes the required task, Keycloak simply will not hand back a finished, usable session.
A Required Action is not the same as an authentication step (like entering a password). Authentication proves identity. A Required Action assumes identity is already proven and instead enforces a piece of account housekeeping or compliance before login can complete.
Why Required Actions Exist
Without this mechanism, an administrator would have no reliable way to force an important change onto a user’s account — like making sure a temporary password gets replaced, or that two-factor authentication gets set up — short of manually contacting every affected person individually. Required Actions let this be enforced automatically and consistently, right at the moment the user is already present and actively logging in.
Think of a gym that issues membership cards. The card scanner at the front door confirms your membership is valid (authentication). But if your annual liability waiver has expired, the front desk stops you right there and says “please re-sign this waiver before you go in” — you can’t reach the gym floor until that one specific task is done, no matter how valid your membership card is otherwise.
Per-User vs. Realm-Wide
Required Actions can be attached in two different ways: an administrator can flag one specific user’s account with a Required Action (perhaps after a suspected password leak), or an administrator can make a Required Action the automatic default for every newly created user in the entire Realm (like always requiring email verification for new signups).
2Architecture & Components
graph TD
U["User Account"] -->|"has attached"| RA1["Required Action:
Update Password"]
U -->|"has attached"| RA2["Required Action:
Configure OTP"]
Realm["Realm Settings"] -->|"sets default for new users"| RA3["Required Action:
Verify Email"]
Login["Login Flow"] -->|"after credentials verified"| Check{"Any Required
Actions pending?"}
Check -->|"Yes"| Prompt["User must complete
each pending action"]
Check -->|"No"| Token["Session & Tokens Issued"]
Prompt --> Token
Registry["Required Action Registry
(built-in + custom SPI providers)"] -->|"defines available types"| RA1
User Attribute
Each pending Required Action is stored directly on the user’s account record as a small flag Keycloak checks during login.
Realm-Level Default
A Realm setting that automatically attaches a given Required Action to every newly registered user.
Required Action Provider
The underlying implementation (built-in or custom) that defines what actually happens when the user is prompted to complete the action.
SPI (Service Provider Interface)
The plugin mechanism that lets developers write entirely custom Required Actions beyond Keycloak’s built-in set.
3Built-In Required Actions
| Required Action | What It Forces the User to Do |
|---|---|
| Update Password | Choose a new password before continuing — common after an admin resets a temporary password |
| Verify Email | Click a confirmation link sent to their email address before the account is treated as fully active |
| Configure OTP | Set up a one-time-password authenticator app before completing login, enforcing two-factor authentication |
| Update Profile | Fill in or correct missing profile fields (like first name, last name) before continuing |
| Terms and Conditions | Accept an updated terms-of-service agreement before continuing |
| Update User Locale | Confirm or set a preferred language/locale for the account |
Production Example: Employee Onboarding
A company provisioning new employee accounts commonly sets a temporary, shared initial password and attaches “Update Password” as a Required Action automatically. The very first time the new employee logs in, they’re forced to choose their own private password before reaching any internal application — closing the window where a temporary, potentially guessable password could be misused.
4Internal Working
Credentials Submitted
The user enters their username and password as usual, and Keycloak verifies them successfully — authentication itself succeeds at this point.
Required Action Check
Before issuing a token, Keycloak checks the user’s account record for any pending Required Actions — flags left over from an admin action or from the Realm’s default settings.
Login Paused
If one or more Required Actions are pending, Keycloak does not issue a token yet. Instead, it shows the user a dedicated screen for the first pending action — for example, a “choose a new password” form.
User Completes the Action
The user fills out whatever the action requires — sets a new password, scans a QR code to configure OTP, clicks a link in a verification email.
Flag Cleared
Once completed successfully, Keycloak removes that specific Required Action flag from the user’s account — it will not be asked again on future logins unless re-attached.
Next Action, or Token Issued
If another Required Action is still pending, the user is walked through it next. Once every pending action is cleared, Keycloak finally issues the login tokens and the user reaches the application.
5Data Flow & Lifecycle
Enablement. An administrator enables a Required Action type at the Realm level (making it available at all, and optionally as a default for new users).
Attachment. The action gets attached to a specific user — automatically at account creation (if set as a Realm default), by an administrator manually flagging an existing account, or occasionally by application code calling Keycloak’s admin API.
Pending State. The action sits as a pending flag on the user’s account, silently, until their next login attempt.
Completion. The user completes the required task during a login attempt, as walked through in Chapter 4.
Clearing. The flag is removed from the account. It stays cleared unless something re-attaches it later (like another forced password reset).
graph LR
A["Required Action
Enabled at Realm Level"] --> B["Attached to a User
(default on creation, or admin flag)"]
B --> C["Pending on Account
(silently, until next login)"]
C --> D["User Logs In"]
D --> E["User Completes the Action"]
E --> F["Flag Cleared
from Account"]
F --> G["Not Asked Again
Until Re-attached"]
6Advantages, Disadvantages & Trade-offs
Advantages
- Guarantees an important step happens, without relying on the user remembering or an admin manually following up
- Enforced automatically, right at the moment the user is already present and engaged (mid-login)
- Works uniformly across every application connected to the Realm — no need to build the enforcement separately per app
- Custom Required Actions let organizations enforce their own compliance steps beyond Keycloak’s built-in set
Disadvantages & Trade-offs
- Adds friction to the login experience — every additional Required Action is one more screen between the user and the application
- Stacking too many required steps on one login can frustrate users, especially on first-time onboarding
- A poorly tested custom Required Action can accidentally block every affected user from logging in at all
- Doesn’t apply retroactively to already-issued, still-valid tokens — it only intercepts new login attempts
7Security
Forcing Credential Rotation After a Breach
If a set of accounts is suspected of compromise — say, a leaked password database from an unrelated breach reused by some employees — an administrator can bulk-attach “Update Password” to every affected account. The very next login for each of those users is intercepted and forced through a password change, without needing to individually contact each person.
Enforcing Two-Factor Authentication Rollouts
When an organization decides to mandate two-factor authentication, attaching “Configure OTP” as a Required Action (either to specific accounts or as a new Realm default) is the standard way to guarantee every user sets it up before their next login succeeds, rather than hoping people opt in voluntarily.
Required Actions only intercept the login flow itself — they don’t invalidate sessions or tokens a user already holds. If immediate lockout is the goal (for example, during active incident response), an administrator also needs to explicitly revoke the user’s existing sessions, not just attach a Required Action and assume access stops right away.
Custom Required Actions and Trust
Because a custom Required Action runs as code directly inside the login pipeline, it should be reviewed with the same scrutiny as any other security-critical component — a bug here can either wrongly lock out legitimate users or, worse, be tricked into letting a login through when it shouldn’t.
8Monitoring, Logging & Metrics
Completion Rate
Tracking what percentage of prompted users actually complete a Required Action (like OTP setup) versus abandoning login shows whether the rollout is too disruptive.
Admin Attachment Events
Logging every time an administrator manually attaches a Required Action to an account provides an audit trail for incident-response actions like forced password resets.
Failure Alerts
A spike in users getting stuck or erroring out on a specific Required Action screen (especially a custom one) is an early signal of a bug blocking legitimate logins.
Help-Desk Correlation
Correlating support tickets about “I can’t log in” with recently attached Required Actions quickly narrows down the root cause.
9Best Practices & Common Mistakes
Best Practices
- Test custom Required Actions thoroughly in a non-production Realm before enabling them broadly
- Combine a forced password reset with explicit session revocation when responding to a real security incident
- Keep the number of stacked Required Actions for any single login as low as reasonably possible
- Clearly communicate to users in advance when a new mandatory step (like OTP setup) is being rolled out
Common Mistakes
- Assuming a Required Action alone revokes an already-active session — it doesn’t, without an explicit session invalidation step too
- Enabling a brand-new custom Required Action for the entire Realm without first testing it on a small pilot group
- Stacking too many Required Actions onto new-user defaults, creating a frustrating first-login experience
- Forgetting to remove a temporary Required Action default once its rollout period has ended
10Real-World & Industry Examples
Enterprise IT Onboarding
New-hire accounts are almost universally issued with a temporary password and “Update Password” attached, ensuring the very first login forces the employee to set something only they know.
Consumer Platforms Requiring Email Verification
Many consumer sign-up flows set “Verify Email” as a default Required Action for new accounts, ensuring a user can log in immediately but can’t take certain sensitive actions until the confirmation link in their inbox has been clicked.
Regulated Industries and Mandatory MFA
Organizations in finance and healthcare frequently mandate two-factor authentication for compliance reasons, rolling it out by attaching “Configure OTP” to all existing accounts at once, guaranteeing every user sets it up before their next successful login.
11Frequently Asked Questions
12Summary and Key Takeaways
Key Takeaways
- A Required Action is a mandatory task inserted between successful authentication and token issuance — the user cannot finish logging in until it’s completed.
- Built-in actions cover common needs: Update Password, Verify Email, Configure OTP, Update Profile, and Terms and Conditions.
- Required Actions can be attached to one specific user (often for incident response) or set as a Realm-wide default for every newly created account.
- Custom Required Actions are possible through Keycloak’s SPI, letting organizations enforce their own compliance steps.
- Attaching a Required Action does not revoke an already-active session — pair it with explicit session revocation when immediate lockout is the goal, such as during incident response.
- Keep the number of stacked Required Actions low, and test any custom one thoroughly before rolling it out broadly — a bug here can lock out legitimate users entirely.
- Monitor completion rates and failure spikes closely, since Required Actions sit directly in the critical path every user must pass through to log in.