Skip to content
ineedcloudineedcloud — home
Browse guides
All guides
HomelabIntermediate

Create your first Keycloak realm and add users

Realms are how Keycloak separates tenants and apps. Here's how to set one up, create user accounts, and understand what you're looking at in the admin console.

12 min readLast updated 4 May 2026

TL;DR

Create a new realm (don't use "master"), add a user, set a temporary password, and log in as that user via the Account Console. Takes about 10 minutes once Keycloak is running.

What you'll need

Step 1 — Create a new realm

The master realm is for administering Keycloak itself. Your apps and users should live in a separate realm.

  1. In the admin console, click the dropdown in the top-left that says master
  2. Click Create realm
  3. Enter a Realm name — something short and lowercase with hyphens, e.g. myhomelab or mycompany
  4. Leave Enabled toggled on
  5. Click Create

You're now inside your new realm. Every setting you change from here applies only to this realm.

Step 2 — Add a user

  1. In the left sidebar, click Users
  2. Click Add user (top right)
  3. Fill in:
    • Username — required, e.g. alice
    • Email — optional but useful
    • First name / Last name — optional
  4. Leave Email verified off for now
  5. Click Create

Step 3 — Set a password

After creating the user you're taken to their profile page.

  1. Click the Credentials tab
  2. Click Set password
  3. Enter a password and confirm it
  4. Toggle Temporary to Off if you don't want to force a password change on first login
  5. Click Save, then Save password in the confirmation dialog

Step 4 — Log in as the user

Your realm has its own Account Console where users can manage their own profile and sessions.

Go to: http://localhost:8080/realms/YOUR_REALM_NAME/account

Replace YOUR_REALM_NAME with the name you chose in Step 1. Log in with the username and password you just set.

If you can log in, user management is working.

Step 5 — Create roles (optional)

Roles let you control what different users can access inside an app.

  1. In the left sidebar, click Realm roles
  2. Click Create role
  3. Enter a role name, e.g. admin or viewer
  4. Click Save

To assign the role to a user:

  1. Go to Users → select the user → click the Role mapping tab
  2. Click Assign role
  3. Select the role and click Assign

Your app can then read roles from the Keycloak token and grant or restrict access accordingly.

Common pitfalls

Using the master realm for apps. Don't. The master realm is for Keycloak admin accounts only. Create a dedicated realm for your apps and users.

Forgetting the realm name in URLs. Every realm has its own endpoint. If your realm is myhomelab, the login URL is .../realms/myhomelab/... — not .../realms/master/....

Temporary password loop. If you leave Temporary toggled on, users must change their password on first login. This is good practice for onboarding new users.

Where to go next