In this tutorial, we'll deploy Keycloak on a local Kubernetes cluster (e.g., Docker Desktop or Minikube) using Helm. We will:

1. Spin up Keycloak (and its PostgreSQL database) via a Helm chart.

2. Create a Realm in Keycloak to isolate authentication data.

3. Create a Client to define valid authentication requests.

4. Add a User and assign a Role.

5. Use Postman to get an access token, refresh it, and log out from Keycloak.

Note: While our focus is on a local cluster (NodePort service type), you can easily adapt this for a production environment with a LoadBalancer or Ingress Controller.

Prerequisites

• Kubernetes cluster running locally (e.g., Docker Desktop, Minikube) or on the cloud.

• Helm installed locally. For installation instructions, see Install Helm on Mac and Windows.

• Basic knowledge of kubectl commands.

• (Optional) Postman for sending authentication requests.

Cloning the Starter Code

A GitHub repository contains all necessary YAML files and Postman collections:

git clone <https://github.com/rslim087a/keycloak-authentication-tutorial-helm-kubernetes.git>
cd

Inside, you’ll see:

• Helm folder or helm-values.yaml (the values file for the Keycloak chart).

• A Postman collection file, which you can import into Postman.

• Other resource links (like how to set up Docker Desktop for Kubernetes, etc.).

Helm Chart and Values File

The values.yaml Explained

Below is the core content of helm-values.yaml (already included in the repository). It configures both Keycloak and PostgreSQL under one chart:

# Global PostgreSQL settings
global:
  postgresql:
    auth:
      username: bn_keycloak
      password: bn_keycloak
      database: bitnami_keycloak

# Keycloak Admin User Configuration
auth:
  adminUser: admin
  adminPassword: admin

# PostgreSQL Specific Configuration
postgresql:
  enabled: true
  auth:
    username: bn_keycloak
    password: bn_keycloak
    database: bitnami_keycloak

# Kubernetes Service Configuration
service:
  type: NodePort
  nodePorts:
    http: 30080

# Additional Keycloak Environment Variables
extraEnvVars:
  - name: KC_PRODUCTION
    value: "true"
  - name: KC_HOSTNAME_STRICT
    value: "false"
  - name: KC_HTTP_ENABLED
    value: "true"
  - name: VERTX_WORKER_POOL_SIZE
    value: "20"
  - name: VERTX_EVENT_LOOP_POOL_SIZE
    value: "8"

Key Points:

1. PostgreSQL is enabled and set to store Keycloak data (bn_keycloak user, bn_keycloak password, bitnami_keycloak DB).

2. We use NodePort (30080) so Keycloak is accessible via http://localhost:30080 on a single-node cluster.

3. The Keycloak admin user/password is admin / admin by default.

4. Additional environment variables override certain defaults (HTTP enabled, hostname strict disabled, etc.).

Production Considerations: For a real environment, you might switch service.type to LoadBalancer or manage Keycloak behind an Ingress Controller with TLS.

Installing Keycloak on Kubernetes

Adding the Bitnami Helm Repo

Bitnami hosts the Keycloak Helm chart:

Deploying Keycloak with Helm

Use the provided helm-values.yaml to install Keycloak:

helm install keycloak bitnami/keycloak \\
  --version 24.4.2 \\
  --namespace keycloak \\
  --create-namespace \\
  --values

Notes:

• -version 24.4.2 ensures we use a specific version for consistency.

• -namespace keycloak --create-namespace creates a new namespace named keycloak and deploys Keycloak there.

Check pods and services:

kubectl get pods -n keycloak
kubectl get svc -n

You should see one or more Keycloak pods and a PostgreSQL pod, plus a Service (type NodePort) mapping Keycloak’s port 8080 to 30080 on your host.

Accessing the Keycloak Admin Console

Once Keycloak finishes starting (it may take a few minutes and pod restarts initially), open a browser and go to:

<http://localhost:30080>

• Click “Administration Console.”

• Log in with:

  • Username: admin

  • Password: admin

You’ll enter the Keycloak Admin Console, where you can configure realms, clients, roles, and users.

Creating a Realm

A Realm is an isolated authentication domain. Each realm has its own users, roles, and clients.

1. In the top-left dropdown (where it says Master), click “Create Realm.”

2. Name your realm, e.g., test-realm.

3. Click “Create.”

Everything we do next (users, clients, roles) is scoped to this test-realm.

Creating a Client

Clients represent applications or services that request authentication from Keycloak.

1. Under “Clients” (left menu), click “Create Client.”

2. For Client ID, enter test-client.

3. Enable Client Authentication, so Keycloak issues a client secret.

4. Add some valid Redirect URIs (e.g., http://localhost/*) even if you don’t fully use them for direct grant type.

5. Click “Save.”

Under “Credentials” for this client, you’ll find the generated client secret, needed for token requests.

Defining a User and Realm Role

Create a Role

1. Under “Realm Roles,” click “Create Role.”

2. Call it api-access. (This role could represent permission to call certain APIs.)

Create a User

1. Navigate to “Users” → “Add User.”

2. For Username, type test-user, and click “Save.”

3. (Optional) Add an email or first name.

4. Under “Credentials,” set a password (e.g., test-password).

   • Uncheck “Temporary” if you don’t want the user to reset next login.

5. Click “Role Mappings.”

   • Assign the api-access role to test-user.

Now, test-user has credentials and a role granting them access to potential protected endpoints.

Testing Authentication with Postman

We can confirm the authentication flow using the Keycloak OpenID Connect endpoints. Import the Postman collection provided in the repo:

1. In Postman, click “Import.”

2. Select the Keycloak_Auth_Flow - Kubernetes.json or similar file from the repository.

3. You’ll see four requests:

   • Get Access Token (Password Grant)

   • Refresh Token

   • User Info

   • Logout

Obtaining an Access Token

Open “1. Get Access Token (Password Grant)”:

• client_id: test-client

• client_secret: (from Keycloak → test-client → “Credentials”)

• grant_type: password

• username: test-user

• password: test-password

• URL: http://localhost:30080/realms/test-realm/protocol/openid-connect/token

Click “Send.” If successful, you’ll see:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....",
  "refresh_token": "eyJhbGc....",
  "expires_in": 300,
  "token_type": "Bearer",
  ...
}

Accessing a Protected Resource

Keycloak offers a built-in protected endpoint: userinfo.

1. Copy the "access_token".

2. Open “3. User Info.”

3. Under Headers, set Authorization: Bearer <access_token>.

4. Send.

If authentication succeeds, you’ll get back user details (username, email, roles, etc.).

Refreshing the Token

Refresh tokens allow you to obtain a new access_token without re-entering user credentials:

1. Open “2. Refresh Token.”

2. Supply the same client_id, client_secret, but set grant_type to refresh_token.

3. Provide "refresh_token" from your previous step.

4. Click “Send.”

You’ll receive a fresh access token in the response.

Logging Out

To invalidate the refresh token and session:

1. Open “4. Logout.”

2. Provide client_id, client_secret, and the current refresh_token.

3. Click “Send.”

If successful, Keycloak returns 204 No Content, ending the user session.

Cleaning Up

When finished, you can remove all Keycloak resources from your cluster:

helm uninstall keycloak --namespace

Optionally remove the namespace:

Also, if you want to free up space, remove any unused images:

docker system prune -a

Video Chapters

• 00:00:00 – 00:01:40 What to Expect: Keycloak Auth on Kubernetes w/ Helm

• 00:01:40 – 00:04:50 Download Helm Starter Code

• 00:04:50 – 00:06:18 Keycloak Bitnami Helm Chart

• 00:06:18 – 00:08:51 Install Keycloak Helm Chart on Kubernetes

• 00:08:51 – 00:09:40 Keycloak Admin Console

• 00:09:40 – 00:10:24 Create Keycloak Realm

• 00:10:24 – 00:13:24 Create Keycloak Client

• 00:13:24 – 00:15:22 Create Realm Role for Keycloak User

• 00:15:22 – 00:16:20 Import Postman Collection

• 00:16:20 – 00:18:08 Keycloak Access Token

• 00:18:08 – 00:19:04 Access Protected Resource

• 00:19:04 – 00:20:04 Keycloak Refresh Token

• 00:20:04 – end Keycloak Logout & Cleaning Up

Additional Resources

• GitHub Repository (Tutorial Code):Keycloak Authentication Tutorial (Helm Kubernetes)

• Setting Up a Kubernetes Cluster with Docker Desktop:Kubernetes Cluster Setup

• Install Helm (Mac/Windows):Install Helm

• Postman Download:Download Postman

• Kubernetes Training Course:Kubernetes Full Course: https://kubernetestraining.io/

Conclusion

Congratulations! You have successfully:

1. Deployed Keycloak on Kubernetes using the Bitnami Helm Chart.

2. Created a Realm, Client, and a User with a Role.

3. Demonstrated the token-based authentication flow via Postman—access tokens, refresh tokens, and logout functionality.

This setup is perfect for local testing or proof-of-concept work. With a few tweaks (switching to a LoadBalancer or adding TLS), you can move the same approach to production clusters. If you found this helpful, consider exploring more DevOps and Kubernetes content and be sure to check out the full YouTube tutorial for a hands-on walkthrough.

Kubernetes Training

If you find these guides helpful, check out our Kubernetes Training course