Deploying and Configuring Keycloak

If you have a web application and you don’t want to write your own authentication from scratch, most likely, Keycloak will come in handy. This is a ready-made user management system that can do everything: logins, roles, tokens, social networks, and even SSO out of the box.

In this article, we’ll look at how to deploy Keycloak on a Hostman server and configure authentication for your applications.

What Keycloak Is and What It Does

Keycloak is a service that takes over all the work with authorization and authentication. Instead of building your own system of logins, passwords, email confirmations, roles, and tokens, you just connect Keycloak and get everything you need.

Keycloak functions as an independent service: it has a control panel, a REST API, integration with external systems, and clients for popular languages and frameworks. In essence, Keycloak becomes the central authorization hub in the project: users authorize through it, receive tokens, and then get into your applications.

Key scenarios where Keycloak shows itself best:

• Single Sign-On (SSO) — one login for all your services.
• OAuth2 and OpenID Connect — ready-made implementation of standards.
• Roles and groups — determine which actions are available to a user.
• Social logins — login through Google, GitHub, etc.
• User management — creation, ban, password reset, email confirmation.
• Integration with any frontends and backends — Java, Python, Node.js, React, Angular.

Keycloak helps not only to quickly launch login via username and password but also to scale access: from one landing page to dozens of microservices with different permissions.

Installing Keycloak

You can deploy Keycloak anywhere, from a home server to Kubernetes. But if you need a quick start without unnecessary complications, a regular VPS is suitable. Let’s see how to install Keycloak in Hostman conveniently, quickly, and inexpensively.

What you will need:

• A Hostman account
• A cloud server (VPS) on Ubuntu 22.04
• Installed Docker and Docker Compose (we’ll show below)

Step 1. Create a server in Hostman

1. Go to the control panel → Cloud servers.
2. Click Create.
3. Select the Ubuntu 22.04 image.
4. Set the parameters (CPU, RAM, disk); the minimum configuration is enough for a test.
5. Launch the server and connect to it via SSH.

Step 2. Install Docker and Docker Compose

This can be done in two commands:

curl -fsSL https://get.docker.com -o get-docker.sh  
sh get-docker.sh  

Wait until the commands finish executing.

Step 3. Create a Docker Compose file

Create a folder for the project and a configuration file:

mkdir keycloak && cd keycloak  
nano docker-compose.yml  

Insert the following content:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.3.2
    command: start-dev
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    ports:
      - "8080:8080"
    restart: always

Save with the key combination Ctrl+O, then Enter to confirm. Close the editor with the combination Ctrl+X.

Step 4. Start Keycloak

Use the command:

docker compose up -d

In a minute, Keycloak will be available at:

http://<your_IP>:8080

Step 5. Disable the HTTPS requirement (only for testing)

By default, Keycloak requires HTTPS even in dev mode, which may result in the message “HTTPS required” when opening.

To disable this behavior only in the test environment, run the following commands inside the Keycloak container:

docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin  
docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE  

After this, you can refresh the page; the HTTPS message will disappear. Now you can log in to the panel with the username and password admin.

Basic Keycloak Configuration

After successfully launching the container with Keycloak, you will get the admin panel at the address:

http://<your-server>:8080/admin  

This is where all configuration takes place: from creating realms to connecting clients, roles, and users.

Realms

In Keycloak, everything starts with a realm. It’s like a separate “world” with its own database of users, security settings, and applications.

Imagine you are building a platform with two projects: an internal portal for employees and a website for clients. Each has its own users, its own roles, its own login settings. To avoid storing everything together, you create two realms: staff and clients. They are completely isolated from each other: logins, rules, login pages, and even password policies can be configured differently.

A realm is a way to maintain order in the system and not mix users from different applications.

Let’s create our own realm. To do this, go to the Manage realms tab (1) in the admin panel and click the Create realm button (2).

Navigation to creating a realm in Keycloak: the “Manage realms” tab and the “Create realm” button

Next, enter the realm name and click the Create button.

Realm creation form: entering the name and confirming by clicking “Create”

Go back to the Manage realms tab and click on the new realm; now it is selected by default.

If you are testing Keycloak, disable the SSL certificate requirement for the new realm; it is not required in the test environment. Use:

docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/<NEW_REALM_NAME> -s sslRequired=NONE  

Users and Roles

Users are people or services that will log into your applications through Keycloak. Each has its own username, password, and set of permissions.

Users without assigned roles do not get access to any functions. To determine what they can and cannot do, roles are assigned to them.

Roles are labels like “admin,” “manager,” “viewer.” They don’t do anything by themselves, but they let the application know: “this person is an admin, they can delete; and that one can only view.”

Create your own role. To do this, go to the Realm roles tab (1) and click the Create role button (2).

Navigation to the roles section: the “Realm roles” tab and the “Create role” button for creating a new role

Enter the role name and click the Save button.

Creating a role

Now let’s try creating a user. Go to the Users tab and click the Add user button. Be sure to enter a username, and optionally an email, first name, and last name. Click Create.

Creating a user: specify the parameters and save with the “Create” button

Assign the new user a password for login. To do this, on the opened page, go to the Credentials tab (1), click the Set password button (2), set the password and repeat it. Leave the Temporary parameter enabled so that the new user changes their password after their first login into the system.

Assigning login credentials: open the “Credentials” tab and enter the password of the new user

Now assign the new user a role. In the same section, go to the Role mapping tab (1), click the Assign role button (2) → Realm roles (3).

Assigning a role: open the “Role mapping” tab and select the desired role via “Assign role” → “Realm roles”

Select the role and click Assign.

Selecting a role from the list and confirming the assignment with the “Assign” button

Now the role is assigned to the user.

Clients

Clients in Keycloak are applications that connect to the authorization system. Through them, the user logs into the service, and Keycloak verifies their identity and rights. Without a client, the system will not understand where the user came from, where to return them after login, and what permissions can be given.

For each client, you can configure the login method: by username and password, through social networks, with two-factor authentication, or with tokens. You can allow or deny specific roles. You can specify where to redirect the user after successful login and after logout.

Important: the same user can log into different clients. For example, in the frontend client, they log in as a regular user, and in the admin-panel client as a moderator. This is convenient when the application has multiple interfaces with different access levels.

Authorization begins with the client. The application redirects the user to Keycloak. It verifies their data and returns them with a token. And the application uses this token to find out who it is dealing with and what is allowed for them.

Create a test client. Go to the Clients tab and click the Create client button. Enter the client name in the Client ID field. At the Login settings step, in the Valid redirect URIs field, enter valid paths where the user can be redirected after authorization. For testing, you can leave an asterisk *. The other values can be left by default.

Screen after creating a client in Keycloak

Configuring Authorization for Applications

Keycloak can be connected to almost any application: a frontend in React, a backend in Flask, a native desktop, or a mobile app. Keycloak itself implements standard protocols OAuth 2.0 and OpenID Connect, which means the application does not depend on the platform: if it supports authorization via the standard, it can work with Keycloak.

The connection process is always roughly the same. The application redirects the user to Keycloak. It requests their login and password and returns a code. The application exchanges the code for a token and starts working with it. From that moment, the user is considered authorized. You can check their rights, roles, and accesses.

On the Keycloak side, the application is set up as a client, for which authorization scenarios and access restrictions are defined in the interface. All these settings depend on the type of application and its capabilities. For example, if the user is writing a regular website, the standard flow will be enough. And if you want to authorize an IoT device, most likely, you will need to use the client credentials flow without user participation.

Here's an example of configuring environment variables in the .env file for connecting to Keycloak. In your case, you would enter the IP address or domain of your server instead of the one shown there, and change the realm to the one you created.

# Keycloak configuration
KEYCLOAK_URL=http://166.1.227.100:8080
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=test-client
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=admin

# Server configuration 
PORT=3000
SERVER_URL=http://166.1.227.100:3000
SESSION_SECRET=your-session-secret-change-this

# Application URLs (must match Keycloak client configuration)
APP_URL=http://166.1.227.100:3000
VALID_REDIRECT_URIS=http://166.1.227.100:3000/*,http://166.1.227.100:3000/oauth2/callback/*

Integration with External Services

Keycloak can be used not only for your own projects but also for logging into third-party services—for example, GitLab, Jenkins, or Grafana. This is especially convenient if you want to implement single sign-on (SSO) for the team. Documentation for integrating any service with Keycloak can be found publicly.

As an example, let’s look at setting up authorization through Keycloak for GitLab. For this, you will need docker-compose and basic configuration in the control panel.

Note that in this case, external services require the mandatory presence of an SSL certificate so that Keycloak can ensure secure login. For this, you will need your own domain. Here, it will be convenient to create two additional subdomains, for GitLab and for Keycloak, respectively.

If GitLab is already installed, you can add the settings manually. But it’s simpler to deploy everything together right away. Below is an example docker-compose.yml that launches Keycloak and GitLab, already configured to work with each other. Don’t forget to put your domain instead of example.com.

version: "3.9"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    restart: unless-stopped
    networks:
      - app-network

  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    hostname: gitlab.example.com
    volumes:
      - gitlab-config:/etc/gitlab
      - gitlab-logs:/var/log/gitlab
      - gitlab-data:/var/opt/gitlab
    restart: unless-stopped
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        nginx['listen_https'] = false
        nginx['listen_port'] = 80
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
        gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']
        gitlab_rails['omniauth_block_auto_created_users'] = false
        gitlab_rails['omniauth_providers'] = [
          {
            name: "openid_connect",
            label: "Keycloak",
            args: {
              name: "openid_connect",
              scope: ["openid", "profile", "email"],
              response_type: "code",
              issuer: "https://keycloak.example.com/realms/master",
              discovery: true,
              client_auth_method: "query",
              uid_field: "preferred_username",
              client_options: {
                identifier: "gitlab",
                secret: "secret",
                redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
              }
            }
          }
        ]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gitlab.rule=Host(`gitlab.example.com`)"
      - "traefik.http.routers.gitlab.entrypoints=websecure"
      - "traefik.http.routers.gitlab.tls.certresolver=letsencrypt"
      - "traefik.http.services.gitlab.loadbalancer.server.port=80"
    networks:
      - app-network

  keycloak:
    image: quay.io/keycloak/keycloak:26.3.2
    container_name: keycloak
    command: start-dev
    environment:
      KC_HOSTNAME: https://keycloak.example.com
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME_HTTPS: true
      KC_PROXY: edge
      KC_HTTP_ENABLED: true
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.keycloak.rule=Host(`keycloak.example.com`)"
      - "traefik.http.routers.keycloak.entrypoints=websecure"
      - "traefik.http.routers.keycloak.tls.certresolver=letsencrypt"
      - "traefik.http.services.keycloak.loadbalancer.server.port=8080"
    networks:
      - app-network

volumes:
  gitlab-config:
  gitlab-logs:
  gitlab-data:

networks:
  app-network:
    driver: bridge

In the project, Traefik is used as a reverse proxy. It will automatically issue free Let’s Encrypt SSL certificates for the subdomains.

Launch the project:

docker compose up -d

In the Keycloak admin panel, create a client gitlab, where you specify:

• Root URL — the GitLab domain with the https protocol. For example, https://gitlab.example.com.
• Valid redirect URIs — the GitLab domain with the https protocol and all possible paths under this domain. For example, https://gitlab.example.com/*.

The default realm is master. If desired, you can create a separate realm. Users for GitLab and other services are created manually through the Keycloak admin panel.

After loading GitLab, go to the login page at the domain belonging to GitLab. The service will offer to log in via Keycloak:

GitLab login screen with an available option to log in via Keycloak

After successful authorization via Keycloak, the editing panel of the new user created after authorization will open.

GitLab new user settings window after authorization via Keycloak

Troubleshooting Common Issues

Sometimes errors occur when deploying and configuring Keycloak, both in the panel itself and during integration with other services. Below we’ve collected common symptoms, causes, and solutions so you can quickly fix the problem and continue setup.

Conclusion

If you are creating a web application and want to quickly launch authorization, Keycloak becomes an excellent solution. It eliminates routine tasks: logins, roles, sessions, social networks, access rights—everything is available right away.

We covered how to deploy Keycloak on a server, configure the basic panel, connect React and Express applications, and integrate a third-party service like GitLab. This is a universal approach: once you configure Keycloak, you can add new services to it in just minutes and manage access from a single panel.

This approach saves time, simplifies maintenance, reduces risks, and makes the system more secure. And most importantly, you no longer waste effort reinventing your own authorization.