Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Evaluation Quickstart

This section will guide you through a quick setup of Kanidm for evaluation. It's recommended that for a production deployment you follow the steps in the installation chapter instead as there are a number of security considerations you should be aware of for production deployments.

Requirements

The only thing you'll need for this is Docker, Podman, or a compatible containerd environment installed and running.

Get the software

docker pull docker.io/kanidm/server:latest

Create your configuration

Create server.toml. The important parts you need to review and change are the domain and origin values. For this example, if you use domain = localhost and origin = https://localhost this will match commands later in the book. If you are using a different domain, you should change these values to match your environment.

# The server configuration file version.
version = "2"

#   The webserver bind address. Requires TLS certificates.
#   If the port is set to 443 you may require the
#   NET_BIND_SERVICE capability.
#   Defaults to "127.0.0.1:8443"
bindaddress = "[::]:8443"
#
#   The read-only ldap server bind address. Requires
#   TLS certificates. If set to 636 you may require
#   the NET_BIND_SERVICE capability.
#   Defaults to "" (disabled)
# ldapbindaddress = "[::]:3636"
#
#   The path to the kanidm database.
db_path = "/data/kanidm.db"
#
#   If you have a known filesystem, kanidm can tune the
#   database page size to match. Valid choices are:
#   [zfs, other]
#   If you are unsure about this leave it as the default
#   (other). After changing this
#   value you must run a vacuum task.
#   - zfs:
#     * sets database pagesize to 64k. You must set
#       recordsize=64k on the zfs filesystem.
#   - other:
#     * sets database pagesize to 4k, matching most
#       filesystems block sizes.
# db_fs_type = "zfs"
#
#   The number of entries to store in the in-memory cache.
#   Minimum value is 256. If unset
#   an automatic heuristic is used to scale this.
#   You should only adjust this value if you experience
#   memory pressure on your system.
# db_arc_size = 2048
#
#   TLS chain and key in pem format. Both must be present.
#   If the server receives a SIGHUP, these files will be
#   re-read and reloaded if their content is valid.
tls_chain = "/data/chain.pem"
tls_key = "/data/key.pem"
#
#   The log level of the server. May be one of info, debug, trace
#
#   NOTE: this can be overridden by the environment variable
#   `KANIDM_LOG_LEVEL` at runtime
#   Defaults to "info"
# log_level = "info"
#
#   The DNS domain name of the server. This is used in a
#   number of security-critical contexts
#   such as webauthn, so it *must* match your DNS
#   hostname. It is used to create
#   security principal names such as `william@idm.example.com`
#   so that in a (future) trust configuration it is possible
#   to have unique Security Principal Names (spns) throughout
#   the topology.
#
#   ⚠️  WARNING ⚠️
#
#   Changing this value WILL break many types of registered
#   credentials for accounts including but not limited to
#   webauthn, oauth tokens, and more.
#   If you change this value you *must* run
#   `kanidmd domain rename` immediately after.
domain = "idm.example.com"
#
#   The origin for webauthn. This is the url to the server,
#   with the port included if it is non-standard (any port
#   except 443). This must match or be a descendent of the
#   domain name you configure above. If these two items are
#   not consistent, the server WILL refuse to start!
#   origin = "https://idm.example.com"
#   # OR
#   origin = "https://idm.example.com:8443"
origin = "https://idm.example.com"

#   HTTPS requests can be reverse proxied by a loadbalancer.
#   To preserve the original IP of the caller, these systems
#   will often add a header such as "Forwarded" or
#   "X-Forwarded-For". Some other proxies can use the PROXY
#   protocol v2 header.
#   This setting allows configuration of the list of trusted
#   IPs or IP ranges which can supply this header information,
#   and which format the information is provided in.
#   Defaults to "none" (no trusted sources)
#   Only one option can be used at a time.
# [http_client_address_info]
# proxy-v2 = ["127.0.0.1", "127.0.0.0/8"]
#   # OR
# [http_client_address_info]
# x-forward-for = ["127.0.0.1", "127.0.0.0/8"]

#   LDAPS requests can be reverse proxied by a loadbalancer.
#   To preserve the original IP of the caller, these systems
#   can add a header such as the PROXY protocol v2 header.
#   This setting allows configuration of the list of trusted
#   IPs or IP ranges which can supply this header information,
#   and which format the information is provided in.
#   Defaults to "none" (no trusted sources)
# [ldap_client_address_info]
# proxy-v2 = ["127.0.0.1", "127.0.0.0/8"]

[online_backup]
#   The path to the output folder for online backups
path = "/data/kanidm/backups/"
#   The schedule to run online backups (see https://crontab.guru/)
#   every day at 22:00 UTC (default)
schedule = "00 22 * * *"
#    four times a day at 3 minutes past the hour, every 6th hours
# schedule = "03 */6 * * *"
#   We also support non standard cron syntax, with the following format:
#   sec  min   hour   day of month   month   day of week   year
#   (it's very similar to the standard cron syntax, it just allows to specify the seconds
#   at the beginning and the year at the end)
#   Number of backups to keep (default 7)
# versions = 7

Start the container

First we create a docker volume to store the data, then we start the container.

docker volume create kanidmd
docker create --name kanidmd \
  -p '443:8443' \
  -p '636:3636' \
  -v kanidmd:/data \
  docker.io/kanidm/server:latest

Copy the configuration to the container

docker cp server.toml kanidmd:/data/server.toml

Generate evaluation certificates

docker run --rm -i -t -v kanidmd:/data \
  docker.io/kanidm/server:latest \
  kanidmd cert-generate

Start Kanidmd Container

docker start kanidmd

Recover the Admin Role Passwords

The admin account is used to configure Kanidm itself.

docker exec -i -t kanidmd \
  kanidmd recover-account admin

The idm_admin account is used to manage persons and groups.

docker exec -i -t kanidmd \
  kanidmd recover-account idm_admin

Install the client tools

This happens on your computer, not in the container.

Kanidm requires locally installed client tools on the system used for administration via the command line. Follow the guide in the installing client tools chapter to install them before continuing.

Client tools are explained more in the client tools chapter, but to complete setup, you will only need to follow the steps below.

Setup the client tool configuration

After installing the kanidm tool, you will need to create a configuration file to continue.

# ~/.config/kanidm

uri = "https://localhost" # The URL of the server
verify_ca = false # disables TLS certificate verification as your are using a self-signed certificate

Check you can login

kanidm login --name idm_admin

Create an account for yourself

kanidm person create <your username> <Your Displayname>

Set up your account credentials

kanidm person credential create-reset-token <your username>

Then follow the presented steps.

What next?

You'll probably want to set it up properly, so that other computers can access it, so choose a domain name and complete the full server installation.

Alternatively you might like to try configurig one of these: