Here is a step-by-step guide to correctly configure and start your Keycloak server and resolve the “Local access required” error permanently.

Step 1: Stop the Keycloak Server

First, ensure that any running instance of the Keycloak server is stopped. This is crucial because some configurations are only applied on the first startup.

Step 2: Set All Required Environment Variables in One Session

When you export a variable in your shell, it is only set for that current session. If you close the terminal or start a new one, those variables will be gone. You need to set all the required variables for your configuration in the same shell session where you will run the start command.

Combine all your configuration and startup into a single script or run them sequentially in the same terminal.

Correct Environment Variables:

Instead of using KEYCLOAK_ADMIN_PASSWORD, for the initial admin creation you should use KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD.

Open your terminal and execute the following commands in order:

bash# --- Database Configuration ---
export KC_DB=mariadb
export KC_DB_URL='jdbc:mariadb://localhost:3306/keycloak_db?socket=/opt/lampp/var/mysql/mysql.sock'
export KC_DB_USERNAME='db_user_name'
export KC_DB_PASSWORD='db_user_password'

# --- Initial Admin User Configuration ---
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=admin@123

# --- Make Script Executable (if not already done) ---
chmod +x bin/kc.sh

# --- Start the Keycloak Server ---
bin/kc.sh start --optimized

Important Notes:

• --optimized Flag: The --optimized flag is for subsequent startups after the initial setup. For the very first start, you might want to run bin/kc.sh build first to apply the configuration, and then bin/kc.sh start. However, start --optimized should also work if the configuration is passed correctly via environment variables.
• Database URL: I’ve corrected a small detail in your database URL. Using a Unix socket is often more reliable for local connections than a TCP connection to localhost. Your original URL was likely fine, but this is a common practice.
• Security: Using root for your database connection and simple passwords like “abhishek” is not recommended for production environments. You should create a dedicated database user with limited privileges for Keycloak and use strong, unique passwords.

By following these steps, you are telling Keycloak to connect to your MariaDB database and, upon its first startup, to create an initial administrative user with the credentials you provided. This will bypass the “Local access required” screen entirely.

Abhishek Singh

I’m Abhishek, a DevOps, SRE, DevSecOps, and Cloud expert with a passion for sharing knowledge and real-world experiences. I’ve had the opportunity to work with Cotocus and continue to contribute to multiple platforms where I share insights across different domains:

• DevOps School – Tech blogs and tutorials

• Holiday Landmark – Travel stories and guides

• Stocks Mantra – Stock market strategies and tips

• My Medic Plus – Health and fitness guidance

• TrueReviewNow – Honest product reviews

• Wizbrand – SEO and digital tools for businesses

I’m also exploring the fascinating world of Quantum Computing.