Skip to content

KeyCloak

KeyCloak is "an open source identity and access management solution." Using a local database, or a variety of backends (think OpenLDAP), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML.

Important

Development of this recipe is sponsored by The Common Observatory. Thanks guys!

Common Observatory

KeyCloak Screenshot

Ingredients

  1. Docker swarm cluster with persistent shared storage
  2. Traefik configured per design
  3. DNS entry for the hostname (i.e. "keycloak.your-domain.com") you intend to use for LDAP Account Manager, pointed to your keepalived IP

Preparation

Setup data locations

We'll need several directories to bind-mount into our container for both runtime and backup data, so create them as follows

1
2
mkdir /var/data/runtime/keycloak/database
mkdir /var/data/keycloak/database-dump

Prepare environment

Create /var/data/keycloak/keycloak.env, and populate with the following variables, customized for your own domain structure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Technically, this could be auto-detected, but we prefer to be prescriptive
DB_VENDOR=postgres
DB_DATABASE=keycloak
DB_ADDR=keycloak-db
DB_USER=keycloak
DB_PASSWORD=myuberpassword
KEYCLOAK_USER=admin
KEYCLOAK_PASSWORD=ilovepasswords

# This is required to run keycloak behind traefik
PROXY_ADDRESS_FORWARDING=true

# What's our hostname?
KEYCLOAK_HOSTNAME=keycloak.batcave.com

# Tell Postgress what user/password to create
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=myuberpassword

Create /var/data/keycloak/keycloak-backup.env, and populate with the following, so that your database can be backed up to the filesystem, daily:

1
2
3
4
5
PGHOST=keycloak-db
PGUSER=keycloak
PGPASSWORD=myuberpassword
BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d

Setup Docker Swarm

Create a docker swarm config file in docker-compose syntax (v3), something like this:

Tip

I share (with my patreon patrons) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a git pull and a docker stack deploy 👍

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
version: '3'

services:
  keycloak:
    image: jboss/keycloak
    env_file: /var/data/config/keycloak/keycloak.env
    volumes:
      - /etc/localtime:/etc/localtime:ro    
    networks:
    - traefik_public
    deploy:
      labels:
        - traefik.frontend.rule=Host:keycloak.batcave.com
        - traefik.port=8080
        - traefik.docker.network=traefik_public

  keycloak-db:
    env_file: /var/data/config/keycloak/keycloak.env
    image: postgres:10.1
    volumes:
      - /var/data/runtime/keycloak/database:/var/lib/postgresql/data
      - /etc/localtime:/etc/localtime:ro    
    networks:
    - traefik_public

  keycloak-db-backup:
    image: postgres:10.1
    env_file: /var/data/config/keycloak/keycloak-backup.env
    volumes:
      - /var/data/keycloak/database-dump:/dump
      - /etc/localtime:/etc/localtime:ro
    entrypoint: |
      bash -c 'bash -s <<EOF
      trap "break;exit" SIGHUP SIGINT SIGTERM
      sleep 2m
      while /bin/true; do
        pg_dump -Fc > /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.psql
        (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql)|sort|uniq -u|xargs rm -- {}
        sleep $$BACKUP_FREQUENCY
      done
      EOF'
    networks:
    - traefik_public

networks:
  traefik_public:
    external: true

Warning

Normally, we set unique static subnets for every stack you deploy, and put the non-public facing components (like databases) in an dedicated <stack>_internal network. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See my list here.

However, KeyCloak's JBOSS startup script assumes a single interface, and will crash in a ball of 🔥 if you try to assign multiple interfaces to the container. This means that we can't use a "keycloak_internal" network for our supporting containers. This is why unlike our other recipes, all the supporting services are prefixed with "keycloak-".

Serving

Launch KeyCloak stack

Launch the OpenLDAP stack by running docker stack deploy keycloak -c <path -to-docker-compose.yml>

Log into your new instance at https://YOUR-FQDN, and login with the user/password you defined in keycloak.env.

Integrating into OpenLDAP

KeyCloak gets really sexy when you integrate it into your OpenLDAP stack (also, it's great not to have to play with ugly LDAP tree UIs).

You'll need to have completed the OpenLDAP recipe

You start in the "Master" realm - but mouseover the realm name, to a dropdown box allowing you add an new realm:

KeyCloak Add Realm Screenshot

Enter a name for your new realm, and click "Create":

KeyCloak Add Realm Screenshot

Once in the desired realm, click on User Federation, and click Add Provider. On the next page ("Required Settings"), set the following:

  • Edit Mode : Writeable
  • Vendor : Other
  • Connection URL : ldap://openldap
  • Users DN : ou=People,<your base DN>
  • Authentication Type : simple
  • Bind DN : cn=admin,<your base DN>
  • Bind Credential : <your chosen admin password>

Save your changes, and then navigate back to "User Federation" > Your LDAP name > Mappers:

KeyCloak Add Realm Screenshot

For each of the following mappers, click the name, and set the "Read Only" flag to "Off" (this enables 2-way sync between KeyCloak and OpenLDAP)

  • last name
  • username
  • email
  • first name

KeyCloak Add Realm Screenshot

Important

Development of this recipe is sponsored by The Common Observatory. Thanks guys!

Common Observatory

Chef's Notes

  1. I wanted to be able to add multiple networks to KeyCloak (i.e., a dedicated overlay network for LDAP authentication), but the entrypoint used by the container produces an error when more than one network is configured. This could theoretically be corrected in future, with a PR, but the GitHub repo has no issues enabled, so I wasn't sure where to start.

Tip your waiter (donate) 👏

Did you receive excellent service? Want to make your waiter happy? (..and support development of current and future recipes!) See the support page for (free or paid) ways to say thank you! 👏

Your comments? 💬