NAME
gyptazy - it's all about FreeBSD, Proxmox, BGP and Coding!

OPTIONS

CONTENT

Kanidm OIDC with Proxmox VE – Configuration Guide

():

In this HowTo we install and configure Kanidm on Linux Debian Trixie and use it for authentication with Proxmox by OIDC (OpenID Connect). In previous articles, I’ve already shown another example in how to integrate Proxmox VE with external identity providers such as Authentik and Keycloak, using them as realms to centralize authentication. Both of these solutions are powerful in their own right, but sometimes you might be looking for something that is more lightweight, simple to deploy, and secure by default without sacrificing the features you’d expect from a modern identity management system.

This is where Kanidm comes in. Kanidm is a modern, secure, and easy-to-use identity management platform built with a strong focus on simplicity and security. Its primary goal is to be a complete identity provider, meaning you shouldn’t need to run additional components like Keycloak to cover your use cases. With Kanidm, you already get everything you need in one place.

Some of the standout features of Kanidm include:

In this guide, we’ll walk through installing Kanidm on Debian Trixie, configuring it as an OpenID Connect (OIDC) provider, and integrating it as a realm in Proxmox VE. By the end, Proxmox will be able to authenticate users directly against Kanidm, giving you a streamlined, secure, and future-proof identity management setup.

Installation

Prerequisites

Before we begin setting up Kanidm, it’s important to prepare the right environment. For this guide, we’ll use a dedicated Debian Trixie (or Bookworm) instance, which can be provisioned as either a virtual machine (VM) or a Proxmox LXC container. To ensure smooth operation, the instance should have at least 6 GB of memory, as Kanidm relies on multiple services running in parallel.

In this setup, Kanidm itself will run inside Docker containers, providing isolation and easy lifecycle management. At the same time, we will install the Kanidm client tooling directly on the host system. This approach keeps administration tasks straightforward while still leveraging the benefits of containerized services.

During this setup we will use the following settings:

Installing Kanidm Server & Client Tools

apt-get update
apt-get install ca-certificates curl gpg sudo
...

Configuring Kanidm Server

The Kanidm configuration file defines several critical parameters that directly impact security and functionality. One of the most important values is the domain, which represents the DNS domain name of your server. This setting is used in many security-sensitive contexts such as WebAuthn, and it forms the basis for security principal names.

Important: Changing the domain later will invalidate existing credentials (WebAuthn keys, OAuth tokens, etc.). If it ever becomes necessary to change the domain, you must immediately run kanidmd domain rename.

Additionally, the configuration specifies the origin, which is the URL of your server. This value must be consistent with the domain name you configure above. 

version = "2"
bindaddress = "[::]:8443"
...

Kanidm Client Config

When running the Kanidm client on the same machine, create a config file in ~/.config/kanidm with the following content: 

uri = "https://localhost"
verify_ca = false

Create Users

Once Kanidm is up and running, the next step is to create users and groups. Users can be provisioned through the CLI or WebUI, and it’s recommended to immediately enforce additional security with two-factor authentication (2FA). 

kanidm person create gyptazy "Max Mustermann"
kanidm person credential create-reset-token gyptazy

Create Groups

Groups in Kanidm are a powerful way to organize users and assign permissions collectively. This simplifies access management across integrated services like Proxmox. 

kanidm group create proxmox_group --name idm_admin
kanidm group add-members proxmox_group gyptazy --name idm_admin

Create OAuth2 Resource

Kanidm natively supports OAuth2 authorization extended with OpenID Connect (OIDC). This allows modern applications to fully offload identity management using open standards. 

kanidm system oauth2 create Proxmox "Proxmox Lab Env" https://virt01.lab.gyptazy.com:8006
...

Proxmox - Adding New OIDC Realm

To set up a new OpenID Connect (OIDC) realm in Proxmox via the Web UI, navigate to Datacenter → Permissions → Realms and add a new OpenID Connect realm using the following values: 

Issuer URL: https://idm.lab.gyptazy.com/oauth2/openid/proxmox
Realm: idm.lab.gyptazy.com
Client ID: proxmox
Client Key: FooBar
Autocreate Users: yes
Proxmox Adding Kanidm OIDC Realm

Conclusion

Kanidm proves that identity management can be lightweight and straightforward without sacrificing security or functionality. It integrates cleanly with Proxmox and many other platforms, offering a modern and open alternative to heavier solutions.

If this was interesting, you might also enjoy building modern Proxmox virtualization infrastructures in 2025 or how to configure Authentik with OIDC in Proxmox.