Authentication and Credentials

A primary job of a system like Kanidm is to manage credentials for persons. This can involve a range of operations from new user onboarding, credential resets, and self service.

Types of Credentials

Passkeys

This is the preferred method of authentication in Kanidm. Passkeys represent "all possible cryptographic" authenticators that support Webauthn. Examples of this include Yubikeys, TouchID, Windows Hello, TPM's and more.

These devices are unphishable, self contained multifactor authenticators and are considered the most secure method of authentication in Kanidm.

Attested Passkeys

These are the same as Passkeys, except that the device must present a cryptographic certificate or origin during registration. This allows account policy to be defined to only allow the use of certain models of authenticator. In general only FIDO2 keys or TPM's are capable of meeting attestation requirements.

Password + TOTP

This is a classic Time-based One Time Password combined with a password. Different to other systems Kanidm will prompt for the TOTP first before the password. This is to prevent drive by bruteforce against the password of the account and testing if the password is vulnerable.

While this authentication method is mostly secure, we do not advise it for high security environments due to the fact it is still possible to perform realtime phishing attacks.

Resetting Person Account Credentials

Members of the groups idm_people_admins, idm_people_on_boarding and idm_service_desk have the rights to initiate a credential reset for a person.

NOTE: If the person is a member of idm_high_privilege then these resets are not allowed. This is to prevent idm_service_desk and similar roles from privilege escalation by resetting the credentials of a higher privileged account. If a person who is a member of idm_high_privilege requires a credential reset, this must be initiated by a member of idm_people_admins.

Onboarding a New Person / Resetting Credentials

These processes are very similar. You can send a credential reset link to a user so that they can directly enroll their own credentials. To generate this link or qrcode:

kanidm person credential create-reset-token <account_id> [<time to live in seconds>]
kanidm person credential create-reset-token demo_user --name idm_admin
kanidm person credential create-reset-token demo_user 86400 --name idm_admin
# The person can use one of the following to allow the credential reset
#
# Scan this QR Code:
#
# █████████████████████████████████████████████
# █████████████████████████████████████████████
# ████ ▄▄▄▄▄ █▄██ ▀▀▀▄▀▀█ ▄▀▀▀▀▄▀▀▄█ ▄▄▄▄▄ ████
# ████ █   █ █▀   ▄▄▄▀█  █▀ ██ ▀ ▀▄█ █   █ ████
# ████ █▄▄▄█ █ █▄█  ▀   ▄███▄ ▀▄▀▄ █ █▄▄▄█ ████
# ████▄▄▄▄▄▄▄█ █▄▀▄█▄█ █▄▀▄▀▄█▄█ █▄█▄▄▄▄▄▄▄████
# ████ ▀█▀ ▀▄▄▄ ▄▄▄▄▄▄▄█▀ ▄█▀█▀  ▄▀ ▄   █▀▄████
# ████▄ █ ▀ ▄█▀█ ▀█   ▀█▄ ▀█▀ ▄█▄ █▀▄▀██▄▀█████
# ████ ▀▀▀█▀▄██▄▀█ ▄▀█▄▄█▀▄▀▀▀▀▀▄▀▀▄▄▄▀ ▄▄ ████
# ████ █▄▀ ▄▄ ▄▀▀ ▀ █▄█ ▀▀ █▀▄▄█▄   ▀  ▄ ▀▀████
# ████ █▀▄ █▄▄  █ █▀▀█▀█▄ ▀█▄█▄█▀▄▄ ▀▀ ▄▄ ▄████
# █████ ▀█▄▀▄▄▀▀ ██▀▀█▄█▄█▄█ █▀▄█ ▄█  ▄▄▀▀█████
# ████▄▄▀  ▄▄ ▀▀▄▀▀ ▄▄█ ▄ █▄ ▄▄ ▀▀▀▄▄ ▀▄▄██████
# ████▄▄▀ ▀▀▄▀▄  ▀▀▀▀█▀█▄▀▀ ▄▄▄ ▄ ▄█▀  ▄ ▄ ████
# ████▀▄  ▀▄▄█▀█▀▄ ▄██▄█▀ ▄█▀█ ▀▄ ███▄█ ▄█▄████
# ██████ ▀▄█▄██▀ ▀█▄▀ ▀▀▄ ▀▀█ ██▀█▄▄▀██  ▀▀████
# ████▄▄██▄▄▄▄  ▀▄██▀█ ███▀ ██▄▀▀█ ▄▄▄ ███ ████
# ████ ▄▄▄▄▄ █▄ ▄▄  ▀█▀ ▀▀ █▀▄▄▄▄█ █▄█ ▀▀ ▀████
# ████ █   █ █▄█▄▀  ██▀█▄ ▀█▄▀▄ ▀▀▄   ▄▄▄▀ ████
# ████ █▄▄▄█ ██▀█ ▀▄▀█▄█▄█▄▀▀▄▄ ▀ ▄▄▄█▀█  █████
# ████▄▄▄▄▄▄▄█▄█▄▄▄▄▄▄█▄█▄██▄█▄▄▄█▄██▄███▄▄████
# █████████████████████████████████████████████
# ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
#
# This link: https://localhost:8443/ui/reset?token=8qDRG-AE1qC-zjjAT-0Fkd6
# Or run this command: kanidm person credential use-reset-token 8qDRG-AE1qC-zjjAT-0Fkd6

If the user wishes you can direct them to https://idm.mydomain.name/ui/reset where they can manually enter their token value.

Once the credential reset has been committed the token is immediately invalidated and can never be used again. By default the token is valid for 1 hour. You can request a longer token validity time when creating the token. Tokens are only allowed to be valid for a maximum of 24 hours.

Resetting Credentials Directly

You can perform a password reset on the demo_user, for example, as the idm_admin user, who is a default member of this group. The lines below prefixed with # are the interactive credential update interface. This allows the user to directly manage the credentials of another account.

kanidm person credential update demo_user --name idm_admin
# spn: demo_user@idm.example.com
# Name: Demonstration User
# Primary Credential:
# uuid: 0e19cd08-f943-489e-8ff2-69f9eacb1f31
# generated password: set
# Can Commit: true
#
# cred update (? for help) # : pass
# New password:
# New password: [hidden]
# Confirm password:
# Confirm password: [hidden]
# success
#
# cred update (? for help) # : commit
# Do you want to commit your changes? yes
# success
kanidm login --name demo_user
kanidm self whoami --name demo_user

Credential Deletion

When a person deletes a credential, all sessions that were created by that credential are immediately logged out and invalidated.

Reauthentication / Privilege Access Mode

To allow for longer lived sessions in Kanidm, by default sessions are issued in a "privilege capable" but read-only mode. In order to access privileges for a short time, you must re-authenticate. This re-issues your session with a small time limited read-write session internally. You can consider this to be like sudo on a unix system or UAC on windows where you reauthenticate for short periods to access higher levels of privilege.

When using a user command that requires these privileges you will be warned:

kanidm person credential update william
# Privileges have expired for william@idm.example.com - you need to re-authenticate again.

To reauthenticate

kanidm reauth -D william