Keycloak 26.3.3 — Resetting the Admin Password (Step-by-Step Guide)

👉 Now, the only way to create/reset the admin user is by using environment variables KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD before starting the server.

If an admin account already exists in the database, these environment variables will be ignored — you must clear the data or reset the DB.

2. Verify Environment Variables

Check if the variables are set:

echo $KEYCLOAK_ADMIN
echo $KEYCLOAK_ADMIN_PASSWORD

Or:

printenv | grep KEYCLOAK

Expected:

admin
StrongP@ss!123

3. Start Keycloak with New Admin Credentials

Development mode (file-based / H2 database):

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='StrongP@ss!123'

cd /opt/keycloak
./bin/kc.sh start-dev

On success, logs should show:

Creating initial admin user: admin

4. Fix: Admin Password Still Invalid

If you get “Invalid username or password”:

Case A — Using dev mode (H2/file store)

Reset by removing local data:

/opt/keycloak/bin/kc.sh stop 2>/dev/null || true
rm -rf /opt/keycloak/data

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='StrongP@ss!123'
/opt/keycloak/bin/kc.sh start-dev

This forces Keycloak to recreate the admin user.

Case B — Using MariaDB (LAMPP integration)

If Keycloak is connected to MariaDB, you need to reset the DB schema:

# Stop Keycloak
/opt/keycloak/bin/kc.sh stop 2>/dev/null || true

# Login to MariaDB
/opt/lampp/bin/mysql -u root -p

# Inside MariaDB shell
DROP DATABASE keycloak;
CREATE DATABASE keycloak CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'localhost' IDENTIFIED BY 'your_db_password';
FLUSH PRIVILEGES;
EXIT;

Now restart Keycloak with DB config:

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='StrongP@ss!123'

/opt/keycloak/bin/kc.sh start \
  --db=mysql \
  --db-url=jdbc:mariadb://127.0.0.1:3306/keycloak \
  --db-username=keycloak \
  --db-password=your_db_password

5. Common Errors & Fixes

• invalid_user_credentials → Admin exists in DB, env vars ignored → wipe data/reset schema.
• expired_code → Old login token cached → open an Incognito tab or clear cookies for localhost.
• No “Creating initial admin user” line → Admin was not recreated → confirm env vars are set in the same shell that starts Keycloak.
• Using sudo → sudo clears env vars → either sudo -E or start without sudo.

6. Persistence of Env Vars

To avoid retyping exports every time, add them to:

~/.bashrc

Example:

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='StrongP@ss!123'

Reload:

source ~/.bashrc

If using systemd service:

[Service]
Environment=KEYCLOAK_ADMIN=admin
Environment=KEYCLOAK_ADMIN_PASSWORD=StrongP@ss!123

7. Final Verification

Log in at:

http://localhost:8080

with:

• Username: admin
• Password: StrongP@ss!123

✅ With this tutorial, anyone on your team can reset the Keycloak admin password for both dev mode and MariaDB setup safely