From Keycloak to Kanidm

Or, "Why I should just move my server to NixOS".

Update 2023-09-05

Since originally writing this post, Kanidm now provides arm64 images for kanidm/server again, and I switched my setup over to using those, however I forgot to update this post, so parts about building my own image are now unneccessary.

Any outdated sections are also marked below.

Kanidm is The Hot New Thing (alright, its not actually that new, and it's still technically in alpha, but still), and I wanted to replace my resource-heavy Keycloak server with it, to hopefully free up my server for more important tasks.

Docker makes things 'easy'

Kanidm provides prebuilt docker images for the server, and this was fairly easy to get running:

kanidm:
  docker_container.running:
    - name: kanidm-main
    - image: kanidm/server:latest
    - restart_policy: on-failure:5
    - binds:
      - /mnt/data/services/kanidm:/data
      - /etc/letsencrypt:/certs:ro
    - port_bindings:
      - 8443:8443
      - 3636:3636

All I had to do was make a configuration file like so (lots of stuff from the default config generator skipped):

# Address to bind the HTTPS server
bindaddress = "[::]:8443"
# Address to bind the LDAPS server
ldapbindaddress = "[::]:3636"
# I use nginx as a reverse proxy, and set this header accordingly
trust_x_forward_for = true
# Default for the docker setup
db_path = "/data/kanidm.db"
# Managed my certbot on the host
tls_chain = "/certs/live/ashhhleyyy.dev/fullchain.pem"
tls_key = "/certs/live/ashhhleyyy.dev/privkey.pem"
# Lots of logging
log_level = "verbose"

domain = "sso.ashhhleyyy.dev"
origin = "https://sso.ashhhleyyy.dev"

However, due to weird issues with the container builds, the latest tag isn't the most recent version, and the x86_64_latest is only compatible with x86_64 CPUs, but my Raspberry Pi 4 has an arm64 CPU. This means I have to use the slightly-outdated latest tag (this will cause issues later).

Update 2023-09-05: Kanidm have since fixed their Docker publishing, and the latest tag is now the latest version, and compatible with arm64.

Setting up a user

Kanidm comes with two pre-created users for managing an instance: admin and idm_admin. The admin account is meant for general administrative tasks, such as management of oauth2 clients and other global configuration, but does not have permissions to manage people, while the idm_admin does not have general administrative permissions, but is able to manage people's accounts.

To start using the server, the first thing required is to stop the server container (this is because resetting the admin account password requires exclusive database access). The following command will then reset the password to allow us to log in:

$ docker run --rm -i -t -v <PATH TO DATA VOLUME>:/data \ <YOUR IMAGE NAME> /sbin/kanidmd recover_account -c /data/server.toml admin
success - recover_account password for user admin: [REDACTED]

Configuring some clients

Next up is to configure all my existing things to use Kanidm, which is a bit of a repetitive task, although I prefer the copy-paste command line configuration for Kanidm over Keycloak's web-based admin portal.

First up, I have Vouch set up to secure certain pages only I should be able to access, and so first I need to create an oauth2 app for it:

$ kanidm login --name admin
Enter password:
Login Success for admin

$ kanidm system oauth2 create vouch "Internal Services" https://vouch.ashhhleyyy.dev
Success

$ kanidm system oauth2 show_basic_secret vouch
[REDACTED]

Cool! Now I can update the configuration for Vouch and restart the service:

# previous sections skipped

oauth:
  provider: oidc

  # kanidm
  client_id: vouch
  client_secret: <REDACTED>
  auth_url: "https://sso.ashhhleyyy.dev/ui/oauth2"
  token_url: "https://sso.ashhhleyyy.dev/oauth2/token"
  user_info_url: "https://sso.ashhhleyyy.dev/oauth2/openid/vouch/userinfo"

  code_challenge_method: S256

  scopes:
    - email
  callback_url: https://vouch.ashhhleyyy.dev/auth

$ docker restart vouch-main
vouch-main
$ 

Aaand done! Let's try it out...

Wait...

It doesn't work :/

The scope of the issue

Kanidm has a feature called "scope maps", which controls which users/clients are able to request certain scopes when logging in. For OpenID Connect, a scope named openid MUST be requested, along with additional scopes which control what user information is included in the provided token, such as profile, email or address.

Vouch only needs the openid and email scopes to function, so we just need to create a scope mapping which grants those:

$ kanidm system oauth2 update-scope-map gitea idm_all_persons openid email
Success

...

Woo!

This should be enough to allow any user (idm_all_persons) to authenticate with Vouch, which should be enough for a single-user setup where the goal is simply to unify login. However, we need to make some changes if we'd like to create accounts for other people and control what they have access to...

Groups, groups, groups!

We've already used a group in the previous part, idm_all_persons, which automatically includes all "person" accounts (which are different to service accounts like admin and idm_admin), but we can also create our own and assign users to them.

First, lets create a group for users which should be able to access Vouch-protected resources:

$ kanidm group create vouch-access
Successfully created group 'vouch-access'

Now, lets add a user to the new group (change ash for whatever your username is)

$ kanidm group add_members vouch-access ash
Successfully added ["ash"] to group "vouch-access"

Finally, we need to remove the old scope map, and create a new one:

$ kanidm system oauth2 delete_scope_map vouch idm_all_persons
Success

$ kanidm system oauth2 update-scope-map vouch vouch-access openid email
Success

Now this still works for my main account, ash, but I get an "Access denied" error if I try using ash2, who is not a member of the vouch-access group:

This technique of using groups to control access to different services is something that I couldn't easily figure out how to do with Keycloak, and so its great that this is such an obvious feature in Kanidm!

Migrating some other services

I use Grafana for making pretty graphs of things, and moving it over to use Kanidm was basically the same as with Vouch - create an oauth2 application, add a group, and update the Grafana configuration file:

[auth.generic_oauth]
enabled = true
name = Kanidm
client_id = grafana
client_secret = [REDACTED]
scopes = openid email profile
login_attribute_path = prefered_username
auth_url = https://sso.ashhhleyyy.dev/ui/oauth2
token_url = https://sso.ashhhleyyy.dev/oauth2/token
api_url = https://sso.ashhhleyyy.dev/oauth2/openid/grafana/userinfo

Other services, however, did not want to play as nicely with Kanidm...

Git-eAAAAA

My Forgejo instance was the next thing I wanted to move over to Kanidm, and so I started out the same way as before, but quickly hit a roadblock: usernames.

Uhhh.

2023/02/06 12:26:51 ...ers/web/auth/auth.go:570:createUserInContext() [E] [63e0f20a] CreateUser: name is invalid [[email protected]]: must be valid alpha or numeric or dash(-_) or dot characters

Ah.

After a bit of digging, I realised Kanidm can be configured per-oauth2 client to prefer either an "SPN" or just the short username in the prefered_username field of the token, and so a quick

$ kanidm system oauth2 prefer-short-username forgejo
Success

later, and everything should be working now.

Hmmmmmmmmm

Eventually, after a lot of digging, I figured out what the issue was:

In Kanidm v1.1.0-alpha.10, when prefer-short-username was added, the implementation did not take into account the OpenID Connect userinfo endpoint, which is used by many implementations to fetch the full details about the authenticated user.

Correction (2023-09-05)

At some point Kanidm fixed this issue, and the latest tag on Docker hub is now compatible with arm64 again.

The section below is outdated and no longer required.

diff --git a/kanidmd/Dockerfile b/kanidmd/Dockerfile
index 0f0125a7f..17feefe2c 100644
--- a/kanidmd/Dockerfile
+++ b/kanidmd/Dockerfile
@@ -1,6 +1,7 @@
 ARG BASE_IMAGE=opensuse/tumbleweed:latest
 FROM ${BASE_IMAGE} AS repos
-RUN zypper refresh --force
+RUN curl -o '/etc/zypp/repos.d/home:dziobian:gulgul-ultron.repo' 'https://download.opensuse.org/repositories/home:/dziobian:/gulgul-ultron/openSUSE_Tumbleweed/home:dziobian:gulgul-ultron.repo'
+RUN zypper --gpg-auto-import-keys refresh --force
 RUN zypper dup -y
 
 # ======================
@@ -17,6 +18,8 @@ RUN zypper install -y \
         rsync \
         findutils \
         which
+RUN zypper install -y --from home_dziobian_gulgul-ultron \
+        binaryen
 RUN zypper clean -a
 RUN rustup default stable
 

$ env IMAGE_BASE=git.ashhhleyyy.dev/ash make buildx/kanidmd buildx/kanidm_tools

Wrapping up

Finally, once I had updated Kanidm, Forgejo basically Just Works™, and I can continue moving services over, all of which worked without any hitch. I've kept my old Keycloak instance running for now, in case I've missed anything that still depends on it, however I've disabled all the clients that I have moved over, and I'm hoping I can stop running the server in the next few weeks and nothing will break :)

Extra update (2023-09-05)

Shortly after writing this post I did in fact stop running the old Keycloak server, and nothing has broken 🎉. Kanidm is now the only SSO app running on my server!