update docs

Signed-off-by: Marc 'risson' Schmitt <[email protected]>

website/docs/sources/index.md

@@ -9,7 +9,7 @@ Sources allow you to connect authentik to an external user directory. Sources ca
 
 Sources are in the following general categories:
 
--   **Protocols** ([LDAP](./ldap/index.md), [OAuth](./oauth/index.md), [SAML](./saml/index.md), and [SCIM](./scim/index.md))
+-   **Protocols** ([Kerberos](./kerberos/index.md), [LDAP](./ldap/index.md), [OAuth](./oauth/index.md), [SAML](./saml/index.md) and [SCIM](./scim/index.md))
 -   [**Property mappings**](./property-mappings/index.md) or how to import data from a source
 -   **Directory synchronization** (Active Directory, FreeIPA)
 -   **Social logins** (Apple, Discord, Twitch, Twitter, and many others)

website/docs/sources/kerberos/index.md

@@ -13,54 +13,114 @@ The following placeholders will be used:
 
 Examples are shown for an MIT Krb5 KDC, you may need to adapt them for you Kerberos installation.
 
-## Kerberos configuration
+There are 3 ways to use the Kerberos source:
+
+-   As a password backend, where users can log in to authentik with their Kerberos password.
+-   As a directory source, where users are synced from the KDC.
+-   With SPNEGO, where users can log in to authentik with their browser and their Kerberos credentials.
+
+You can choose to use one or several of those methods.
+
+## Common settings
+
+In the Admin interface, under **Directory** -> **Federation and Social login**, create a new source of type Kerberos with these settings:
+
+-   Name: a value of your choosing, which will be shown to users if you use the SPNEGO login method
+-   Slug: `kerberos`
+-   Realm: `REALM.COMPANY`
+-   Kerberos 5 configuration: If you need to override the default Kerberos configuration, you can do it here. See [man krb5.conf(5)](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html) for the expected format.
+-   User matching mode: how Kerberos users get matched to authentik users.
+-   Group matching mode: how Kerberos groups (specified via property mappings) get matched to authentik groups.
+-   User property mappings and group property mappings: see [Source property mappings](../property-mappings/index.md) and the section below for details.
+
+## Password backend
+
+No extra configuration is required. Simply select the Kerberos backend in the password stage of your flow.
+
+This only works on users that have been linked to this source, i.e. they must have been created via sync or via SPNEGO.
+
+## Sync
+
+The sync process uses the [Kerberos V5 administration system](https://web.mit.edu/kerberos/krb5-latest/doc/admin/database.html) to list users. Your KDC must support it to sync users with this source.
 
 You need to create a principal for authentik and a keytab:
 
 ```bash
 $ kadmin
-> add_principal HTTP/authentik.company@REALM.COMPANY
-> ktadd -k /tmp/authentik.keytab HTTP/authentik.company@REALM.COMPANY
+> add_principal authentik/admin@REALM.COMPANY
+> ktadd -k /tmp/authentik.keytab authentik/admin@REALM.COMPANY
 > exit
 $ cat /tmp/authentik.keytab | base64
+$ rm /tmp/authentik.keytab
 ```
 
-Keep the base64-encoded keytab for later.
-
-## authentik configuration
+In authentik, you need to configure these extra options:
 
-In the Admin interface, under **Directory** -> **Federation and Social login**, create a new source of type SPNEGO with these settings:
+-   Sync users: enable it
+-   Sync principal: `authentik/[email protected]`
+-   Sync keytab: the base64-encoded keytab created above.
 
--   Name: a value of your choosing that will be shown to users
--   Slug: `kerberos`
--   Keytab: the keytab created above
+If you do not wish to use a keytab, you can also configure authentik to authenticate using a password, or an existing credentials cache.
 
-## Finalizing
+## SPNEGO
 
-You may need to configure your web browser to allow SPNEGO. Check out [our documentation](./browser) on how to do so. You can now login to authentik using SPNEGO.
+You need to create a principal for authentik and a keytab:
 
-## Note on user linking
+```bash
+$ kadmin
+> add_principal HTTP/[email protected]
+> ktadd -k /tmp/authentik.keytab HTTP/[email protected]
+> exit
+$ cat /tmp/authentik.keytab | base64
+$ rm /tmp/authentik.keytab
+```
 
-When editing the source, you can choose the **User matching mode**. For the SPNEGO source, the unique identifier will be the user principal, i.e. `[email protected]`, the username will be `alice` and the email will be empty. You can enable **Guess email** under **Advanced protocol settings**, in which case the email would be `[email protected]`. This option does not perform any kind of validation, use with care.
+In authentik, you need to configure these extra options:
 
-## Advanced configuration
+-   SPNEGO keytab: the base64-encoded keytab created above.
 
-The following section is intended for advanced users with specific needs and showcases some exotic configurations.
+If you do not wish to use a keytab, you can also configure authentik to use an existing credentials cache.
 
-### Custom Kerberos configuration
+You can also override the SPNEGO server name if needed.
 
-authentik bundles a sensible default Kerberos configuration which should work with most implementations. If you need to override that, you can mount your own `krb5.conf` in the authentik containers at `/etc/krb5.conf`.
+You may need to configure your web browser to allow SPNEGO. Check out [our documentation](./browser.md) on how to do so. You can now login to authentik using SPNEGO.
 
 ### Custom server name
 
 If your authentik instance is accessed from multiple domains, you may want to force the use of a specific server name. You can do so with this option. It must be in the form of `HTTP/domain@REALM`.
 
 If not specified, this defaults to trying out all entries in the keytab/credentials cache until a valid server name is found.
 
-### Mounted keytab
+## Extra settings
+
+There are some extra settings you can configure:
+
+-   Update internal password on login: when a user logs in to authentik using the Kerberos source as a password backend, their internal authentik password will be updated to match the one from Kerberos.
+-   Use password writeback: when a user changes their password in authentik, their Kerberos password will be updated to match the one from authentik. This is only available if synchronization is configured.
+
+## Kerberos source property mappings
+
+See the [overview](../property-mappings/index.md) for information on how property mappings work.
+
+By default, authentik ships with [pre-configured mappings](#built-in-property-mappings) for the most common Kerberos setups. These mappings can be found on the Kerberos Source Configuration page in the Admin interface.
+
+### Built-in property mappings
+
+Kerberos property mappings are used when you define a Kerberos source. These mappings define which Kerberos property maps to which authentik property. By default, the following mappings are created:
+
+-   authentik default Kerberos User Mapping: Add realm as group
+    The realm of the user will be added as a group for that user.
+-   authentik default Kerberos User Mapping: Ignore other realms
+    Other realms than the one configured on the source will be ignored, and not be allowed to log in.
+-   authentik default Kerberos User Mapping: Ignore system principals
+    System principals such as `K/M` or `kadmin/admin` are ignored.
+-   authentik default Kerberos User Mapping: Multipart principals as service accounts
+    Multipart principals (for example: `HTTP/authentik.company`) have their user type set to service account.
+
+These are configured with the most common Kerberos setups.
 
-If you prefer to mount your keytab in the authentik containers instead of storing in the database, you can do so by specifying `FILE:/path/to/keytab` instead of the base64-encoded keytab. If the field is left empty, authentik will use the default keytab path configuration method used by MIT Krb5.
+### Expression data
 
-### Custom credentials cache
+The following variables are available to Kerberos source property mappings:
 
-By default, authentik creates a private credentials cache file for each source of type SPNEGO. If you'd like to customize that path or use your own credentials cache to avoid giving out a keytab to authentik, you can do so by setting this option to `TYPE:residual` of where the credentials cache is located. The format is the same as MIT Krb5, for instance: `FILE:/path/to/ccache`.
+-   `principal`: a Python string containing the Kerberos principal. For example `[email protected]` or `HTTP/[email protected]`.

website/docs/sources/property-mappings/index.md

@@ -6,6 +6,7 @@ Source property mappings allow you to modify or gather extra information from so
 
 This page is an overview of how property mappings work. For information about specific protocol, please refer to each protocol page:
 
+-   [Kerberos](../kerberos/#ldap-source-property-mappings)
 -   [LDAP](../ldap/#ldap-source-property-mappings)
 -   [OAuth](../oauth/#oauth-source-property-mappings)
 -   [SAML](../saml/#saml-source-property-mappings)