Last updated: July 2026
To enable user registration in Keycloak, open the admin console, go to Realm settings > Login, and toggle User registration ON. A Register link appears on the login page immediately. One thing changed in Keycloak 26.x, though: when Verify email is also enabled, the registration form no longer asks for a password. Users verify their email first, then set one.
Turn it on: the two-minute version
Self-registration is off by default in every new realm, and turning it on takes exactly one toggle:
- Log in to the Keycloak admin console and select the realm your app uses (not
master, that one is for administrators). - Go to Realm settings > Login.
- On the Login tab, flip User registration to ON.
Done. Open your app’s login page in a private window and you’ll see a Register link under the sign-in form. Clicking it renders Keycloak’s built-in registration page with first name, last name, email, and username fields.
If you don’t have an instance handy to follow along, our Keycloak Docker Compose generator will give you a disposable 26.x setup in about a minute. And if you’re still working out where Keycloak fits in your stack at all, start with the complete Keycloak guide and come back.
The toggle is the easy part. The decisions that actually matter come next: what the form asks for, how emails get verified, and how you keep bots out. Everything below is verified against Keycloak 26.7.0, released July 2026, and the current Server Administration Guide.
Why the registration form no longer asks for a password
This is the change that quietly made most older tutorials wrong, and the reason this guide got a full refresh. In Keycloak 26.x, when User registration and Verify email are both enabled, the registration form does not include password fields at all (Server Administration Guide).
The new sequence looks like this:
- The user fills in the registration form: name, email, username, plus any custom fields you’ve added.
- Keycloak sends a verification link to the email address they entered.
- The user clicks the link, proving they actually own that mailbox.
- Only then does Keycloak ask them to set a password.
The logic is sound. Unverified accounts never hold credentials, so a bot that hammers your registration form ends up with a pile of inert, passwordless records instead of usable accounts. And a user who typos their email finds out at step 2, loudly, instead of ending up with an account nobody can ever recover.
You can still keep password fields on the registration form by adjusting the registration flow, but Keycloak marks that configuration as deprecated. Treat it as a bridge for an in-flight migration, not something to build on. The docs also recommend enabling Forgot password alongside the new flow, so anyone who abandons registration halfway has a clean way back in rather than a support ticket.
One practical consequence worth saying out loud: email deliverability is now on the critical path of your signup conversion. If your verification mail lands in spam, the user never gets to set a password and the account never activates. We’ll deal with SMTP in a moment.
If the tutorial you were reading has screenshots with password fields on the registration form, check its publish date. The guides currently ranking for this topic were all written before this behavior existed.
What do the other Login tab settings do?
The User registration toggle shares the Login tab with six settings that shape the whole sign-up and sign-in experience. Here’s what each one does:
| Setting | Default | What it does |
|---|---|---|
| Email as username | Off | Drops the separate username field entirely; the email address is the username. |
| Login with email | On | Lets users sign in with their email address as well as their username. |
| Duplicate emails | Off | Allows multiple accounts to share one email address. Auto-disabled when Email as username and Login with email are on, since both depend on emails being unique. |
| Verify email | Off | Requires users to confirm their address via an emailed link. Needs SMTP configured first. |
| Forgot password | Off | Adds a password reset link to the login page. Recommended alongside the 26.x email-first flow. |
| Remember me | Off | Shows a checkbox that keeps the session alive across browser restarts. |
For a typical customer-facing app, our recommended combination is Email as username ON (nobody remembers a username they invented under pressure), Verify email ON, and Forgot password ON. You’ll notice Keycloak grays out Duplicate emails on its own once the email-based login settings are active; that’s expected, not a bug.
Configure SMTP before you enable Verify email
Verify email does nothing useful until Keycloak can actually send mail, and in 26.x that’s a bigger deal than it used to be. The verification email is no longer a nice-to-have follow-up; it carries the link where the user sets their password. Broken SMTP means registration silently dead-ends.
Set it up under Realm settings > Email:
- From address (plus an optional display name)
- Host and Port of your mail server
- Encryption settings for the connection
- Authentication: username and password, or token-based authentication, which 26.x supports for providers that have retired basic SMTP auth
Run a full test registration with a real inbox before you announce anything. Check the spam folder too. In our experience, the “registration is broken” reports that reach support are SMTP problems far more often than they’re Keycloak problems.
Add custom registration fields without touching a theme
The old advice was that custom registration fields meant a custom FreeMarker theme or a registration SPI, which is exactly the kind of maintenance burden that makes people wary of Keycloak. That advice is stale. Since Keycloak 24, the declarative user profile is the default, and it lets you add, validate, and render custom fields entirely from the admin console (Server Administration Guide).
To put a new field on the registration form:
- Go to Realm settings > User profile.
- Click Create attribute and name it, say,
company. - Set Who can edit to User.
- Mark the attribute Required to expose it on the registration form.
Validation is declarative too. The built-in validators cover most of what you’d otherwise write code for:
lengthfor minimum and maximum characterspatternfor regex matchingemailfor address formatoptionsfor a fixed list of allowed valuesiso-datefor date fieldsusername-prohibited-charactersfor keeping usernames sane
Rendering is controlled through annotations on the attribute: inputType picks the widget (a select, a textarea, and so on) and inputHelperTextBefore adds explanatory copy above the field. No theme files, no redeploys, no SPI jar to babysit through upgrades.
Two related notes. First, the VerifyProfile required action ships enabled by default, so if you later add a required attribute, existing users get prompted to fill it in at their next login. Your profile data converges without a migration script. Second, if what you want to change is how the registration page looks (logo, colors, layout), that’s still a theme concern; on Skycloak that’s handled through custom branding so you’re not maintaining FreeMarker templates yourself.
The user profile is also where registration stops being a one-time event and becomes part of the account lifecycle. Attribute permissions decide what users can see and edit later from the account console, which is worth thinking through as one system; our user management feature page shows how that looks on a managed setup.
Customize the registration flow: terms, conditions, and steps
The registration form is backed by an authentication flow you can edit under Authentication > Flows > registration. Each row in the flow is an execution, and each execution can be set to Required, Alternative, or Disabled. This is the same place the deprecated keep-the-password-on-the-form option lives, and where CAPTCHA steps get added.
The most common customization by far is a terms-of-service acceptance:
- Go to Authentication > Required actions and enable Terms and conditions.
- Open the registration flow and set the Terms and conditions row to Required.
New users now have to accept your terms before their account is created, with no code involved. The acceptance is enforced by Keycloak itself, not by a checkbox your frontend could forget to send.
Add a CAPTCHA: reCAPTCHA is native, Turnstile is not
An open registration form on the public internet will collect bots. Even with 26.x’s email-first flow blunting the damage, you probably don’t want thousands of junk records in your user database. Keycloak ships two native CAPTCHA options, and both are Google’s.
reCAPTCHA v2 or v3. Add the reCAPTCHA execution to your registration flow and configure the Site Key and Secret from your Google admin console. There’s one catch that trips almost everyone: Google renders the widget in a frame, and Keycloak’s default security headers refuse to load it. You have to relax the headers under Realm settings > Security defenses to allow Google’s frame through.
reCAPTCHA Enterprise. Duplicate the built-in registration flow, add the Enterprise execution as a sub-step, and configure the Project ID, Site Key, API Key, and a minimum score below which registrations get rejected.
Cloudflare Turnstile. Not supported natively, full stop. There’s an open feature request at keycloak/keycloak#44305, and community providers exist, such as keycloak-turnstile. Those work, but they mean deploying a third-party JAR and carrying it through every Keycloak upgrade yourself. If your stack is all-in on Cloudflare, weigh that maintenance cost honestly; plenty of teams decide the Google dependency on this one form is the cheaper trade.
Can you restrict registration to specific email domains?
Not natively, and this one surprises a lot of B2B teams. Keycloak has no built-in email domain allowlist for registration.
The workable native option reuses the user profile machinery from earlier: put a pattern validator on the built-in email attribute with a regex that matches only your approved domains. Something like:
^[A-Za-z0-9._%+-]+@(acme.com|acme.dev)$It works, but it’s a blunt instrument. The rejection surfaces as a generic validation error rather than a friendly “this domain isn’t allowed” message, the regex gets unwieldy past a handful of domains, and there’s no admin UI for the list itself. If you need a real allowlist or blocklist that non-developers can manage, that’s extension territory.
Before building any of it, ask whether open registration is the right model at all. If you’re onboarding business customers team by team, an invitation-driven approach is usually cleaner than policing a public form; we walked through that pattern in self-service client onboarding in Keycloak.
What to build after registration works
Registration is the front door of the self-service lifecycle, not the whole house. Once people can sign up on their own, the next expectations arrive fast: verifying and editing their profile, resetting credentials without a support ticket, and eventually leaving cleanly. That last one is both a UX courtesy and a GDPR obligation, and Keycloak can handle it with the same no-code approach used here; we covered it in self-service account deletion in Keycloak.
Get the front door right first, though. A registration flow with verified emails, declarative custom fields, and a CAPTCHA at the gate covers what most production apps need, and every piece of it above ships in stock Keycloak 26.x.
Frequently asked questions
How do I enable self-registration in Keycloak?
Go to Realm settings > Login and toggle User registration ON; a Register link appears on the login page immediately. For production, pair it with Verify email and Forgot password, and configure SMTP under Realm settings > Email so verification mails actually send.
How do I add custom fields to the registration form without a custom theme?
Use the declarative user profile, which has been the default since Keycloak 24. Under Realm settings > User profile, create the attribute, set Who can edit to User, and mark it Required to expose it on the registration form. Built-in validators like pattern, length, and options handle validation, and annotations like inputType control rendering, all without theme code.
Why doesn’t the Keycloak registration form ask for a password anymore?
Because in 26.x, with User registration and Verify email both enabled, users verify their email address first and set a password afterwards. That way unverified accounts never hold credentials. You can restore the password fields via the registration flow, but the option is deprecated; the docs recommend enabling Forgot password as the fallback instead.
How do I add reCAPTCHA or Turnstile to Keycloak registration?
reCAPTCHA v2/v3 and reCAPTCHA Enterprise are native: add the execution to the registration flow with your keys, and relax the headers under Realm settings > Security defenses so Google’s frame can load. Turnstile has no native support (feature request keycloak/keycloak#44305 is open), so you’d need a community provider such as panpaul/keycloak-turnstile and accept the upgrade maintenance that comes with it.
Can I restrict Keycloak registration to specific email domains?
There’s no native allowlist. The built-in workaround is a pattern validator on the email attribute in the user profile, using a regex that matches your approved domains. That holds up for a few domains but scales poorly, so a managed allowlist needs an extension, or an invitation-based onboarding model instead of open registration.
