From e41fada28a7fa02c95e2bba6b175958d5fc02e12 Mon Sep 17 00:00:00 2001 From: Charelle Collett Date: Mon, 27 Jan 2020 22:30:09 +1000 Subject: [PATCH] Minor typo and formatting fixes. --- kanidm_book/src/SUMMARY.md | 2 +- kanidm_book/src/administrivia.md | 20 ++++++++++---------- kanidm_book/src/client_tools.md | 7 +++++-- kanidm_book/src/intro.md | 8 ++++---- kanidm_book/src/why_tls.md | 18 +++++++++--------- 5 files changed, 29 insertions(+), 26 deletions(-) diff --git a/kanidm_book/src/SUMMARY.md b/kanidm_book/src/SUMMARY.md index 93671216c..df5f6fc1f 100644 --- a/kanidm_book/src/SUMMARY.md +++ b/kanidm_book/src/SUMMARY.md @@ -1,6 +1,6 @@ # Summary -[Kanidm Administration](./intro.md) +[Introduction to Kanidm](./intro.md) - [Installing the Server](./installing_the_server.md) - [Administrative Tasks](./administrivia.md) - [Interacting with the Server](./client_tools.md) diff --git a/kanidm_book/src/administrivia.md b/kanidm_book/src/administrivia.md index d3b20c3c1..fc757fbf0 100644 --- a/kanidm_book/src/administrivia.md +++ b/kanidm_book/src/administrivia.md @@ -1,6 +1,6 @@ # Administration Tasks -There are a number of tasks that you may wish to perform as an administrator of a service like kanidm. +There are a number of tasks that you may wish to perform as an administrator of a service like Kanidm. # Backup and Restore @@ -10,7 +10,7 @@ that physical damage or mistake. Kanidm supports backup and restore of the datab ## Method 1 Method 1 involves taking a backup of the database entry content, which is then re-indexed on restore. -This is the "prefered" method. +This is the preferred method. To take the backup (assuming our docker environment) you first need to stop the instance: @@ -20,7 +20,7 @@ To take the backup (assuming our docker environment) you first need to stop the /backup/kanidm.backup.json -D /data/kanidm.db docker start -You can then restart your instance. It's advised you DO NOT modify the backup.json as it may introduce +You can then restart your instance. DO NOT modify the backup.json as it may introduce data errors into your instance. To restore from the backup: @@ -47,13 +47,13 @@ There are some cases where you may need to rename the domain. You should have co this initially in the setup, however you may have a situation where a business is changing name, merging, or other needs which may prompt this needing to be changed. -WARNING: This WILL break ALL u2f/webauthn tokens that have been enrolled, which MAY cause -accounts to be locked out and unrecoverable until further action is taken. DO NOT CHANGE -the domain_name unless REQUIRED and have a plan on how to manage these issues. +> **WARNING:** This WILL break ALL u2f/webauthn tokens that have been enrolled, which MAY cause +> accounts to be locked out and unrecoverable until further action is taken. DO NOT CHANGE +> the `domain_name` unless REQUIRED and have a plan on how to manage these issues. -WARNING: This operation can take an extensive amount of time as ALL accounts and groups -in the domain MUST have their SPN's regenerated. This will also cause a large delay in -replication once the system is restarted. +> **WARNING:** This operation can take an extensive amount of time as ALL accounts and groups +> in the domain MUST have their SPN's regenerated. This will also cause a large delay in +> replication once the system is restarted. You should take a backup before proceeding with this operation. @@ -93,7 +93,7 @@ definitions (this works even though the schema is in the same database!) -D /data/kanidm.db docker start -Generally reindexing is a rare action and should not normally be required. +Generally, reindexing is a rare action and should not normally be required. # Verification diff --git a/kanidm_book/src/client_tools.md b/kanidm_book/src/client_tools.md index 6d172b73d..ebf6b87aa 100644 --- a/kanidm_book/src/client_tools.md +++ b/kanidm_book/src/client_tools.md @@ -4,7 +4,10 @@ To interact with Kanidm as an administration, you'll need to use our command lin ## From (experimental) packages -Today we support Fedora 30/31 and OpenSUSE leap 15.1 and Tumbleweed. +Kanidm currently supports: + * Fedora 30/31 + * OpenSUSE leap 15.1 + * Tumbleweed ### SUSE @@ -39,7 +42,7 @@ After you check out the source (see github), navigate to: cargo build cargo install --path ./ -## Check the tools work. +## Check 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: diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index 2d3784651..fb9a249c4 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -1,11 +1,11 @@ -# Kanidm Administration +# Introduction to Kanidm Kanidm is an identity management server, acting as an authority on accounts and authorisation within a technical environment. -WARNING: This project is still under heavy development, and has not had a production ready -release yet. It may lose your data, be offline for some periods of time, or otherwise cause -disruptions if you aren't ready. +> **WARNING:** This project is still under heavy development, and has not had a production ready +> release yet. It may lose your data, be offline for some periods of time, or otherwise cause +> disruptions if you aren't ready. The intent of the Kanidm project is: diff --git a/kanidm_book/src/why_tls.md b/kanidm_book/src/why_tls.md index a573e79b2..99943e001 100644 --- a/kanidm_book/src/why_tls.md +++ b/kanidm_book/src/why_tls.md @@ -1,28 +1,28 @@ # Why TLS? -In the getting started you may notice that we require TLS to be configure in +You may have noticed that Kanidm requires you to configure TLS in your container - or that you provide something *with* TLS in front like haproxy. -This is due to a single setting on the server - secure_cookies +This is due to a single setting on the server - `secure_cookies` -## What are secure cookies? +## What are Secure Cookies? -Secure Cookies is a flag set in cookies that "asks" a client only to transmit them +`secure-cookies` is a flag set in cookies that "asks" a client to transmit them back to the origin site if and only if https is present in the URL. CA verification is *not* checked - you can use invalid, out of date certificates, -or even certificates where the subjectAltName does not match. But the client +or even certificates where the `subjectAltName` does not match, but the client must see https:// as the destination else it *will not* send the cookies. -## How does that affect kanidm? +## How does that affect Kanidm? Kanidm's authentication system is a stepped challenge response design, where you -initially request an "intent" to authenticated. Once you establish this intent -the server set's up a session-id into a cookie, and we inform the client of +initially request an "intent" to authenticate. Once you establish this intent, +the server sets up a session-id into a cookie, and informs the client of what authentication methods can proceed. -When you then go to continue the authentication if you do NOT have a https url +When you then go to continue the authentication, if you do NOT have a https url, the cookie with the session-id is not transmitted. The server detects this as an invalid-state request in the authentication design and immediately disconnects you from attempting to continue the authentication as you may be using an insecure