Kanidm

Connect over SSH and confirm the service is healthy. The status endpoint returns true when the server is ready to take requests.

sudo systemctl is-active kanidm-firstboot.service kanidmd.service curl -sk https://127.0.0.1/status echo
sudo kanidmd version

Read the access note, which records everything specific to this machine. It contains no password, because no credential exists anywhere on the server yet.

sudo cat /root/kanidm-credentials.txt

Run this command on the machine, as root or as the service account. It turns a locked server into one you can administer, and it prints a freshly generated random password exactly once.

Use idm_admin for day-to-day administration of people and groups. Recover admin only when you need to change server-level configuration such as the domain name or the LDAP base DN. Keeping the two accounts separate is the reason Kanidm has both.

sudo -u kanidmd kanidmd recover-account idm_admin INFO Running account recovery ... INFO | new_password: "<a fresh 48 character password, shown once>"

Record that password in your password manager now. It is not stored in clear text anywhere on the machine. Running the command again replaces it with a new one.

For an automated deployment, capture the password straight into a sign-in so it is never written to a file. This is the sequence used to verify the image:

PW=$(sudo -u kanidmd kanidmd recover-account idm_admin 2>&1 | sed -n 's/.*new_password: "\(.*\)".*/\1/p')
sudo KANIDM_PASSWORD="$PW" kanidm login -D idm_admin
sudo kanidm self whoami -D idm_admin

The kanidm client on this machine is preconfigured with the server's address and its certificate authority, so you need no --url or --ca flags here.

Recovering one break-glass account does not unlock the other. Until you recover admin, it stays refused.

Browse to https://<your-domain>/. The certificate is issued for the domain name rather than the IP address, so if DNS does not yet point at the machine, add a hosts file entry on your workstation first.

Sign in as idm_admin with the password you just recorded.

Your browser warns about the certificate on the first visit. This is expected. The machine issued its own certificate at first boot, and upstream labels it with the subject OU = Development and Evaluation - NOT FOR PRODUCTION. It lets the server start and lets you connect immediately. Replace it with your own certificate, as described in the section on replacing the TLS certificate. It takes two file copies.

The web interface is where your people manage their own credentials, passkeys and application access. It also has an administration panel for browsing persons and groups.

Administration in Kanidm 1.11 is done with the kanidm command line client, not the web interface. The admin panel lists and inspects persons and groups and lets you edit a group's membership. Creating accounts, setting POSIX attributes, issuing RADIUS secrets and registering OAuth2 clients are command line operations. This is upstream design, not a limitation of this image.

Create an account for a person, add them to a group, and give both POSIX attributes so Unix and LDAP clients can see them.

sudo kanidm person create alice "Alice Baker" -D idm_admin
sudo kanidm person posix set alice --shell /bin/bash -D idm_admin
sudo kanidm group create platform-engineers -D idm_admin
sudo kanidm group add-members platform-engineers alice -D idm_admin
sudo kanidm group posix set platform-engineers -D idm_admin
sudo kanidm person get alice -D idm_admin

Both objects appear immediately in the administration panel. Open the person to see their security principal name, their UUID and every group they belong to. The group's own page lists its members and lets you add and remove them.

To let Alice set her own password and passkeys, generate a credential reset link and send it to her. The link is single-use and time-limited, so you never need to know or transport her password:

sudo kanidm person credential create-reset-token alice -D idm_admin

Applications that only speak LDAP bind to port 636 over TLS. The base DN is derived from your domain name, so idm.example.com becomes dc=idm,dc=example,dc=com. The access note records it for you.

Anonymous search resolves POSIX-enabled people and groups. This is what most LDAP clients need to look up a user and their group membership:

D=$(sudo grep -m1 '^KANIDM_DOMAIN=' /root/kanidm-credentials.txt | cut -d= -f2-)
B=$(sudo grep -m1 '^KANIDM_LDAP_BASEDN=' /root/kanidm-credentials.txt | cut -d= -f2-) sudo LDAPTLS_CACERT=/var/lib/kanidmd/ca.pem \
  ldapsearch -LLL -o ldif-wrap=no -H "ldaps://$D:636" -b "$B" -x '(name=alice)' \
  name spn gidnumber loginshell memberof

Read the base DN with cut -d= -f2- rather than awk -F= '{print $2}'. The value contains equals signs of its own. Taking only the second field silently truncates dc=idm,dc=example,dc=com to dc, and every search then fails with a constraint violation that looks like a server problem.

For an application that needs more than anonymous read access, create a service account and issue it an API token. Bind with the reserved DN dn=token and the token as the password to get that service account's own read permissions:

D=$(sudo grep -m1 '^KANIDM_DOMAIN=' /root/kanidm-credentials.txt | cut -d= -f2-) sudo kanidm service-account create svc-ldap "Directory reader" idm_admin -D idm_admin
TOK=$(sudo kanidm service-account api-token generate svc-ldap readers -D idm_admin | tail -1) sudo LDAPTLS_CACERT=/var/lib/kanidmd/ca.pem \
  ldapwhoami -H "ldaps://$D:636" -x -D 'dn=token' -w "$TOK"

A person can also bind as themselves with a POSIX password, which is what Unix clients do. Set one interactively. The command prompts twice and never accepts the password on the command line, so it cannot end up in your shell history:

sudo kanidm person posix set-password alice -D idm_admin

Two behaviours to expect:

• Writes over LDAP are always refused, because LDAP cannot express Kanidm's data model. Use the REST API or the kanidm client to make changes.
• A failed bind soft-locks the account for a short period, so the next few attempts fail even with the correct password. This is brute-force protection working, not a fault.

If you have no LDAP applications, you can turn the POSIX password bind off and leave only token binds:

sudo kanidm system domain set-ldap-allow-unix-password-bind false -D admin

For applications that support modern federation, register them as OAuth2 clients instead of pointing them at LDAP. Kanidm is the provider, and you need no extra component.

sudo kanidm system oauth2 create grafana "Grafana" https://grafana.example.com -D idm_admin
sudo kanidm system oauth2 update-scope-map grafana platform-engineers openid profile email -D idm_admin
sudo kanidm system oauth2 show-basic-secret grafana -D idm_admin
sudo kanidm system oauth2 list -D idm_admin

The discovery document your application needs is published at https://<your-domain>/oauth2/openid/grafana/.well-known/openid-configuration. Only members of the groups you grant a scope map to can sign in, so access control lives in the directory instead of in each application.

Kanidm holds the per-account RADIUS secret and serves it to a FreeRADIUS instance running upstream's rlm_kanidm module. The RADIUS daemon is a separate deployment and is not installed on this image. This machine is the authority that issues and stores the secrets.

sudo kanidm person radius generate-secret alice -D idm_admin
sudo kanidm group create radius_access_allowed -D idm_admin
sudo kanidm group add-members radius_access_allowed alice -D idm_admin

For Unix login, the POSIX attributes you set in step 4 are consumed by kanidm-unixd, libnss-kanidm and libpam-kanidm. Install them on the client machines that people log in to. They are not installed on this appliance, because a third-party NSS and PAM module in the authentication path of the machine that holds your only recovery command could lock you out of it.