/ Keycloak


Setting Up Keycloak with Docker: A Step-by-Step Guide

Keycloak is a popular open-source identity and access management solution that supports Single Sign-On (SSO), OAuth 2.0, OpenID Connect, and SAML 2.0. It's ideal for securing web applications, APIs, and microservices. In this guide, we will walk you through the process of setting up Keycloak version 23 using Docker.

Prerequisites

Before starting, ensure you have the following installed on your machine:

  1. Docker - Download and install Docker from docker.com if you don't have it already.
  2. Docker Compose (optional) - While not necessary, Docker Compose makes it easier to manage multi-container applications.

Step 1: Pull the Keycloak Docker Image

Keycloak has an official Docker image, making the setup process straightforward. To begin, open your terminal and run the following command to pull the Keycloak 23 Docker image:

docker pull quay.io/keycloak/keycloak:23.0.0

This will download the Keycloak version 23 image from the Quay.io container registry.

Step 2: Run the Keycloak Container

To start Keycloak, we can use Docker’s docker run command. However, with Keycloak 17 and later versions, the server now runs in "quarkus mode," so we need to pass appropriate environment variables for configuration.

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:23.0.0 \
  start-dev

Breakdown of the Command:

  • -d: Runs the container in detached mode.
  • --name keycloak: Names the container "keycloak."
  • -p 8080:8080: Maps port 8080 on the host to port 8080 in the container (default Keycloak port).
  • -e KEYCLOAK_ADMIN=admin: Environment variable to set the Keycloak admin username.
  • -e KEYCLOAK_ADMIN_PASSWORD=admin: Environment variable to set the Keycloak admin password.
  • quay.io/keycloak/keycloak:23.0.0: The Keycloak 23 Docker image.
  • start-dev: Starts Keycloak in development mode, which is recommended for initial setup and testing.

Alternative: Run Keycloak with Docker Compose

If you prefer to use Docker Compose, create a docker-compose.yml file with the following content:

version: '3'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:23.0.0
    container_name: keycloak
    ports:
      - 8080:8080
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    command:
      - start-dev

Then, in your terminal, navigate to the directory containing this file and run:

docker-compose up -d

Step 3: Access the Keycloak Admin Console

After running the container, Keycloak will be accessible at http://localhost:8080. To verify that everything is working, follow these steps:

  1. Open your browser and navigate to http://localhost:8080.
  2. Click on the Administration Console.
  3. You will be prompted to log in. Use the credentials you set earlier (in our case, admin as both username and password).

Once logged in, you’ll have access to the Keycloak Admin Console, where you can create realms, users, clients, roles, and configure various identity and access management settings.

Step 4: Persistent Data Storage (Optional)

By default, Docker containers do not persist data once they are stopped or removed. If you need to persist Keycloak data (for example, realm configurations), you'll need to use Docker volumes.

Create a Volume for Keycloak Data:

docker volume create keycloak_data

Modify the docker run Command:

Update the docker run command to include the volume mount:

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v keycloak_data:/opt/keycloak/data \
  quay.io/keycloak/keycloak:23.0.0 \
  start-dev

In the above command, -v keycloak_data:/opt/keycloak/data mounts the volume to the directory where Keycloak stores its data.

Modify docker-compose.yml (If using Docker Compose):

version: '3'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:23.0.0
    container_name: keycloak
    ports:
      - 8080:8080
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    volumes:
      - keycloak_data:/opt/keycloak/data
    command:
      - start-dev

volumes:
  keycloak_data:

Run docker-compose up -d again to persist the Keycloak data.

Step 5: Configure Keycloak (Optional)

Now that your Keycloak instance is running, you can start configuring it according to your needs:

  1. Create a Realm: Realms allow you to manage a set of users, roles, and clients. By default, Keycloak comes with a master realm, but you can create additional realms for specific applications or services.
  2. Create Users: Users can be created and managed within a realm. You can set attributes like email, roles, and credentials for each user.
  3. Add Clients: Clients represent applications that interact with Keycloak for authentication. You can configure different protocols (OAuth 2.0, SAML) for each client.
  4. Define Roles: Roles can be assigned to users or groups to control access to various resources.

Step 6: Stopping and Restarting the Container

To stop the Keycloak container, run:

docker stop keycloak

To start it again, run:

docker start keycloak

If you used Docker Compose, you can manage the container with:

docker-compose down   # To stop and remove the container
docker-compose up -d  # To start it again

Conclusion

Setting up Keycloak 23 using Docker is a quick and efficient way to manage identity and access for your applications. By following the steps outlined in this guide, you can have a fully operational Keycloak instance up and running in minutes. Docker's containerization makes it easy to deploy and scale Keycloak across different environments, whether you're working locally or in production.

Now that your Keycloak instance is set up, we are going in the next post look into how we can develop on Keycloak and add our own custom functionality!