Keycloak required actions are a powerful, yet often misunderstood, mechanism for ensuring users provide critical information or complete essential setup steps when they first log in. The most surprising thing about them is that they aren’t just for initial onboarding; they can be dynamically triggered for existing users to enforce policy changes or gather new data without requiring manual administrative intervention.
Let’s see this in action. Imagine a new security policy that requires all users to set up multi-factor authentication (MFA) within 7 days of its enactment.
First, we define the "Configure Two-Factor Authentication" required action in Keycloak. This is a built-in action, so we just need to select it. Then, we associate it with a specific user group, say "All Employees."
# This is a conceptual command, actual configuration is done via the Keycloak Admin Console or Admin API.
# Example of adding a user to a group that has a required action associated:
# POST /admin/realms/{realm}/users/{userId}/groups/{groupId}
Now, when any user in the "All Employees" group logs in for the first time after this required action is enabled, they’ll be immediately presented with a prompt to set up their MFA. They won’t be able to access any protected applications until they complete this step.
The system works by checking for associated required actions against a user’s profile before issuing an authentication token. If any required actions are pending for that user, Keycloak intercepts the login flow and redirects them to the specific action’s UI. Once the user successfully completes the action, Keycloak marks it as done for that user, and they can proceed.
Here’s a breakdown of the key components and levers:
- Required Actions List: This is where you enable or disable built-in actions (like "Update Profile," "Configure Two-Factor Authentication," "Verify Email") or create custom ones. You can also set a "Default period" for how long users have to complete an action before they are blocked.
- User Federation/Identity Providers: If you’re using an external IdP like Active Directory or LDAP, required actions can still be enforced. Keycloak will apply them after the user is successfully authenticated by the external provider.
- User Groups: Associating required actions with groups is crucial for targeted enforcement. You can have different sets of required actions for different user segments (e.g., administrators vs. regular users).
- Authentication Flows: Required actions are integrated into Keycloak’s flexible authentication flow. You can even customize when during the login process a required action is checked or presented. For example, you might want to force an email verification after they’ve successfully logged in once, rather than before.
- Admin Console & API: All this configuration can be managed through the Keycloak Admin Console or programmatically via the Keycloak Admin REST API, allowing for automation and integration into CI/CD pipelines.
The "Update Profile" required action, for instance, is incredibly versatile. It allows administrators to define specific user attributes (like "Employee ID" or "Department") that must be filled in by the user. If you have a critical piece of user data that’s currently optional but you need it for everyone, you can make "Update Profile" a required action, specify those attributes in the action’s configuration, and users will be prompted to enter them on their next login.
What many people overlook is the User Profile configuration within Keycloak’s realm settings. This is where you define the schema for user attributes, including whether they are required, optional, or immutable. When you configure the "Update Profile" required action, you’re essentially telling Keycloak to enforce the required constraints defined in your User Profile schema during the login flow. If an attribute is marked as required in the User Profile but you haven’t enabled "Update Profile" as a required action, users might be able to log in without it, leading to inconsistent data. The required action is the enforcement mechanism for the schema definitions.
The next logical step is to explore how to build custom required actions for unique workflows that aren’t covered by the built-in options.