mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-02-23 04:27:02 +01:00
Code Issues Actions 16 Packages Projects Releases Wiki Activity

Auto-publishing the book and rustdoc. (#534)

Browse source
This commit is contained in:
James Hodgkinson 2021-07-24 11:12:35 +10:00 committed by GitHub
parent 8bc7afe007
commit 6ff74c976e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 336 additions and 302 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
.github/workflows/kanidm_book.yml vendored Normal file
View file

@ -0,0 +1,47 @@
name: GitHub Pages
on:
push:
branches:
- master
pull_request:
jobs:
deploy:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v2
- name: Install deps
run: sudo apt-get update && sudo apt-get install -y clang build-essential librust-openssl-dev libssl-dev libsqlite3-dev libudev-dev libpam0g-dev
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: 'latest'
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
- uses: actions-rs/cargo@v1
with:
command: doc
args: --no-deps
- name: Copy developer readme into book
run: cp DEVELOPER_README.md ./kanidm_book/src/ && echo '- [Developer Guide](DEVELOPER_README.md)' >> ./kanidm_book/src/SUMMARY.md
- name: Run mdbook
run: mdbook build kanidm_book
- name: Move files around
run: mv ./kanidm_book/book/ ./docs/ && mkdir -p ./docs/rustdoc/ && mv ./target/doc/* ./docs/rustdoc/
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
destination_dir: ./docs

2
README.md
View file

@ -18,7 +18,7 @@ treated as such.
## Documentation / Getting Started / Install
If you want to deploy kanidm to see what it can do, you should read the [kanidm book]
If you want to deploy Kanidm to see what it can do, you should read the [kanidm book]
We also publish limited [support guidelines].

35
kanidm_book/src/SUMMARY.md
View file

@ -1,26 +1,21 @@
# Summary
[Introduction to Kanidm](./intro.md)
Getting started with Kanidm
- [Introduction to Kanidm](./intro.md)
- [Installing the Server](./installing_the_server.md)
- [Administrative Tasks](./administrivia.md)
- [Interacting with the Server](./client_tools.md)
- [Server Configuration](./installing_the_server.md)
- [Security Hardening](./security_hardening.md)
- [Client Tools](./client_tools.md)
- [Installing client tools](./installing_client_tools.md)
- [Accounts and Groups](./accounts_and_groups.md)
Additional information
- [Legacy Applications - LDAP](./ldap.md)
- [Monitoring the platform](./monitoring.md)
- [Administrative Tasks](./administrivia.md)
- [Monitoring the platform](./monitoring.md)
- [Password Quality and Badlisting](./password_quality.md)
- [POSIX Accounts and Groups](./posix_accounts.md)
- [SSH Key Distribution](./ssh_key_dist.md)
- [The Recycle Bin](./recycle_bin.md)
- [LDAP](./ldap.md)
- [PAM and nsswitch](./pam_and_nsswitch.md)
- [Password Quality and Badlisting](./password_quality.md)
- [POSIX Accounts and Groups](./posix_accounts.md)
- [RADIUS](./radius.md)
- [Recycle Bin](./recycle_bin.md)
- [Security Hardening](./security_hardening.md)
- [SSH Key Distribution](./ssh_key_dist.md)
-----------
[Why TLS?](./why_tls.md)
- [Why TLS?](./why_tls.md)

2
kanidm_book/src/accounts_and_groups.md
View file

@ -124,7 +124,7 @@ accounts". This is to help prevent elevation attacks, where say a member of a
service desk could attempt to reset the password of idm_admin or admin, or even a member of
HR or System Admin teams to move laterally.
Generally, membership of a "privilege" group that ships with kanidm, such as:
Generally, membership of a "privilege" group that ships with Kanidm, such as:
* idm_account_manage_priv
* idm_people_read_priv

68
kanidm_book/src/client_tools.md
View file

@ -1,70 +1,10 @@
# Interacting with the Server
# Client tools
To interact with Kanidm as an administrator, you'll need to use our command line tools.
## From packages
Kanidm currently supports:
* OpenSUSE Tumbleweed
* OpenSUSE Leap 15.3
* Fedora 33/34
### OpenSUSE Tumbleweed
Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
the clients with:
zypper ref
zypper in kanidm-clients
### OpenSUSE Leap 15.3
Leap 15.3 is still not fully supported with Kanidm. For an experimental client, you can
try the development repository. Using zypper you can add the repository with:
zypper ar -f obs://network:idm network_idm
Then you need to refresh your metadata and install the clients.
zypper ref
zypper in kanidm-clients
### Fedora
Fedora is still experimentally supported through the development repository. You need to add the repository metadata into the correct directory.
cd /etc/yum.repos.d
# 33
wget https://download.opensuse.org/repositories/network:/idm/Fedora_33/network:idm.repo
# 34
wget https://download.opensuse.org/repositories/network:/idm/Fedora_34/network:idm.repo
You can then install with:
dnf install kanidm-clients
## From source (CLI only, not recommended)
After you check out the source (see [GitHub](https://github.com/kanidm/kanidm)), navigate to:
cd kanidm_tools
cargo install --path .
## Checking that the tools work
Now you can check your instance is working. You may need to provide a CA certificate for verification
with the -C parameter:
kanidm login --name anonymous
kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous
kanidm self whoami -H https://localhost:8443 --name anonymous
Now you can take some time to look at what commands are available - please [ask for help at any time](https://github.com/kanidm/kanidm#getting-in-contact--questions).
To interact with Kanidm as an administrator, you'll need to use our command line tools. If you haven't installed them yet, [install them now](installing_client_tools.mdc).
## Kanidm configuration
You can configure kanidm to help make commands simpler by modifying ~/.config/kanidm OR /etc/kanidm/config
You can configure `kanidm` to help make commands simpler by modifying `~/.config/kanidm` or `/etc/kanidm/config`.
uri = "https://idm.example.com"
verify_ca = true|false
@ -83,7 +23,7 @@ to establish a session token.
kanidm login --name USERNAME
kanidm login --name admin
Once complete, you can use kanidm without reauthenticating for a period of time for administration.
Once complete, you can use `kanidm` without reauthenticating for a period of time for administration.
You can list active sessions with:

63
kanidm_book/src/installing_client_tools.md Normal file
View file

@ -0,0 +1,63 @@
# Installing Client Tools
> **NOTE** As this project is in a rapid development phase, running different release versions will likely present incompatibilities. Ensure you're running the same release version of client/server binaries (eg. 1.1.0-alpha5, released 2021-07-07)
## From packages
Kanidm currently supports:
* OpenSUSE Tumbleweed
* OpenSUSE Leap 15.3
* Fedora 33/34
### OpenSUSE Tumbleweed
Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
the clients with:
zypper ref
zypper in kanidm-clients
### OpenSUSE Leap 15.3
Leap 15.3 is still not fully supported with Kanidm. For an experimental client, you can
try the development repository. Using zypper you can add the repository with:
zypper ar -f obs://network:idm network_idm
Then you need to refresh your metadata and install the clients.
zypper ref
zypper in kanidm-clients
### Fedora
Fedora is still experimentally supported through the development repository. You need to add the repository metadata into the correct directory.
cd /etc/yum.repos.d
# 33
sudo wget https://download.opensuse.org/repositories/network:/idm/Fedora_33/network:idm.repo
# 34
sudo wget https://download.opensuse.org/repositories/network:/idm/Fedora_34/network:idm.repo
You can then install with:
sudo dnf install kanidm-clients
## From source (CLI only, not recommended)
After you check out the source (see [GitHub](https://github.com/kanidm/kanidm)), navigate to:
cd kanidm_tools
cargo install --path .
## Checking that the tools work
Now you can check your instance is working. You may need to provide a CA certificate for verification
with the -C parameter:
kanidm login --name anonymous
kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous
kanidm self whoami -H https://localhost:8443 --name anonymous
Now you can take some time to look at what commands are available - please [ask for help at any time](https://github.com/kanidm/kanidm#getting-in-contact--questions).

127
kanidm_book/src/installing_the_server.md
View file

@ -1,11 +1,13 @@
# Installing the Server
> **NOTE** Our preferred deployment method is in containers, the documentation assumes you're running in docker. Kanidm will run in traditional compute, and server builds are available for multiple platforms or you can build the binaries yourself.
Currently we have docker images for the server components. They can be found at:
https://hub.docker.com/r/kanidm/server
https://hub.docker.com/r/kanidm/radius
- <https://hub.docker.com/r/kanidm/server>
- <https://hub.docker.com/r/kanidm/radius>
You can fetch these with:
You can fetch these by running the commands:
docker pull kanidm/server:latest
docker pull kanidm/radius:latest
@ -16,9 +18,14 @@ If you wish to use an x86\_64 cpu-optimised version (See System Requirements CPU
You may need to adjust your example commands throughout this document to suit.
## Development Version
If you are interested in running the latest code from development, you can do this by changing the
docker tag to `kanidm/server:devel` or `kanidm/server:x86_64_v3_devel` instead.
## System Requirements
### CPU
#### CPU
If you are using the x86\_64 cpu-optimised version, you must have a CPU that is from 2013 or newer
(Haswell, Ryzen). The following instruction flags are used.
@ -36,12 +43,12 @@ image. These flags will be:
cmov, cx8, fxsr, mmx, sse, sse2
### Memory
#### Memory
Kanidm extensively uses memory caching, trading memory consumption to improve parallel throughput.
You should expect to see 64KB of ram per entry in your database, depending on cache tuning and settings.
### Disk
#### Disk
You should expect to use up to 8KB of disk per entry you plan to store. At an estimate 10,000 entry
databases will consume 40MB, 100,000 entry will consume 400MB.
@ -113,109 +120,9 @@ OR for a shell into the volume:
docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
## Configuration
You will also need a config file in the volume named `server.toml` (Within the container it should be `/data/server.toml`). Its contents should be as follows:
# The webserver bind address. Will use HTTPS if tls_* is provided.
# Defaults to "127.0.0.1:8443"
bindaddress = "127.0.0.1:8443"
#
# The read-only ldap server bind address. The server will use LDAPS if tls_* is provided.
# Defaults to "" (disabled)
# ldapbindaddress = "127.0.0.1:3636"
#
# The path to the kanidm database.
db_path = "/data/kanidm.db"
#
# If you have a known filesystem, kanidm can tune sqlite 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 sqlite pagesize to 64k. You must set recordsize=64k on the zfs filesystem.
# - other:
# * sets sqlite 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.
# db_arc_size = 2048
#
# TLS chain and key in pem format. Both must be commented, or both must be present
# tls_chain = "/data/chain.pem"
# tls_key = "/data/key.pem"
#
# The log level of the server. May be default, verbose, perfbasic, perffull
# Defaults to "default"
# log_level = "default"
#
# The origin for webauthn. This is the url to the server, with the port included if
# it is non-standard (any port except 443)
# origin = "https://idm.example.com"
origin = "https://idm.example.com:8443"
#
# The role of this server. This affects features available and how replication may interact.
# Valid roles are:
# - write_replica
# This server provides all functionality of Kanidm. It allows authentication, writes, and
# the web user interface to be served.
# - write_replica_no_ui
# This server is the same as a write_replica, but does NOT offer the web user interface.
# - read_only_replica
# This server will not writes initiated by clients. It supports authentication and reads,
# and must have a replication agreement as a source of it's data.
# Defaults to "write_replica".
# role = "write_replica"
An example is located in [examples/server.toml](../../examples/server.toml).
Then you can setup the initial admin account and initialise the database into your volume.
docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd recover_account -c /data/server.toml -n admin
You then want to set your domain name so that security principal names (spn's) are generated correctly.
This domain name *must* match the url/origin of the server that you plan to use to interact with
so that other features work correctly. It is possible to change this domain name later.
docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd domain_name_change -c /data/server.toml -n idm.example.com
Now we can run the server so that it can accept connections. This defaults to using `-c /data/server.toml`
docker run -p 8443:8443 -v kanidmd:/data kanidm/server:latest
# Development Version
If you are interested to run our latest code from development, you can do this by changing the
docker tag to `kanidm/server:devel` or `kanidm/server:x86_64_v3_devel` instead.
# Running as non-root in docker
By default the above commands will run kanidmd as "root" in the container to make the onboarding
smoother. However, this is not recommended in production for security reasons.
You should allocate a uidnumber/gidnumber for the service to run as that is unique on your host
system. In this example we use `1000:1000`
You will need to adjust the permissions on the /data volume to ensure that the process
can manage the files. Kanidm requires the ability to write to the /data directory to create
the sqlite files. This uid/gidnumber should match the above. You could consider the following
changes to help isolate these changes:
docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
# mkdir /data/db/
# chown 1000:1000 /data/db/
# chmod 750 /data/db/
# sed -i -e "s/db_path.*/db_path = \"\/data\/db\/kanidm.db\"/g" /data/server.toml
# chown root:root /data/server.toml
# chmod 644 /data/server.toml
You can then use this with run the kanidm server in docker with a user.
docker run --rm -i -t -u 1000:1000 -v kanidmd:/data kanidm/server:latest /sbin/kanidmd ...
> **HINT**
> You need to use the uidnumber/gidnumber to the `-u` argument, as the container can't resolve
> usernames from the host system.
# Continue on to [Configuring the Server](server_configuration.md)

92
kanidm_book/src/intro.md
View file

@ -13,6 +13,10 @@ The intent of the Kanidm project is to:
> This is a pre-release project. While all effort has been made to ensure no data loss
> or security flaws, you should still be careful when using this in your environment.
## Library documentation
Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](./rustdoc/kanidm/)
## Why do I want Kanidm?
Whether you work in a business, a volunteer organisation, or are an enthusiast who manages
@ -29,50 +33,50 @@ access or privilege than they require.
Kanidm acts as a central authority of accounts in your organisation and allows each account to associate
many devices and credentials with different privileges. An example of how this looks:
┌──────────────────┐
┌┴─────────────────┐│
│ ││
┌───────────────────┬───▶│ Kanidm │◀──────┬─────────────────────────┐
│ │ │ ├┘ │ │
│ │ └──────────────────┘ │ Verify
Account Data │ ▲ │ Radius
References │ │ │ Password
│ │ │ │ │
│ │ │ │ ┌────────────┐
│ │ │ │ │ │
│ │ │ Verify │ RADIUS │
┌────────────┐ │ Retrieve SSH Application │ │
│ │ │ Public Keys Password └────────────┘
│ Database │ │ │ │ ▲
│ │ │ │ │ │
└────────────┘ │ │ │ ┌─────────┴──────────┐
▲ │ │ │ │ │
│ │ │ │ │ │
┌────────────┐ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ │ │ │ │ │ │ │ │ │ │
│ Web Site │ │ │ SSH │ │ Email │ │ WIFI │ │ VPN │
│ │ │ │ │ │ │ │ │ │ │
└────────────┘ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘
▲ │ ▲ ▲ ▲ ▲
│ │ │ │ │ │
│ │ │ │ │ │
│ Login To │ │ │ │
SSO/Oauth Oauth/SSO SSH Keys Application Radius Radius
│ │ │ Password Password Password
│ │ │ │ │ │
│ │ │ │ │ │
│ │ │ │ │ │
│ │ ┌──────────┐ │ │ │
│ │ │ │ │ │ │
└──────────────────┴────────│ Laptop │───────────┴───────────────┴────────────────────┘
│ │
└──────────┘
▲
│
│
┌──────────┐
│ You │
└──────────┘
┌──────────────────┐
┌┴─────────────────┐│
│ ││
┌───────────────┬───▶│ Kanidm │◀─────┬─────────────────────────┐
│ │ │ ├┘ │ │
│ │ └──────────────────┘ │ Verify
Account Data │ ▲ │ Radius
References │ │ │ Password
│ │ │ │ │
│ │ │ │ ┌────────────┐
│ │ │ │ │ │
│ │ │ Verify │ RADIUS │
┌────────────┐ │ Retrieve SSH Application │ │
│ │ │ Public Keys Password └────────────┘
│ Database │ │ │ │ ▲
│ │ │ │ │ │
└────────────┘ │ │ │ ┌────────┴──────┐
▲ │ │ │ │ │
│ │ │ │ │ │
┌────────────┐ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ │ │ │ │ │ │ │ │ │ │
│ Web Site │ │ │ SSH │ │ Email │ │ WIFI │ │ VPN │
│ │ │ │ │ │ │ │ │ │ │
└────────────┘ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘
▲ │ ▲ ▲ ▲ ▲
│ │ │ │ │ │
│ │ │ │ │ │
│ Login To │ │ │ │
SSO/Oauth Oauth/SSO SSH Keys Application Radius Radius
│ │ │ Password Password Password
│ │ │ │ │ │
│ │ │ │ │ │
│ │ │ │ │ │
│ │ ┌──────────┐ │ │ │
│ │ │ │ │ │ │
└──────────────┴────────│ Laptop │──────────┴───────────────┴───────────────┘
│ │
└──────────┘
▲
│
│
┌──────────┐
│ You │
└──────────┘
A key design goal is that you authenticate with your device in some manner, and then your device will
continue to authenticate you in the future. Each of these different types of credential from SSH keys,

6
kanidm_book/src/ldap.md
View file

@ -1,4 +1,4 @@
# Legacy Applications -- LDAP
# LDAP
While many applications can support systems like SAML or OAuth, many do not. LDAP
has been the "lingua franca" of authentication for many years, with almost
@ -43,7 +43,7 @@ For this reason, when you search the LDAP interface, Kanidm will make some mappi
* The '\*' and '+' operators can not be used in conjuction with attribute lists in searches.
These decisions were made to make the path as simple and effective as possible,
relying more on the kanidm query and filter system than attempting to generate a tree-like
relying more on the Kanidm query and filter system than attempting to generate a tree-like
representation of data. As almost all clients can use filters for entry selection
we don't believe this is a limitation for consuming applications.
@ -81,7 +81,7 @@ By default Kanidm is limited in what attributes are generated or remaped into LD
the server internally contains a map of extended attribute mappings for application specific requests
that must be satisfied.
An example is that some applications expect and require a 'CN' value, even though kanidm does not
An example is that some applications expect and require a 'CN' value, even though Kanidm does not
provide it. If the application is unable to be configured to accept "name" it may be necessary
to use Kanidm's mapping feature. Today these are compiled into the server so you may need to open
an issue with your requirements.

39
kanidm_book/src/pam_and_nsswitch.md
View file

@ -1,22 +1,12 @@
# PAM and nsswitch
PAM and nsswitch are the core mechanisms used by Linux and BSD clients
to resolve identities from an IDM service like kanidm into accounts that
can be used on the machine for various interactive tasks.
[PAM](http://linux-pam.org) and [nsswitch](https://en.wikipedia.org/wiki/Name_Service_Switch) are the core mechanisms used by Linux and BSD clients to resolve identities from an IDM service like Kanidm into accounts that can be used on the machine for various interactive tasks.
## The unix daemon
## The UNIX daemon
Kanidm provide a unix daemon that runs on any client that wants to use pam
and nsswitch integration. This is provided as the daemon can cache the accounts
for users who have unreliable networks or leave the site where kanidm is. The
cache is also able to cache missing-entry responses to reduce network traffic
and main server load.
Kanidm provides a UNIX daemon that runs on any client that wants to use PAM and nsswitch integration. This is provided as the daemon can cache the accounts for users who have unreliable networks or leave the site where Kanidm is. The cache is also able to cache missing-entry responses to reduce network traffic and main server load.
Additionally, the daemon means that the pam and nsswitch integration libraries
can be small, helping to reduce the attack surface of the machine.
Similarly, a tasks daemon is available that can create home directories on first
login and supports several features related to aliases and links to these
home directories.
Additionally, the daemon means that the PAM and nsswitch integration libraries can be small, helping to reduce the attack surface of the machine. Similarly, a tasks daemon is available that can create home directories on first login and supports several features related to aliases and links to these home directories.
We recommend you install the client daemon from your system package manager.
@ -33,10 +23,9 @@ You can check the privileged tasks daemon is running with
systemctl status kanidm-unixd-tasks
> **NOTE** The `kanidm_unixd_tasks` daemon is not required for pam and nsswitch functionality.
> **NOTE** The `kanidm_unixd_tasks` daemon is not required for PAM and nsswitch functionality.
> If disabled, your system will function as usual. It is however recommended due to the features
> it provides supporting kanidm's capabilities.
> it provides supporting Kanidm's capabilities.
Both unixd daemons use the connection configuration from /etc/kanidm/config. This is the covered in
[client_tools](./client_tools.md#kandim-configuration).
@ -52,8 +41,8 @@ You can also configure some unixd specific options with the file /etc/kanidm/uni
gid_attr_map = "spn"
The `pam_allowed_login_groups` defines a set of posix groups where membership of any of these
groups will be allowed to login via pam. All posix users and groups can be resolved by nss
regardless of pam login status. This may be a group name, spn or uuid.
groups will be allowed to login via PAM. All posix users and groups can be resolved by nss
regardless of PAM login status. This may be a group name, spn or uuid.
`default_shell` is the default shell for users with none defined. Defaults to `/bin/sh`.
@ -69,7 +58,7 @@ to nss calls. It is recommended you choose a "human friendly" attribute here.
Valid choices are `none`, `uuid`, `name`, `spn`. Defaults to `spn`.
> **NOTICE:**
> All users in kanidm can change their name (and their spn) at any time. If you change
> All users in Kanidm can change their name (and their spn) at any time. If you change
> `home_attr` from `uuid` you *must* have a plan on how to manage these directory renames
> in your system. We recommend that you have a stable id (like the uuid) and symlinks
> from the name to the uuid folder. Automatic support is provided for this via the unixd
@ -122,7 +111,7 @@ You can also do the same for groups.
## PAM
> **WARNING:** Modifications to pam configuration *may* leave your system in a state
> **WARNING:** Modifications to PAM configuration *may* leave your system in a state
> where you are unable to login or authenticate. You should always have a recovery
> shell open while making changes (ie root), or have access to single-user mode
> at the machine's console.
@ -135,7 +124,7 @@ where each module may request or reuse authentication token information.
### Before you start
You *should* backup your /etc/pam.d directory from its original state as you *may* change the
pam config in a way that will cause you to be unable to authenticate to your machine.
PAM config in a way that will cause you to be unable to authenticate to your machine.
cp -a /etc/pam.d /root/pam.d.backup
@ -148,7 +137,7 @@ To configure PAM on suse you must module four files:
/etc/pam.d/common-password
/etc/pam.d/common-session
Each of these controls one of the four stages of pam. The content should look like:
Each of these controls one of the four stages of PAM. The content should look like:
# /etc/pam.d/common-account-pc
account [default=1 ignore=ignore success=ok] pam_localuser.so
@ -182,7 +171,7 @@ Each of these controls one of the four stages of pam. The content should look li
### Fedora 33
> **WARNING:** kanidm currently has no support for SELinux policy - this may mean you need to
> **WARNING:** Kanidm currently has no support for SELinux policy - this may mean you need to
> run the daemon with permissive mode for the unconfined_service_t daemon type. To do this run:
> `semanage permissive -a unconfined_service_t`. To undo this run `semanage permissive -d unconfined_service_t`.
>
@ -319,7 +308,7 @@ You can clear (wipe) the cache with:
$ kanidm_cache_clear
There is an important distinction between these two - invalidated cache items may still
be yielded to a client request if the communication to the main kanidm server is not
be yielded to a client request if the communication to the main Kanidm server is not
possible. For example, you may have your laptop in a park without wifi.
Clearing the cache, however, completely wipes all local data about all accounts and groups.

27
kanidm_book/src/password_quality.md
View file

@ -1,39 +1,28 @@
# Password Quality and Badlisting
Kanidm embeds a set of tools to help your users use and create strong passwords. This is important
as not all user types will require MFA for their roles, but compromised accounts still pose a risk.
There may also be deployment or other barriers to a site rolling out site wide MFA.
Kanidm embeds a set of tools to help your users use and create strong passwords. This is important as not all user types will require MFA for their roles, but compromised accounts still pose a risk. There may also be deployment or other barriers to a site rolling out site wide MFA.
## Quality Checking
Kanidm enforces that all passwords are checked by the library "zxcvbn". This has a large number of
checks for password quality. It also provides constructive feedback to users on how to improve their
passwords if it was rejected.
Kanidm enforces that all passwords are checked by the library "[zxcvbn](https://github.com/dropbox/zxcvbn)". This has a large number of checks for password quality. It also provides constructive feedback to users on how to improve their passwords if it was rejected.
Some things that zxcvbn looks for is use of the account name or email in the password, common passwords,
low entropy passwords, dates, reverse words and more.
Some things that zxcvbn looks for is use of the account name or email in the password, common passwords, low entropy passwords, dates, reverse words and more.
This library can not be disabled - all passwords in Kanidm must pass this check.
## Password Badlisting
This is the process of configuring a list of passwords to exclude from being able to be used. This
is especially useful if a specific business has been notified of a compromised account, allowing
you to maintain a list of customised excluded passwords.
This is the process of configuring a list of passwords to exclude from being able to be used. This is especially useful if a specific business has been notified of a compromised account, allowing you to maintain a list of customised excluded passwords.
The other value to this feature is being able to badlist common passwords that zxcvbn does not
detect, or from other large scale password compromises.
The other value to this feature is being able to badlist common passwords that zxcvbn does not detect, or from other large scale password compromises.
By default we ship with a preconfigured badlist that is updated overtime as new password breach
lists are made available.
By default we ship with a preconfigured badlist that is updated overtime as new password breach lists are made available.
## Updating your own badlist.
You can update your own badlist by using the proided `kanidm_badlist_preprocess` tool which helps
to automate this process.
You can update your own badlist by using the proided `kanidm_badlist_preprocess` tool which helps to automate this process.
Given a list of passwords in a text file, it will generate a modification set which can be
applied. The tool also provides the command you need to run to apply this.
Given a list of passwords in a text file, it will generate a modification set which can be applied. The tool also provides the command you need to run to apply this.
kanidm_badlist_preprocess -m -o /tmp/modlist.json <password file> [<password file> <password file> ...]

31
kanidm_book/src/security_hardening.md
View file

@ -15,9 +15,11 @@ The unixd resolver is also a high value target as it can be accessed to allow un
access to a server, to intercept communications to the server, or more. This also must be protected
carfully.
For this reason the kanidm's components must be protected carefully. Kanidm avoids many classic
For this reason, Kanidm's components must be protected carefully. Kanidm avoids many classic
attacks by being developed in a memory safe language, but risks still exist.
## Startup Warnings
At startup Kanidm will warn you if the environment it is running in is suspicious or
has risks. For example:
@ -114,4 +116,31 @@ This file should be everyone-readable which is why the bits are defined as such.
> but it affects the check. We don't believe this is a significant issue though because
> setting these to 440 and 444 helps to prevent accidental changes by an administrator anyway
## Running as non-root in docker
The commands provided in this book will run kanidmd as "root" in the container to make the onboarding
smoother. However, this is not recommended in production for security reasons.
You should allocate a uidnumber/gidnumber for the service to run as that is unique on your host
system. In this example we use `1000:1000`
You will need to adjust the permissions on the `/data` volume to ensure that the process
can manage the files. Kanidm requires the ability to write to the `/data` directory to create
the sqlite files. This uid/gidnumber should match the above. You could consider the following
changes to help isolate these changes:
docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
# mkdir /data/db/
# chown 1000:1000 /data/db/
# chmod 750 /data/db/
# sed -i -e "s/db_path.*/db_path = \"\/data\/db\/kanidm.db\"/g" /data/server.toml
# chown root:root /data/server.toml
# chmod 644 /data/server.toml
You can then use this with run the kanidm server in docker with a user.
docker run --rm -i -t -u 1000:1000 -v kanidmd:/data kanidm/server:latest /sbin/kanidmd ...
> **HINT**
> You need to use the uidnumber/gidnumber to the `-u` argument, as the container can't resolve
> usernames from the host system.

70
kanidm_book/src/server_configuration.md Normal file
View file

@ -0,0 +1,70 @@
## Configuring the Server
You will also need a config file in the volume named `server.toml` (Within the container it should be `/data/server.toml`). Its contents should be as follows:
# The webserver bind address. Will use HTTPS if tls_* is provided.
# Defaults to "127.0.0.1:8443"
bindaddress = "127.0.0.1:8443"
#
# The read-only ldap server bind address. The server will use LDAPS if tls_* is provided.
# Defaults to "" (disabled)
# ldapbindaddress = "127.0.0.1:3636"
#
# The path to the kanidm database.
db_path = "/data/kanidm.db"
#
# If you have a known filesystem, kanidm can tune sqlite 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 sqlite pagesize to 64k. You must set recordsize=64k on the zfs filesystem.
# - other:
# * sets sqlite 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.
# db_arc_size = 2048
#
# TLS chain and key in pem format. Both must be commented, or both must be present
# tls_chain = "/data/chain.pem"
# tls_key = "/data/key.pem"
#
# The log level of the server. May be default, verbose, perfbasic, perffull
# Defaults to "default"
# log_level = "default"
#
# The origin for webauthn. This is the url to the server, with the port included if
# it is non-standard (any port except 443)
# origin = "https://idm.example.com"
origin = "https://idm.example.com:8443"
#
# The role of this server. This affects features available and how replication may interact.
# Valid roles are:
# - write_replica
# This server provides all functionality of Kanidm. It allows authentication, writes, and
# the web user interface to be served.
# - write_replica_no_ui
# This server is the same as a write_replica, but does NOT offer the web user interface.
# - read_only_replica
# This server will not writes initiated by clients. It supports authentication and reads,
# and must have a replication agreement as a source of it's data.
# Defaults to "write_replica".
# role = "write_replica"
An example is located in [examples/server.toml](../../examples/server.toml).
Then you can setup the initial admin account and initialise the database into your volume.
docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd recover_account -c /data/server.toml -n admin
You then want to set your domain name so that security principal names (spn's) are generated correctly.
This domain name *must* match the url/origin of the server that you plan to use to interact with
so that other features work correctly. It is possible to change this domain name later.
docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd domain_name_change -c /data/server.toml -n idm.example.com
Now we can run the server so that it can accept connections. This defaults to using `-c /data/server.toml`
docker run -p 8443:8443 -v kanidmd:/data kanidm/server:latest

2
kanidm_book/src/ssh_key_dist.md
View file

@ -37,7 +37,7 @@ can still ssh into your machines, even if your network is down, you move away fr
some other interruption occurs.
The kanidm_ssh_authorizedkeys command is part of the kanidm-unix-clients package, so should be installed
on the servers. It communicates to kanidm_unixd, so you should have a configured pam/nsswitch
on the servers. It communicates to kanidm_unixd, so you should have a configured PAM/nsswitch
setup as well.
You can test this is configured correctly by running:

2
kanidm_proto/src/v1.rs
View file

@ -717,7 +717,7 @@ pub struct TotpSecret {
}
impl TotpSecret {
/// https://github.com/google/google-authenticator/wiki/Key-Uri-Format
/// <https://github.com/google/google-authenticator/wiki/Key-Uri-Format>
pub fn to_uri(&self) -> String {
// label = accountname / issuer (“:” / “%3A”) *”%20” accountname
// This is already done server side but paranoia is good!

1
kanidm_tools/Cargo.toml
View file

@ -17,6 +17,7 @@ path = "src/cli/lib.rs"
[[bin]]
name = "kanidm"
path = "src/cli/main.rs"
doc = false
[[bin]]
name = "kanidm_ssh_authorizedkeys_direct"

12
kanidm_unix_int/pam_kanidm/src/pam/module.rs
View file

@ -68,7 +68,7 @@ pub type PamResult<T> = Result<T, PamResultCode>;
/// Type-level mapping for safely retrieving values with `get_item`.
///
/// See `pam_get_item` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub trait PamItem {
/// Maps a Rust type to a pam constant.
///
@ -84,7 +84,7 @@ impl PamHandle {
/// previously.
///
/// See `pam_get_data` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub unsafe fn get_data<'a, T>(&'a self, key: &str) -> PamResult<&'a T> {
let c_key = CString::new(key).unwrap();
let mut ptr: *const PamDataT = ptr::null();
@ -102,7 +102,7 @@ impl PamHandle {
/// as long as the current pam cycle.
///
/// See `pam_set_data` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub fn set_data<T>(&self, key: &str, data: Box<T>) -> PamResult<()> {
let c_key = CString::new(key).unwrap();
let res = unsafe {
@ -121,7 +121,7 @@ impl PamHandle {
/// particularly useful for getting a `PamConv` reference.
///
/// See `pam_get_item` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub fn get_item<'a, T: PamItem>(&self) -> PamResult<&'a T> {
let mut ptr: *const PamItemT = ptr::null();
let (res, item) = unsafe {
@ -143,7 +143,7 @@ impl PamHandle {
/// Note that all items are strings, except `PAM_CONV` and `PAM_FAIL_DELAY`.
///
/// See `pam_set_item` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub fn set_item_str<T: PamItem>(&mut self, item: &str) -> PamResult<()> {
let c_item = CString::new(item).unwrap();
@ -168,7 +168,7 @@ impl PamHandle {
/// This is really a specialization of `get_item`.
///
/// See `pam_get_user` in
/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
pub fn get_user(&self, prompt: Option<&str>) -> PamResult<String> {
let ptr: *mut c_char = ptr::null_mut();
let res = match prompt {

2
kanidmd/src/lib/core/mod.rs
View file

@ -6,7 +6,7 @@
//!
//! Generally, this is the "entry point" where the server begins to run, and
//! the entry point for all client traffic which is then directed to the
//! varius [`actors`].
//! various `actors`.
mod https;
mod ldaps;

2
kanidmd/src/lib/credential/totp.rs
View file

@ -57,7 +57,7 @@ impl TotpAlgo {
}
}
/// https://tools.ietf.org/html/rfc6238 which relies on https://tools.ietf.org/html/rfc4226
/// <https://tools.ietf.org/html/rfc6238> which relies on <https://tools.ietf.org/html/rfc4226>
#[derive(Debug, Clone)]
pub struct Totp {
secret: Vec<u8>,

4
kanidmd/src/lib/idm/mod.rs
View file

@ -1,6 +1,6 @@
//! The Identity Management components that are layered ontop of the [`QueryServer`]. These allow
//! The Identity Management components that are layered ontop of the [QueryServer](crate::server::QueryServer). These allow
//! rich and expressive events and transformations that are lowered into the correct/relevant
//! actions in the [`QueryServer`]. Generally this is where "Identity Management" policy and code
//! actions in the [QueryServer](crate::server::QueryServer). Generally this is where "Identity Management" policy and code
//! is implemented.
pub(crate) mod account;

2
kanidmd/src/lib/value.rs
View file

@ -1,7 +1,7 @@
//! Inside an entry, the key-value pairs are stored in these [`Value`] types. The components of
//! the [`Value`] module allow storage and transformation of various types of input into strongly
//! typed values, allows their comparison, filtering and more. It also has the code for serialising
//! these into a form for the backend that can be persistent into the [`Backend`].
//! these into a form for the backend that can be persistent into the [`Backend`](crate::be::Backend).
use crate::be::dbvalue::{
DbCidV1, DbValueCredV1, DbValueEmailAddressV1, DbValueTaggedStringV1, DbValueV1,

2
project_docs/RELEASE_AND_SUPPORT.md
View file

@ -1,6 +1,6 @@
## Release Schedule
In the alpha phase, kanidm will be released on a 3 month (quarterly) basis,
In the alpha phase, Kanidm will be released on a 3 month (quarterly) basis,
starting on July 1st 2020.
* January 1st