Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Customization

User Profile and Required Actions

Configure the Keycloak declarative user profile: attributes, validators, permissions, groups of fields, and required actions such as verify email, update password and terms.

Every identity system collects some data about people: a name, an email, perhaps a phone number, a department, a locale. For years Keycloak treated custom attributes as free-form key/value pairs that any form could set. The declarative user profile (enabled by default in current versions) replaces that with a schema: you define the attributes, who can see and edit them, and how they are validated. This lesson covers the schema and the related idea of required actions, steps a user must complete before they get a session.

Keycloak does not run on this site. The JSON below is the shape used in the admin console's JSON editor; the TryIt blocks are JavaScript stand-ins that validate values against a similar schema.

Where to find it

Open Realm settings > User profile. The Attributes tab lists defined attributes; the JSON editor tab shows the whole configuration. Built-in attributes are username, email, firstName, and lastName. Add your own, such as department or phone.

An attribute has these pieces:

  • name: the key stored on the user (department).
  • displayName: a label, or a message key like ${department} for translation.
  • validations: rules such as length, pattern, options, email, integer, uri.
  • annotations: hints for forms, like inputType: select or inputTypeSize.
  • required: who must supply it (roles: user, admin) and in which contexts (scopes).
  • permissions: who can view and edit the attribute (user, admin).
  • selector (optional): applies the attribute only for certain client scopes.

A small configuration:

JSON
{
  "attributes": [
    {
      "name": "department",
      "displayName": "Department",
      "validations": { "options": { "options": ["finance", "sales", "support"] } },
      "required": { "roles": ["user"] },
      "permissions": { "view": ["admin", "user"], "edit": ["admin"] }
    },
    {
      "name": "phone",
      "displayName": "Phone",
      "validations": {
        "pattern": { "pattern": "^\\+[0-9]{8,15}$", "error-message": "Use international format" }
      },
      "permissions": { "view": ["admin", "user"], "edit": ["admin", "user"] }
    }
  ]
}

Here department is set by admins only (users see it but cannot change it), which is exactly what you want if the value feeds authorization claims. phone is editable by the user.

A validator stand-in

Validators run on registration, on account edits, and on admin edits. This stand-in applies the same kinds of rules:

JS Stand-in: validate a user against a profile schema

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

No output.

Permissions and security

Attribute permissions are a security feature, not just UX. If a profile attribute drives a claim like tenant or department, and users may edit it, any user could promote themselves. Rules of thumb:

  • Attributes used in authorization: edit by admin only.
  • Attributes users manage themselves (phone, locale): edit by user.
  • Attributes only the system sets: no edit permission for anyone in the UI; set them through the Admin API or mappers.
  • Mark sensitive attributes view-restricted if they should not appear in the account console.

Unmanaged attributes (values not defined in the profile) are controlled by the realm's Unmanaged attributes setting: Disabled (default), Enabled, Admin can view, or Admin can edit. Leave it disabled unless you need legacy data.

Required actions

A required action is a step Keycloak demands before issuing tokens. They appear after login (or after the first login) as full pages. Built-in ones include:

  • Verify Email
  • Update Password
  • Update Profile
  • Configure OTP (set up an authenticator app)
  • Terms and Conditions
  • Webauthn Register / Webauthn Register Passwordless (passkeys)
  • Delete Account, Update Email, Verify Profile (checks the user profile is complete)

Manage them in Authentication > Required actions. Each can be Enabled, and a Set as default action turns it on for every new user. You can also assign them to individual users in the user's Required user actions field, which is how an admin forces "update password at next login".

flowchart LR
  L["Credentials accepted"] --> Q{"Required actions pending?"}
  Q -->|"yes"| A["Show action page: update password, accept terms..."]
  A --> Q
  Q -->|"no"| T["Issue tokens"]

Actions run one after another until none remain.

Account console and self-service

The account console reads the same profile: attributes appear as form fields according to their permissions. Users can also manage credentials (password, OTP, passkeys), sessions, linked accounts, and applications there. Admins can ask for a fresh start via Credentials > Reset password, with a temporary option that adds Update Password as a required action.

Forced actions in code

A typical onboarding policy is "on first login: verify email, accept terms, set up OTP". This stand-in orders actions and shows how the queue drains:

JS Stand-in: required action queue

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should an attribute that feeds an authorization claim be admin-editable only?

    Self-editable attributes are untrusted input; restrict edit permission when they influence authorization.
  2. 2. Where are required actions managed?

    That page enables actions and lets you set defaults.
  3. 3. Which validator restricts a value to a fixed list?

    The options validator accepts only the listed values.
  4. 4. What does the Unmanaged attributes setting control?

    It decides whether free-form attributes outside the schema are allowed and who may see or edit them.

Summary

  • The declarative user profile defines attributes, validators, permissions, and annotations.
  • Use permissions to protect authorization-relevant attributes.
  • Required actions force steps like verify email, update password, OTP setup, and terms.
  • Keep unmanaged attributes disabled unless needed.
  • Test validation behaviour with real forms before launch.

Next: Production Configuration