Keycloak Bootstrap Admin: Create the Initial Admin User

You installed Keycloak, but no application administrator exists yet — or you are about to start it for the first time and need to know how the initial admin is created before you can open the Admin Console.

This guide covers first-time bootstrap only: how Keycloak creates the first temporary administrator in the master realm. It does not cover recovering access when you have already run Keycloak and lost the admin password.

What is a Keycloak bootstrap admin?

When Keycloak starts on an empty database, it has no configured application administrator yet. A bootstrap administrator is the first admin user Keycloak creates so you can sign in to the Admin Console and manage the server.

• The bootstrap admin belongs to the built-in master realm — not to application realms you create later.
• Bootstrap accounts are temporary. Keycloak marks them in the Admin Console until you finish setup and remove them if needed.
• After master exists, bootstrap settings are for initial creation only — they do not reset a forgotten password on an existing admin.

Does Keycloak have a default admin username and password?

Keycloak does not ship a built-in admin / admin account you can sign in with on every install. You create the initial administrator yourself — through the Welcome Page, bootstrap configuration, or the bootstrap-admin command.

If you set a bootstrap password but omit the username, Keycloak defaults the temporary username to temp-admin. That is a bootstrap default for the username only — not a default password. You must still supply KC_BOOTSTRAP_ADMIN_PASSWORD (or the equivalent keycloak.conf / CLI option). There is no universal factory password.

Which method should you use?

Pick one path for your first start. You do not need all four.

Create the first admin with KC_BOOTSTRAP_ADMIN_USERNAME

Set username and password before the first start while the database is still empty. Keycloak creates a temporary admin when it creates master.

Generic Keycloak (ZIP layout):

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD='YourBootstrapPassword'
bin/kc.sh start-dev

Equivalent startup options:

bin/kc.sh start-dev \
  --bootstrap-admin-username=admin \
  --bootstrap-admin-password='YourBootstrapPassword'

First boot logs should include:

KC-SERVICES0050: Initializing master realm
KC-SERVICES0077: Created temporary admin user with username admin

Open http://localhost:8080/admin/ (or your host URL) and sign in. Full variable spelling is in Keycloak environment variables.

How bootstrap settings map to configuration sources

Keycloak accepts the same bootstrap values through environment variables, keycloak.conf, or CLI flags. The names differ by source:

Do not put KC_BOOTSTRAP_ADMIN_USERNAME inside keycloak.conf — that file uses the bootstrap-admin-* keys. See Keycloak keycloak.conf configuration for how configuration sources merge.

ZIP or systemd

Set bootstrap values in keycloak.conf, an environment file sourced before kc.sh, or Environment= lines in the systemd unit. Then run bin/kc.sh start or start-dev once against an empty data directory.

Example keycloak.conf fragment:

bootstrap-admin-username=admin
bootstrap-admin-password=YourBootstrapPassword

Docker or Podman

Pass the same variables with -e or an env file on first container start. The example below is a development-mode container (start-dev with an embedded database) — not a production persistence layout. Production deployments usually store realm data in an external database; see Configure Keycloak with PostgreSQL.

docker run -d \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD='YourBootstrapPassword' \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:26.7.3 start-dev

Replace docker with podman on Podman hosts. A full lab walkthrough is in Install Keycloak with Podman.

Kubernetes without Keycloak Operator

For a hand-written Deployment or StatefulSet (not the Keycloak Operator), set KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD in the pod env — or reference a Secret — before the first pod starts against an empty database.

For production start with PostgreSQL, set bootstrap variables together with KC_DB_* before the first start — see Configure Keycloak with PostgreSQL. For Kubernetes, use the Keycloak Operator and spec.bootstrapAdmin in Install Keycloak on Kubernetes.

Kubernetes with Keycloak Operator

The Keycloak Operator handles initial admin bootstrapping through spec.bootstrapAdmin. You can point it at a Secret you create, or let the Operator generate credentials.

If you do not configure spec.bootstrapAdmin, the Operator creates a Secret named:

<keycloak-cr-name>-initial-admin

That Secret contains a generated username and password for the first sign-in.

Retrieve the generated credentials:

kubectl get secret example-keycloak-initial-admin -n keycloak \
  -o jsonpath='{.data.username}{"\n"}{.data.password}{"\n"}' \
  | while read -r key; do echo -n "$key" | base64 -d; echo; done

Replace example-keycloak with your Keycloak custom resource name and adjust the namespace. Operator install and CR examples are in the Operator documentation.

Create the first admin from the Welcome Page

When Keycloak is reachable from your browser on local access and you did not set bootstrap credentials, the Welcome Page prompts you to create the initial administrator on first visit.

This is convenient for a local ZIP install or when you port-forward the Admin Console to localhost. For remote servers, containers, or Kubernetes without local browser access, set KC_BOOTSTRAP_ADMIN_* before the first start instead of relying on the Welcome Page.

Create the admin before first startup with bootstrap-admin

You can run bootstrap-admin before Keycloak has ever started. It creates the master realm offline; startup bootstrap options are then ignored on the first start.

Use the same database settings you will use when the server runs:

export BOOTSTRAP_PASS='YourBootstrapPassword'
bin/kc.sh bootstrap-admin user \
  --username admin --password:env BOOTSTRAP_PASS --no-prompt

Then start Keycloak normally (bin/kc.sh start-dev or start). This suits automation that prepares the database before the first pod or container starts — not the usual path for a first manual install.

On Docker, Podman, or Kubernetes, run the same bootstrap-admin command in a one-off container or Job with the same image and database configuration as production — see Reset Keycloak admin password for how execution differs by deployment when nodes must be stopped.

What to do after the first admin login

Bootstrap accounts are temporary. After you sign in for the first time:

1. Sign in using the temporary bootstrap administrator (admin, temp-admin, or the Operator-generated user).
2. Create or configure the permanent administrator account you intend to keep (username, password, roles).
3. Verify the permanent administrator can sign in to master and open the Admin Console.
4. Delete the temporary bootstrap account from Users in master.

Step-by-step user creation and role assignment are in Create and manage Keycloak users.

Why KC_BOOTSTRAP_ADMIN_PASSWORD does not change an existing password

KC_BOOTSTRAP_ADMIN_* applies only when Keycloak creates master for the first time. Once master and the admin user exist, changing those variables does not update the stored password — even if you restart the server.

If bootstrap credentials remain configured after the initial admin exists, logs may report that the initial administrator could not be created. That is expected when the current admin still works; remove the bootstrap variables if you no longer need them.

This is initial bootstrap only. If master already exists and you have lost access, see Reset Keycloak admin password and recover access.

Common bootstrap admin problems

Summary

Create Keycloak’s first administrator before or during the first start: use the Welcome Page on local access, set KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD for servers and containers, use spec.bootstrapAdmin or the Operator initial-admin Secret on Kubernetes, or run bootstrap-admin user only when you must prepare master before the server starts. The account lives in master and is temporary — replace it with a permanent admin and delete the bootstrap account.

Bootstrap environment variables do not reset a password after master exists. If you cannot sign in to an already-configured Keycloak, use the recovery guide: Reset Keycloak admin password and recover access.

References

• Bootstrapping and recovering an admin account — startup bootstrap and bootstrap-admin overview
• Configuring Keycloak — configuration sources and bootstrap options
• Keycloak Operator — basic deployment — spec.bootstrapAdmin and initial-admin Secret
• Upgrading Guide — migration from KEYCLOAK_ADMIN to KC_BOOTSTRAP_ADMIN_*