Improve the readme (#1679)

* Improvements to the readme

README.md

@@ -6,65 +6,73 @@
 
 ## About
 
-Kanidm is a simple and secure identity management platform, which provides services to allow other
+Kanidm is a simple and secure identity management platform, allowing other applications and services
-systems and application to authenticate against. The project aims for the highest levels of
+to offload the challenge of authenticating and storing identities to Kanidm.
-reliability, security and ease of use.
 
-The goal of this project is to be a complete identity management provider, covering the broadest
+The goal of this project is to be a complete identity provider, covering the broadest possible set
-possible set of requirements and integrations. You should not need any other components (like
+of requirements and integrations. You should not need any other components (like Keycloak) when you
-Keycloak) when you use Kanidm. We want to create a project that will be suitable for everything from
+use Kanidm - we already have everything you need!
-personal home deployments, to the largest enterprise needs.
 
 To achieve this we rely heavily on strict defaults, simple configuration, and self-healing
-components.
+components. This allows Kanidm to run from small home labs, for families, small business, and all
+the way to the largest enterprise needs.
 
-The project is still growing and some areas are developing at a fast pace. The core of the server
+If you want to host your own authentication service, then Kanidm is for you!
-however is reliable and we make all effort to ensure upgrades will always work.
+
+<details><summary>Supported Features</summary>
 
 Kanidm supports:
 
+- Webauthn (passkeys) for secure cryptographic authentication
 - Oauth2/OIDC Authentication provider for web SSO
-- Read only LDAPS gateway
+- Oauth Application Portal/Gateway allowing easy access to linked applications
-- Linux/Unix integration (with offline authentication)
+- Linux/Unix integration with offline authentication
 - SSH key distribution to Linux/Unix systems
-- RADIUS for network authentication
+- RADIUS for network and VPN authentication
-- Passkeys / Webauthn for secure cryptographic authentication
+- Read only LDAPS gateway for Legacy Systems
-- A self service web ui
+- Complete CLI tooling for Administration
-- Complete CLI tooling for administration
+- User Self Service the WebUI
 
-If you want to host your own centralised authentication service, then Kanidm is for you!
+</details>
 
 ## 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 read more about what Kanidm can do, you should read our documentation.
 
 - [Kanidm book (Latest stable)](https://kanidm.github.io/kanidm/stable/)
-- [Kanidm book (Latest commit)](https://kanidm.github.io/kanidm/master/)
 
-We also publish
+We also have a set of
 [support guidelines](https://github.com/kanidm/kanidm/blob/master/project_docs/RELEASE_AND_SUPPORT.md)
-for what the project will support.
+for what the project team will support
 
 ## Code of Conduct / Ethics
 
-See our [code of conduct]
+All interactions with the project are covered by our [code of conduct].
 
-See our documentation on [rights and ethics]
+When we develop features we follow our projects guidelines on [rights and ethics]
 
 [code of conduct]: https://github.com/kanidm/kanidm/blob/master/CODE_OF_CONDUCT.md
 [rights and ethics]: https://github.com/kanidm/kanidm/blob/master/project_docs/ethics/README.md
 
 ## Getting in Contact / Questions
 
-We have a [gitter community channel] where we can talk. Firstyear is also happy to answer questions
+We have a [gitter community channel] where project members are always happy to answer questions.
-via email, which can be found on their github profile.
+Alternately you can open a new [github discussion].
 
 [gitter community channel]: https://gitter.im/kanidm/community
+[github discussion]: https://github.com/kanidm/kanidm/discussions
+
+## What does Kanidm mean?
+
+Kanidm is a portmanteau of 'kani' and 'idm'. Kani is Japanese for crab, related to Rust's mascot
+ferris the crab. identity management is often abbreviated to 'idm', and is a common industry term
+for these services.
+
+Kanidm is pronounced as "kar - nee - dee - em".
 
 ## Comparison with other services
 
-### LLDAP
+<details><summary>LLDAP</summary>
-
 [LLDAP](https://github.com/nitnelave/lldap) is a similar project aiming for a small and easy to
 administer LDAP server with a web administration portal. Both projects use the
 [Kanidm LDAP bindings](https://github.com/kanidm/ldap3), and have many similar ideas.
@@ -77,20 +85,23 @@ may make it easier to administer and deploy for you.
 If Kanidm is too complex for your needs, you should check out LLDAP as a smaller alternative. If you
 want a project which has a broader feature set out of the box, then Kanidm might be a better fit.
 
-### 389-ds / OpenLDAP
+</details>
 
+<details><summary>389-ds / OpenLDAP</summary>
 Both 389-ds and OpenLDAP are generic LDAP servers. This means they only provide LDAP and you need to
-bring your own IDM configuration on top.
+bring your own IDM components - you need your own OIDC portal, webui's for self service, commandline
+tools to administer and more.
 
 If you need the highest levels of customisation possible from your LDAP deployment, then these are
-probably better alternatives. If you want a service that is easier to setup and focused on IDM, then
+probably better alternatives. If you want a service that is easy to setup and focused on IDM, then
 Kanidm is a better choice.
 
 Kanidm was originally inspired by many elements of both 389-ds and OpenLDAP. Already Kanidm is as
-fast as (or faster than) 389-ds for performance and scaling.
+fast as (or faster than) 389-ds for performance and scaling as a directory service.
 
-### FreeIPA
+</details>
 
+<details><summary>FreeIPA</summary>
 FreeIPA is another identity management service for Linux/Unix, and ships a huge number of features
 from LDAP, Kerberos, DNS, Certificate Authority, and more.
 
@@ -103,16 +114,30 @@ Kanidm is probably for you. In testing with 3000 users + 1500 groups, Kanidm is
 search operations and 5 times faster for modification and addition of entries (your results may
 differ however, but generally Kanidm is much faster than FreeIPA).
 
+</details>
+
+<details><summary>Keycloak</summary>
+Keycloak is an OIDC/Oauth2/SAML provider. It allows you to layer on Webauthn to existing IDM systems.
+Keycloak can operate as a stand alone IDM but generally is a component attached to an existing LDAP
+server or similar.
+
+Keycloak requires a significant amount of configuration and experience to deploy. It allows high
+levels of customisation to every detail of it's authentication work flows, which makes it harder to
+start with in many cases.
+
+Kanidm does NOT require Keycloak to provide services such as Oauth2 and integrates many of the
+elements in a simpler and correct way out of the box in comparison.
+
+<details>
+
 ## Developer Getting Started
 
-If you want to develop on the server, there is a getting started [guide for developers]. IDM is a
+If you want to contribute to Kanidm there is a getting started [guide for developers]. IDM is a
 diverse topic and we encourage contributions of many kinds in the project, from people of all
 backgrounds.
 
+When developing the server you should refer to the latest commit documentation instead.
+
+- [Kanidm book (Latest commit)](https://kanidm.github.io/kanidm/master/)
+
 [guide for developers]: https://kanidm.github.io/kanidm/master/DEVELOPER_README.html
-
-## What does Kanidm mean?
-
-The original project name was rsidm while it was a thought experiment. Now that it's growing and
-developing, we gave it a better project name. Kani is Japanese for "crab". Rust's mascot is a crab.
-IDM is the common industry term for identity management services.

book/src/developers/designs/architecture.md

@@ -122,9 +122,9 @@ This operation returns a result (9) to the backend, which is then filtered up to
 
 (11) Provided all operations to this point have been successful, we now apply post write plugins
 which may enforce or generate different properties in the transaction. This is similar to the pre
-plugins, but allows different operations. For example, a post plugin ensures uuid reference types are
+plugins, but allows different operations. For example, a post plugin ensures uuid reference types
-consistent and valid across the set of changes in the database. The most critical is memberof, which
+are consistent and valid across the set of changes in the database. The most critical is memberof,
-generates reverse reference links from entries to their group memberships, enabling fast rbac
+which generates reverse reference links from entries to their group memberships, enabling fast rbac
 operations. These are done as post plugins because at this point internal searches can now yield and
 see the modified entries that we have just added to the indexes and datatables, which is important
 for consistency (and simplicity) especially when you consider batched operations.

book/src/developers/designs/identifiable_secrets.md

@@ -1,25 +1,35 @@
 # Identifiable Secrets
 
-Kanidm tokens should have a unique pattern, making them easy to recognize. This is crucial for security systems that aim to prevent incorrect credential storage. Without a distinct pattern, like with bare JWTs that look like any base64-encoded data, we risk false alarms.
+Kanidm tokens should have a unique pattern, making them easy to recognize. This is crucial for
+security systems that aim to prevent incorrect credential storage. Without a distinct pattern, like
+with bare JWTs that look like any base64-encoded data, we risk false alarms.
 
 ## The Kanidm pattern
 
 ```text
 kanidm_<CREDENTIAL>
 ```
+
 Where:
 
 - `<CREDENTIAL>` is the actual credential.
 
-We can make this compatible with current validators by checking if the submitted token starts with `kanidm_`. If it does, we remove that part and continue with validation.
+We can make this compatible with current validators by checking if the submitted token starts with
+`kanidm_`. If it does, we remove that part and continue with validation.
 
-Regular expressions should NOT be used. Credentials are valid only in context, so the auth check knows it's looking for `kanidm_<CREDENTIAL>`. A simple string match and split is more efficient in this case.
+Regular expressions should NOT be used. Credentials are valid only in context, so the auth check
+knows it's looking for `kanidm_<CREDENTIAL>`. A simple string match and split is more efficient in
+this case.
 
 ## Other implementations
 
-[AWS token IDs have follow designated patterns](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html), say `AKIA` for IAM key, or `ASIA` for a short-term token.
+[AWS token IDs have follow designated patterns](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html),
+say `AKIA` for IAM key, or `ASIA` for a short-term token.
 
-Sadly we can't join [GitHub's secret scanning program](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/secret-scanning-partner-program) because we don't run a single platform. It would be great if they could support token introspection and issuer communication.
+Sadly we can't join
+[GitHub's secret scanning program](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/secret-scanning-partner-program)
+because we don't run a single platform. It would be great if they could support token introspection
+and issuer communication.
 
 ## Further Reading
 

book/src/troubleshooting.md

@@ -73,13 +73,16 @@ RUST_LOG=debug kanidm login --name anonymous
 
 ## Reverse Proxies not sending HTTP/1.1 requests
 
-NGINX (and probably other proxies) send HTTP/1.0 requests to the upstream server by default. This'll lead to errors like this in your proxy logs:
+NGINX (and probably other proxies) send HTTP/1.0 requests to the upstream server by default. This'll
+lead to errors like this in your proxy logs:
 
 ```text
 *17 upstream prematurely closed connection while reading response header from upstream, client: 172.19.0.1, server: example.com, request: "GET / HTTP/1.1", upstream: "https://172.19.0.3:8443/", host: "example.com:8443"
 ```
 
-The fix for NGINX is to set the [proxy_http_version](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) to `1.1`. This can go in the same block as the `proxy_pass` option.
+The fix for NGINX is to set the
+[proxy_http_version](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version)
+to `1.1`. This can go in the same block as the `proxy_pass` option.
 
 ```text
 proxy_http_version 1.1