Installing Keycloak on Kubernetes

Keycloak is a widely used open source identity and access management system. Think Okta but open source. This is where users will actually enter their username and password for services and where we'll configure which users can login to which applications. It will also provide users with a single directory of applications they can login to.

In this post - as part of the larger series on Kubernetes SSO - we cover how to install Keycloak on Kubernetes.

Pre-requisites

This assumes you have CLI access to a Kubernetes cluster, will be working in a namespace called identity and have both Helm 3 and Kubectl installed and working locally. Finally it assumes that you're using NGINX for Ingress along with cert manager for SSL certificates with a Cluster Issuer called letsencrypt-production.

If your configuration is different, the majority of the steps will be the same, but you'll need to change the ingress annotations accordingly.

The source for this series of tutorials can be found here: https://github.com/TalkingQuickly/kubernetes-sso-guide and cloned with:

git clone [email protected]:TalkingQuickly/kubernetes-sso-guide.git

All commands in the tutorial assume that they're being executed from the root of this cloned repository.

Install Keycloak

Helm 3 is migrating charts out of it's centrally managed repository and into decentralised ones, so to access the Keycloak Chart we'll need to add the relevant repository.

helm repo add codecentric https://codecentric.github.io/helm-charts

We can see details of the chart itself here.

For a basic configuration, we need to configure Ingress and enable Postgres as the data store.

This assumes you're working on a cluster with support for Ingress and Persistent Volumes. In this case I have a wildcard DNS record for *.ssotest.staging.talkingquickly.co.uk which points at my test cluster. So our initial values file keycloak/values-keycloak looks something like:

extraEnv: |
  - name: KEYCLOAK_LOGLEVEL
    value: DEBUG
  - name: KEYCLOAK_USER
    value: admin
  - name: KEYCLOAK_PASSWORD
    value: as897gsdfs766dfsgjhsdf
  - name: PROXY_ADDRESS_FORWARDING
    value: "true"

ingress:
  enabled: true
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-production
  rules:
    - host: sso.ssotest.staging.talkingquickly.co.uk
      paths:
        - /
args:
  - -Dkeycloak.profile.feature.docker=enabled

  tls:
  - hosts:
    - sso.ssotest.staging.talkingquickly.co.uk
    secretName: keycloak-tld-secret

postgresql:
  enabled: true
  postgresqlPassword: asdfaso97sadfjylfasdsf78

We can then install it with:

helm upgrade --install keycloak codecentric/keycloak --values keycloak/values-keycloak.yml

We've set the initial username and password of the keycloak user in the environment variables KEYCLOAK_USER and KEYCLOAK_PASSWORD in our values-keycloak.yml, well need these to login to the administrative console.

We can then go to whichever URL we've selected for Ingress, in my case this was https://sso.ssotest.staging.talkingquickly.co.uk.

And can then choose to login to the administrative console. From here we can create users and "client" apps that we'll use for configuring other applications with Keycloak SSO.

Note that logging into the administrative console is separate to logging in as a Keycloak service user.

Within Keycloak we can create multiple "realms" which are essentially standalone auth services. For example we might have one realm for internal systems and one real for customers. The default realm is called "master" and so using my ingress URL, users would login to this realm at https://sso.ssotest.staging.talkingquickly.co.uk/auth/realms/master/account. Visiting https://sso.ssotest.staging.talkingquickly.co.uk/auth/realms/master would give some useful information about the realm.

A common source of confusion is attempting to test logins using administrative credentials rather than credentials from a user who has been created in a specific realm. Incognito or Sandboxed browser tabs are useful for this.