From 6ff74c976e887c2a8336f1ffa2e3781d309f8b95 Mon Sep 17 00:00:00 2001 From: James Hodgkinson Date: Sat, 24 Jul 2021 11:12:35 +1000 Subject: [PATCH] Auto-publishing the book and rustdoc. (#534) --- .github/workflows/kanidm_book.yml | 47 +++++++ README.md | 2 +- kanidm_book/src/SUMMARY.md | 35 +++-- kanidm_book/src/accounts_and_groups.md | 2 +- kanidm_book/src/client_tools.md | 68 +--------- kanidm_book/src/installing_client_tools.md | 63 +++++++++ kanidm_book/src/installing_the_server.md | 127 +++---------------- kanidm_book/src/intro.md | 92 +++++++------- kanidm_book/src/ldap.md | 6 +- kanidm_book/src/pam_and_nsswitch.md | 39 ++---- kanidm_book/src/password_quality.md | 27 ++-- kanidm_book/src/security_hardening.md | 31 ++++- kanidm_book/src/server_configuration.md | 70 ++++++++++ kanidm_book/src/ssh_key_dist.md | 2 +- kanidm_proto/src/v1.rs | 2 +- kanidm_tools/Cargo.toml | 1 + kanidm_unix_int/pam_kanidm/src/pam/module.rs | 12 +- kanidmd/src/lib/core/mod.rs | 2 +- kanidmd/src/lib/credential/totp.rs | 2 +- kanidmd/src/lib/idm/mod.rs | 4 +- kanidmd/src/lib/value.rs | 2 +- project_docs/RELEASE_AND_SUPPORT.md | 2 +- 22 files changed, 336 insertions(+), 302 deletions(-) create mode 100644 .github/workflows/kanidm_book.yml create mode 100644 kanidm_book/src/installing_client_tools.md create mode 100644 kanidm_book/src/server_configuration.md diff --git a/.github/workflows/kanidm_book.yml b/.github/workflows/kanidm_book.yml new file mode 100644 index 000000000..0361c437e --- /dev/null +++ b/.github/workflows/kanidm_book.yml @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index cd1250045..1b3fc7a39 100644 --- a/README.md +++ b/README.md @@ -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]. diff --git a/kanidm_book/src/SUMMARY.md b/kanidm_book/src/SUMMARY.md index 22b8dd77d..143a2e792 100644 --- a/kanidm_book/src/SUMMARY.md +++ b/kanidm_book/src/SUMMARY.md @@ -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) diff --git a/kanidm_book/src/accounts_and_groups.md b/kanidm_book/src/accounts_and_groups.md index 4f6604a69..e8bc17c4f 100644 --- a/kanidm_book/src/accounts_and_groups.md +++ b/kanidm_book/src/accounts_and_groups.md @@ -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 diff --git a/kanidm_book/src/client_tools.md b/kanidm_book/src/client_tools.md index 03f41e84c..a25d8dfbc 100644 --- a/kanidm_book/src/client_tools.md +++ b/kanidm_book/src/client_tools.md @@ -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: diff --git a/kanidm_book/src/installing_client_tools.md b/kanidm_book/src/installing_client_tools.md new file mode 100644 index 000000000..8dbabc4b5 --- /dev/null +++ b/kanidm_book/src/installing_client_tools.md @@ -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). \ No newline at end of file diff --git a/kanidm_book/src/installing_the_server.md b/kanidm_book/src/installing_the_server.md index 57b4fd48c..7592aab56 100644 --- a/kanidm_book/src/installing_the_server.md +++ b/kanidm_book/src/installing_the_server.md @@ -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 + - + - -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) + diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index c0c14179e..bc9b3dfcd 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -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, diff --git a/kanidm_book/src/ldap.md b/kanidm_book/src/ldap.md index 7d1ac512e..af1a26921 100644 --- a/kanidm_book/src/ldap.md +++ b/kanidm_book/src/ldap.md @@ -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. diff --git a/kanidm_book/src/pam_and_nsswitch.md b/kanidm_book/src/pam_and_nsswitch.md index 7aae9df53..dd7ab1fb8 100644 --- a/kanidm_book/src/pam_and_nsswitch.md +++ b/kanidm_book/src/pam_and_nsswitch.md @@ -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. diff --git a/kanidm_book/src/password_quality.md b/kanidm_book/src/password_quality.md index 764615cfb..f848603cf 100644 --- a/kanidm_book/src/password_quality.md +++ b/kanidm_book/src/password_quality.md @@ -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 [ ...] diff --git a/kanidm_book/src/security_hardening.md b/kanidm_book/src/security_hardening.md index b7971ebe1..8c41533dd 100644 --- a/kanidm_book/src/security_hardening.md +++ b/kanidm_book/src/security_hardening.md @@ -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. \ No newline at end of file diff --git a/kanidm_book/src/server_configuration.md b/kanidm_book/src/server_configuration.md new file mode 100644 index 000000000..989b2ecf3 --- /dev/null +++ b/kanidm_book/src/server_configuration.md @@ -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 \ No newline at end of file diff --git a/kanidm_book/src/ssh_key_dist.md b/kanidm_book/src/ssh_key_dist.md index 91b45375d..80b2fd94d 100644 --- a/kanidm_book/src/ssh_key_dist.md +++ b/kanidm_book/src/ssh_key_dist.md @@ -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: diff --git a/kanidm_proto/src/v1.rs b/kanidm_proto/src/v1.rs index 197522fdb..6744c45c7 100644 --- a/kanidm_proto/src/v1.rs +++ b/kanidm_proto/src/v1.rs @@ -717,7 +717,7 @@ pub struct TotpSecret { } impl TotpSecret { - /// 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! diff --git a/kanidm_tools/Cargo.toml b/kanidm_tools/Cargo.toml index 50e3b5b43..4217dafd5 100644 --- a/kanidm_tools/Cargo.toml +++ b/kanidm_tools/Cargo.toml @@ -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" diff --git a/kanidm_unix_int/pam_kanidm/src/pam/module.rs b/kanidm_unix_int/pam_kanidm/src/pam/module.rs index 10d4c1902..994768ff5 100755 --- a/kanidm_unix_int/pam_kanidm/src/pam/module.rs +++ b/kanidm_unix_int/pam_kanidm/src/pam/module.rs @@ -68,7 +68,7 @@ pub type PamResult = Result; /// 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 +/// 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 + /// 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 + /// pub fn set_data(&self, key: &str, data: Box) -> 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 + /// 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 + /// pub fn set_item_str(&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 + /// pub fn get_user(&self, prompt: Option<&str>) -> PamResult { let ptr: *mut c_char = ptr::null_mut(); let res = match prompt { diff --git a/kanidmd/src/lib/core/mod.rs b/kanidmd/src/lib/core/mod.rs index f7152f7cf..40871090c 100644 --- a/kanidmd/src/lib/core/mod.rs +++ b/kanidmd/src/lib/core/mod.rs @@ -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; diff --git a/kanidmd/src/lib/credential/totp.rs b/kanidmd/src/lib/credential/totp.rs index 1ae492497..82f361e35 100644 --- a/kanidmd/src/lib/credential/totp.rs +++ b/kanidmd/src/lib/credential/totp.rs @@ -57,7 +57,7 @@ impl TotpAlgo { } } -/// https://tools.ietf.org/html/rfc6238 which relies on https://tools.ietf.org/html/rfc4226 +/// which relies on #[derive(Debug, Clone)] pub struct Totp { secret: Vec, diff --git a/kanidmd/src/lib/idm/mod.rs b/kanidmd/src/lib/idm/mod.rs index 876ba2d10..a5ec365a5 100644 --- a/kanidmd/src/lib/idm/mod.rs +++ b/kanidmd/src/lib/idm/mod.rs @@ -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; diff --git a/kanidmd/src/lib/value.rs b/kanidmd/src/lib/value.rs index 493681b3c..6283f14bc 100644 --- a/kanidmd/src/lib/value.rs +++ b/kanidmd/src/lib/value.rs @@ -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, diff --git a/project_docs/RELEASE_AND_SUPPORT.md b/project_docs/RELEASE_AND_SUPPORT.md index 207fc6984..f27e31776 100644 --- a/project_docs/RELEASE_AND_SUPPORT.md +++ b/project_docs/RELEASE_AND_SUPPORT.md @@ -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