Purpose
This guide explains how to create a new user in Keycloak and prepare that user for first access to the platform.
By the end of this guide, you will have:
- logged into Keycloak as an administrator
- selected the correct realm
- created a new user
- set the user details
- assigned an initial password
- understood the first-login password reset behavior
Overview
User creation in Keycloak is straightforward.
The normal flow is:
- log into Keycloak as admin
- move to the giotto realm
- open the Users section
- create a new user
- set the username and optional profile information
- assign an initial password
- confirm that Update Password is required
- let the user log in and change the password at first access
This guide follows exactly that path.
Before you begin
Make sure you have:
- admin access to Keycloak
- permission to manage users in the target realm
- the user details you want to create, such as:
- username
- optional email
- optional first name
- optional last name
Step 1 — Open Keycloak and log in as admin
Open the Keycloak admin interface and log in using your administrator credentials.
This gives you access to realms, users, clients, and credentials.
Step 2 — Move to the giotto realm
Once logged in:
- open the Realms section
- select the giotto realm
This is the realm where the new user will be created.
Step 3 — Open the Users section
Inside the giotto realm:
- go to the Users section
This is where existing users can be searched, viewed, and managed, and where new users can be created.
Step 4 — Create the new user
In the Users section:
- click the action to create a new user
This opens the user creation form.
Step 5 — Set the user details
In the user creation form, enter the required and optional user information.
At a minimum, set:
- Username
You can also optionally set:
- First name
- Last name
This is enough to create the user profile.
Required field
Username
The username is the main identifier the user will use to log in.
Optional fields
The user’s email address.
First name
The user’s first name.
Last name
The user’s last name.
Once the values are entered, save the user.
Step 6 — Set a password for the user
After the user has been created:
- open the user
- go to the Credentials section
- set a new password for the user
- share that password with the user securely
This password is only the initial password. The user will be required to change it at first login.
Important: share the initial password securely. Do not send it through unsafe channels or store it in shared documents.
Step 7 — Confirm that “Update Password” is required
After setting the password, go back to the user page.
You should notice that the Update Password action is now marked as a required user action.
This means the user is expected to change the password during the first login flow.
Why this matters
This is the normal and expected security behavior. It ensures that the administrator can create the account and bootstrap access, while the user still ends up with a personal password known only to them.
Step 8 — The user changes the password at first login
When the new user logs in for the first time:
- Keycloak will force a password update
- the user must choose a new password
- only after that step will the user be able to continue normally
This is the expected first-login experience for the newly created account.
What you have accomplished
At this point, you have:
- created a new user in Keycloak
- populated the main profile fields
- assigned an initial password
- prepared the account for first login
- ensured that the user will be required to choose a new password
This is the standard administrative flow for onboarding a new platform user.
Troubleshooting tips
I cannot create the user
Make sure you are logged in with sufficient administrative permissions and are working inside the correct realm.
I do not see the Users section
Verify that you selected the giotto realm and that your admin account has access to user management.
The password reset requirement does not appear
Check that the password was actually saved and that the required action was applied correctly.
The user cannot log in
Verify:
- the username is correct
- the initial password was shared correctly
- the user is logging into the correct Keycloak instance and realm
Best practices
Always create users in the correct realm
Make sure the account is created in the realm actually used by your platform deployment.
Share initial passwords securely
Treat the initial password as sensitive information.
Let users choose their own final password
Do not disable the first-login password update unless you have a very specific operational reason.
Fill optional fields when possible
Email, first name, and last name improve account manageability and identification later.
Comments
0 comments
Article is closed for comments.