How to add an Admin User in Keycloak

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):

keycloak ad admin user

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

You can use the KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD to set an initial Administration user for Keycloak. This is a good idea for two reasons:

  1. You can automate the installation of Keycloak and the creation of an Admin User in a single Shell.
  2. It works both in a bare metal installation and in a Container, therefore it’s a way to define the Admin user in a common way.

To do that, simply set the variables KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD before starting Keycloak:

export KEYCLOAK_ADMIN="newadmin"
export KEYCLOAK_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”:

keycloak step by step guide add admin user

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:

keycloak admin user

Set the User Credentials and Assign it to the Admin Role:

keycloak how to recover admin password

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:

  1. 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
  2. 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:

keycloak lost admin password

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:

keycloak adding admin user

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.