From 7925f873a88b78fdff6ddc2a1dddbb575170deb6 Mon Sep 17 00:00:00 2001 From: Sebastian Lenzlinger Date: Wed, 18 Jun 2025 00:11:45 +0200 Subject: [PATCH] Add kanidm-eval example config and task file! --- kanidm-eval/dot-config/eval_quickstart.md | 317 ++++++++++++ .../dot-config/evaluation_quickstart.html | 481 ++++++++++++++++++ kanidm-eval/dot-config/kanidm | 2 + kanidm-eval/dot-config/tasks | 100 ++++ 4 files changed, 900 insertions(+) create mode 100644 kanidm-eval/dot-config/eval_quickstart.md create mode 100644 kanidm-eval/dot-config/evaluation_quickstart.html create mode 100644 kanidm-eval/dot-config/kanidm create mode 100755 kanidm-eval/dot-config/tasks diff --git a/kanidm-eval/dot-config/eval_quickstart.md b/kanidm-eval/dot-config/eval_quickstart.md new file mode 100644 index 0000000..96fee01 --- /dev/null +++ b/kanidm-eval/dot-config/eval_quickstart.md @@ -0,0 +1,317 @@ +::: {#mdbook-help-container} +::: {#mdbook-help-popup} +## Keyboard shortcuts {#keyboard-shortcuts .mdbook-help-title} + +
+ +Press [←]{.kbd} or [→]{.kbd} to navigate between chapters + +Press [S]{.kbd} or [/]{.kbd} to search in the book + +Press [?]{.kbd} to show this help + +Press [Esc]{.kbd} to hide this help + +
+::: +::: + +::: {#body-container} +::: {#sidebar-resize-handle .sidebar-resize-handle} +::: sidebar-resize-indicator +::: +::: + +::: {#page-wrapper .page-wrapper} +::: page +::: {#menu-bar-hover-placeholder} +::: + +::: {#menu-bar .menu-bar .sticky} +::: left-buttons + +- Auto +- Light +- Rust +- Coal +- Navy +- Ayu +::: + +# Kanidm Administration {#kanidm-administration .menu-title} + +::: right-buttons +[](print.html "Print this book"){aria-label="Print this book"} +[](https://github.com/kanidm/kanidm "Git repository"){aria-label="Git repository"} +[](https://github.com/kanidm/kanidm/edit/master/book/src/evaluation_quickstart.md "Suggest an edit"){aria-label="Suggest an edit"} +::: +::: + +::: {#search-wrapper .hidden} +::: {#searchresults-outer .searchresults-outer .hidden} +::: {#searchresults-header .searchresults-header} +::: +::: +::: + +::: {#content .content} +::: {role="main"} +# [Evaluation Quickstart](#evaluation-quickstart){.header} + +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](installing_the_server.html) instead as there are a number of +security considerations you should be aware of for production +deployments. + +## [Requirements](#requirements){.header} + +The only thing you\'ll need for this is Docker, Podman, or a compatible +containerd environment installed and running. + +## [Get the software](#get-the-software){.header} + +``` bash +docker pull docker.io/kanidm/server:latest +``` + +## [Create your configuration](#create-your-configuration){.header} + +Create `server.toml`. The important parts are the `domain` and `origin`. +For this example, if you use `localhost` and `https://localhost:8443` +this will match later commands. + +``` toml +# 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" +origin = "https://idm.example.com:8443" + +# 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 +# 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](#start-the-container){.header} + +First we create a docker volume to store the data, then we start the +container. + +``` bash +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](#copy-the-configuration-to-the-container){.header} + +``` bash +docker cp server.toml kanidmd:/data/server.toml +``` + +## [Generate evaluation certificates](#generate-evaluation-certificates){.header} + +``` bash +docker run --rm -i -t -v kanidmd:/data \ + docker.io/kanidm/server:latest \ + kanidmd cert-generate +``` + +## [Start Kanidmd Container](#start-kanidmd-container){.header} + +``` bash +docker start kanidmd +``` + +## [Recover the Admin Role Passwords](#recover-the-admin-role-passwords){.header} + +The `admin` account is used to configure Kanidm itself. + +``` bash +docker exec -i -t kanidmd \ + kanidmd recover-account admin +``` + +The `idm_admin` account is used to manage persons and groups. + +``` shell +docker exec -i -t kanidmd \ + kanidmd recover-account idm_admin +``` + +## [Setup the client configuration](#setup-the-client-configuration){.header} + +This happens on your computer, not in the container. + +``` toml +# ~/.config/kanidm + +uri = "https://localhost:8443" +verify_ca = false +``` + +## [Check you can login](#check-you-can-login){.header} + +``` bash +kanidm login --name idm_admin +``` + +## [Create an account for yourself](#create-an-account-for-yourself){.header} + +``` shell +kanidm person create +``` + +## [Set up your account credentials](#set-up-your-account-credentials){.header} + +``` shell +kanidm person credential create-reset-token +``` + +Then follow the presented steps. + +## [What next?](#what-next){.header} + +You\'ll probably want to set it up properly, so that other computers can +access it, so [choose a domain name](choosing_a_domain_name.html) and +complete the full server installation. + +Alternatively you might like to try configurig one of these: + +- [OAuth2](./integrations/oauth2.html) for web services +- [PAM and nsswitch](./integrations/pam_and_nsswitch.html) for + authentication to Linux systems +- [Replication](repl/), if one Kanidm instance isn\'t enough +::: + +[](introduction_to_kanidm.html "Previous chapter"){.mobile-nav-chapters +.previous rel="prev" aria-label="Previous chapter" +aria-keyshortcuts="Left"} +[](supported_features.html "Next chapter"){.mobile-nav-chapters .next +rel="next prefetch" aria-label="Next chapter" aria-keyshortcuts="Right"} + +::: {style="clear: both"} +::: +::: +::: + +[](introduction_to_kanidm.html "Previous chapter"){.nav-chapters +.previous rel="prev" aria-label="Previous chapter" +aria-keyshortcuts="Left"} +[](supported_features.html "Next chapter"){.nav-chapters .next +rel="next prefetch" aria-label="Next chapter" aria-keyshortcuts="Right"} +::: +::: diff --git a/kanidm-eval/dot-config/evaluation_quickstart.html b/kanidm-eval/dot-config/evaluation_quickstart.html new file mode 100644 index 0000000..8a6b639 --- /dev/null +++ b/kanidm-eval/dot-config/evaluation_quickstart.html @@ -0,0 +1,481 @@ + + + + + + Evaluation Quickstart - Kanidm Administration + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

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 are the domain and origin. For this example, if you +use localhost and https://localhost:8443 this will match later commands.

+
# 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"
+origin = "https://idm.example.com:8443"
+
+#   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
+# 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
+
+

Setup the client configuration

+

This happens on your computer, not in the container.

+
# ~/.config/kanidm
+
+uri = "https://localhost:8443"
+verify_ca = false
+
+

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:

+ + +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + +
+ + diff --git a/kanidm-eval/dot-config/kanidm b/kanidm-eval/dot-config/kanidm new file mode 100644 index 0000000..d8e6189 --- /dev/null +++ b/kanidm-eval/dot-config/kanidm @@ -0,0 +1,2 @@ +uri = "https://localhost:8443" +verify_ca = false diff --git a/kanidm-eval/dot-config/tasks b/kanidm-eval/dot-config/tasks new file mode 100755 index 0000000..a7469b8 --- /dev/null +++ b/kanidm-eval/dot-config/tasks @@ -0,0 +1,100 @@ +#!/usr/bin/env bash + + +fedora_build_notes () { + echo "NOTE: clang and lld are required to build Kanidm for performance" + echo "Rustup toolchain is needed" + +} +install_system_lib_deps_fedora () { + dnf install systemd-devel sqlite-devel openssl-devel pam-devel clang lld +} + +install_webui_additional_pkgs () { + dnf install perl-FindBin perl-File-Compare +} + +get_server_dev_config () { + wget https://raw.githubusercontent.com/kanidm/kanidm/master/examples/server.toml +} + +make_localhost_config () { + if [[ -f server.toml ]];then + sed 's/idm\.example\.com/localhost/g' server.toml > server_localhost.toml + else + echo "First get example server.toml!" + fi +} + +get_the_software () { + podman pull docker.io/kanidm/server:latest +} + +create_eval_config () { + get_server_dev_config && make_localhost_config +} + +create_kanidmd_volume () { + # First create volume for the data! + podman volume create kanidmd +} + +start_eval_container () { + create_kanidmd_volume && podman create --name kanidmd \ + -p '8443:8443' \ + -p '3636:3636' \ + -v kanidmd:/data \ + docker.io/kanidm/server:latest +} + +copy_config_to_container () { + podman cp server_localhost.toml kanidmd:/data/server.toml +} + +generate_eval_certs () { + podman run --rm -i -t -v kanidmd:/data \ + docker.io/kanidm/server:latest \ + kanidmd cert-generate +} + +recover_admin_pw () { + podman exec -i -t kanidmd \ + kanidmd recover-account admin +} + +recover_idm_admin_pw () { + podman exec -i -t kanidmd \ + kanidmd recover-account idm_admin +} + +setup_eval_client_config () { + cat <<'EOF' > ./kanidm +uri = "https://localhost:8443" +verify_ca = false +EOF +} + +check_can_login () { + if ! command -v kanidm > /dev/null; then + echo "First install kanidm client tools!" + else + kanidm login --name idm_admin + fi +} + +create_account () { + # Usage: + # kanidm person create + + echo "Implement create_account" +} + +setup_account_credentials () { + # Usage: + # kanidm person credential create-reset-token + echo "Implement setup_account_credentials" +} + + + +