docs tweaks, renaming integrations (#1228)

kanidm_book/src/SUMMARY.md

@@ -1,7 +1,7 @@
 # Kanidm
 
 - [Introduction to Kanidm](intro.md)
-- [Glossary of Technical Terms](glossary.md)
+- [Frequently Asked Questions](frequently_asked_questions.md)
 - [Installing the Server](installing_the_server.md)
   - [Choosing a Domain Name](choosing_a_domain_name.md)
   - [Preparing for your Deployment](prepare_the_server.md)
@@ -10,8 +10,8 @@
   - [Platform Security Hardening](security_hardening.md)
 - [Client Tools](client_tools.md)
   - [Installing client tools](installing_client_tools.md)
-- [Accounts and Groups](accounts_and_groups.md)
 - [Administration](administrivia.md)
+  - [Accounts and Groups](accounts_and_groups.md)
   - [Backup and Restore](backup_restore.md)
   - [Database Maintenance](database_maint.md)
   - [Domain Rename](domain_rename.md)
@@ -21,20 +21,20 @@
   - [SSH Key Distribution](ssh_key_dist.md)
   - [The Recycle Bin](recycle_bin.md)
   - [Why TLS?](why_tls.md)
-- [Frequently Asked Questions](frequently_asked_questions.md)
 - [Troubleshooting](troubleshooting.md)
+- [Glossary of Technical Terms](glossary.md)
 
-# Integrations
+# Services
 
 - [Oauth2](integrations/oauth2.md)
 - [PAM and nsswitch](integrations/pam_and_nsswitch.md)
 - [RADIUS](integrations/radius.md)
 - [LDAP](integrations/ldap.md)
-- [Traefik](integrations/traefik.md)
 
 # Integration Examples
 
 - [Kubernetes Ingress](examples/k8s_ingress_example.md)
+- [Traefik](integrations/traefik.md)
 
 # For Developers
 
@@ -49,4 +49,4 @@
 ## Packaging
 
 - [Packaging](packaging.md)
-- [Debian/Ubuntu](packaging_debs.md)
+  - [Debian/Ubuntu](packaging_debs.md)

kanidm_book/src/frequently_asked_questions.md

@@ -2,6 +2,13 @@
 
 ... or ones we think people *might* ask.
 
+## Why disallow HTTP (without TLS) between my load balancer and Kanidm?
+
+Because Kanidm is one of the keys to a secure network, and insecure connections
+to them are not best practice.
+
+Please refer to [Why TLS?](why_tls.md) for a longer explanation.
+
 ## Why so many crabs?
 
 It's [a rust thing](https://rustacean.net).
@@ -16,4 +23,4 @@ Don't [ask](https://www.youtube.com/watch?v=0QaAKi0NFkA). They just [do](https:/
 
 ## Why won't you take this FAQ thing seriously?
 
-Look, people just haven't asked many questions yet.
+Look, people just haven't asked many questions yet.

kanidm_book/src/integrations/oauth2.md

@@ -57,22 +57,22 @@ In general Kanidm requires that your resource server supports:
 
 Kanidm will expose its OAuth2 APIs at the following URLs:
 
-* user auth url: https://idm.example.com/ui/oauth2
+* user auth url: `https://idm.example.com/ui/oauth2`
-* api auth url: https://idm.example.com/oauth2/authorise
+* api auth url: `https://idm.example.com/oauth2/authorise`
-* token url: https://idm.example.com/oauth2/token
+* token url: `https://idm.example.com/oauth2/token`
-* rfc7662 token introspection url: https://idm.example.com/oauth2/token/introspect
+* rfc7662 token introspection url: `https://idm.example.com/oauth2/token/introspect`
-* rfc7009 token revoke url: https://idm.example.com/oauth2/token/revoke
+* rfc7009 token revoke url: `https://idm.example.com/oauth2/token/revoke`
 
 OpenID Connect discovery - you need to substitute your OAuth2 client id in the following
 urls:
 
-* OpenID connect issuer uri: https://idm.example.com/oauth2/openid/:client\_id:/
+* OpenID connect issuer uri: `https://idm.example.com/oauth2/openid/:client\_id:/`
-* OpenID connect discovery:  https://idm.example.com/oauth2/openid/:client\_id:/.well-known/openid-configuration
+* OpenID connect discovery:  `https://idm.example.com/oauth2/openid/:client\_id:/.well-known/openid-configuration`
 
 For manual OpenID configuration:
 
-* OpenID connect userinfo:   https://idm.example.com/oauth2/openid/:client\_id:/userinfo
+* OpenID connect userinfo:   `https://idm.example.com/oauth2/openid/:client\_id:/userinfo`
-* token signing public key:  https://idm.example.com/oauth2/openid/:client\_id:/public\_key.jwk
+* token signing public key:  `https://idm.example.com/oauth2/openid/:client\_id:/public\_key.jwk`
 
 ### Scope Relationships
 
@@ -126,9 +126,12 @@ You can create a scope map with:
     kanidm system oauth2 update_scope_map <name> <kanidm_group_name> [scopes]...
     kanidm system oauth2 update_scope_map nextcloud nextcloud_admins admin
 
-> **WARNING**
+{{#template
-> If you are creating an OpenID Connect (OIDC) resource server you *MUST* provide a
+    ../templates/kani-warning.md
-> scope map named 'openid'. Without this, OpenID clients *WILL NOT WORK*
+    imagepath=../images
+    title=WARNING
+    text=If you are creating an OpenID Connect (OIDC) resource server you <b>MUST</b> provide a scope map named <code>openid</code>. Without this, OpenID clients <b>WILL NOT WORK</b>
+}}
 
 > **HINT**
 > OpenID connect allows a number of scopes that affect the content of the resulting
@@ -186,8 +189,8 @@ it may be necessary to disable these on a per-resource server basis. Disabling t
 one resource server will not affect others.
 
 {{#template
-    templates/kani-warning.md
+    ../templates/kani-warning.md
-    imagepath=images
+    imagepath=../images
     title=WARNING
     text=Changing these settings MAY have serious consequences on the security of your resource server. You should avoid changing these if at all possible!
 }}
@@ -296,10 +299,11 @@ these to a group with a scope map due to Velociraptors high impact.
 > Vouch proxy requires a unique identifier but does not use the proper scope, "sub". It uses the fields
 > "username" or "email" as primary identifiers instead. As a result, this can cause user or deployment issues, at
 > worst security bypasses. You should avoid Vouch Proxy if possible due to these issues.
-> * https://github.com/vouch/vouch-proxy/issues/309
+>
-> * https://github.com/vouch/vouch-proxy/issues/310
+> * <https://github.com/vouch/vouch-proxy/issues/309>
+> * <https://github.com/vouch/vouch-proxy/issues/310>
 
-_You need to run at least the version 0.37.0_.
+Note: **You need to run at least the version 0.37.0**
 
 Vouch Proxy supports multiple OAuth and OIDC login providers.
 To configure it you need to pass:
@@ -321,4 +325,3 @@ oauth:
 The `email` scope needs to be passed and thus the mail attribute needs to exist on the account:
 
     kanidm person update <ID> --mail "YYYY@somedomain.com" --name idm_admin
-