Creating an admin user in Keycloak is a mandatory step for automating administrative tasks and managing your Keycloak instance. This tutorial will guide you through the process of adding an admin user to Keycloak using the Web Console or environment variables.
The default flow to add an Admin User
Firstly, when you install a Keycloak server, you will be requested to enter an Admin user upon first access to the console (http://localhost:8080):
Although this is a simple approach, it would be better to have a way to automate the creation of the Admin User. Let’s see how to do it in the next section
Creating an Admin user using Environment Variables
For automation purposes, you can also define KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD before the first startup. These variables allow Keycloak to bootstrap an administrative user without manual input, making it ideal for containerized or scripted deployments.
It’s important to note that these environment variables are only effective during the first startup. Once the initial admin user is created, Keycloak will ignore these variables on subsequent launches—even if they’re still present—logging a warning instead of failing the startup. After the admin account is in place, you can manage users and roles through the Admin Console or the kcadm.sh command-line tool. This approach ensures a secure and streamlined initialization process while supporting both manual and automated workflows.
export KC_BOOTSTRAP_ADMIN_USERNAME="newadmin" export KC_BOOTSTRAP_ADMIN_PASSWORD="newadmin"
As you can see from the log of Keycloak, upon start-up the “newadmin” user has been added to the Realm “Master”:
Therefore, the next time you start Keycloak you won’t need to set again the Admin credentials
Creating an Admin User from the Realm
This option can be useful if you want to add one or more extra Admin users to your Keycloak server. Therefore, you will need to login with an Admin user on the Master Realm. Then, choose to add an User:
Set the User Credentials and Assign it to the Admin Role:
Now you can use the “newadmin” User as additional Administration User.
How to recover the Admin Password
Keycloak users are stored in a Database however you will not be able to recover the password by looking into the Database CREDENTIAL Table. There are some possible ways to reset the Admin Password though:
- Delete from the Database the Admin User. Although not the best option, you can find more details about this step in the following article: How to access Keycloak H2 Database
- Enable Password Recovery for Users in your Realm
In order to Enable Password Recovery for your Users, select in your Realm Settings the Login Tab. From there, enable the “Forgot Password” option:
As you can see, the next time you attempt a login in Keycloak you will see the “Forgot Password” link you can follow to recover your password:
Conclusion
That’s it! In this article we have discussed how to add an initial Admin user in Keycloak using the Web console or environment variables. We also discussed how to recover the Admin Password of your Keycloak Server.