sources: add Kerberos (#10815)

* sources: introduce new property mappings per-user and group

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* sources/ldap: migrate to new property mappings

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint-fix and make gen

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* web changes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix tests

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* update tests

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* remove flatten for generic implem

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* rework migration

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint-fix

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix migrations

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* re-add field migration to property mappings

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix migrations

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* more migrations fixes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* easy fixes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* migrate to propertymappingmanager

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* ruff and small fixes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* move mapping things into a separate class

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* migrations: use using(db_alias)

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* migrations: use built-in variable

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* add docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* add release notes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix login reverse

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* refactor source flow manager matching

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* kerberos sync with mode matching

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fixup

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* finish frontend

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Optimised images with calibre/image-actions

* make web

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* add test for internal password update

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix sync tests

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix filter

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* switch to blueprints property mappings, improvements to frontend

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* some more small fixes

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix reverse

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* properly deal with password changes signals

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* actually deal with it properly

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* update docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint-fix

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* blueprints: realm as group: make it non default

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* small fixes and improvements

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* wip

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix title

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* add password backend to default flow

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* link docs page properly, add in admin interface, add suggestions for how to apply changes to a fleet of machines

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* add troubleshooting

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix default flow pass backend

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix flaky spnego tests

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* properly convert gssapi name to python str

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix unpickable types

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* make sure the last server token is returned to the client

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* lint

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/developer-docs/setup/full-dev-environment.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/browser.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update website/docs/users-sources/sources/protocols/kerberos/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* more docs review

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix missing library

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix missing library again

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix web import

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix sync

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix sync v2

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix sync v3

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

---------

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
This commit is contained in:
Marc 'risson' Schmitt
2024-10-23 17:58:29 +02:00
committed by GitHub
parent d3ebfcaf2f
commit d817c646bd
60 changed files with 5037 additions and 15 deletions

View File

@ -0,0 +1,43 @@
---
title: Browser configuration for SPNEGO
---
You might need to configure your web browser to allow SPNEGO. Following are the instructions for major browsers.
## Firefox
1. In the address bar of Firefox, type `about:config` to display the list of current configuration options.
2. In the **Filter** field, type `negotiate` to restrict the list of options.
3. Double-click the `network.negotiate-auth.trusted-uris` entry to display the **Enter string value** dialog box.
4. Enter the name of the domain against which you want to authenticate. For example, `.example.com`.
On Windows environments, to automate the deployment of this configuration use a [Group policy](https://support.mozilla.org/en-US/kb/customizing-firefox-using-group-policy-windows). On Linux or macOS systems, use [policies.json](https://support.mozilla.org/en-US/kb/customizing-firefox-using-policiesjson).
## Chrome
This section applies only for Chrome users on macOS and Linux machines. For Windows, see the instructions below.
1. Make sure you have the necessary directory created by running: `mkdir -p /etc/opt/chrome/policies/managed/`
2. Create a new `/etc/opt/chrome/policies/managed/mydomain.json` file with write privileges limited to the system administrator or root, and include the following line: `{ "AuthServerWhitelist": "*.example.com" }`.
**Note**: if using Chromium, use `/etc/chromium/policies/managed/` instead of `/etc/opt/chrome/policies/managed/`.
To automate the deployment of this configuration use a [Group policy](https://support.google.com/chrome/a/answer/187202).
## Windows / Internet Explorer
Log into the Windows machine using an account of your Kerberos realm (or administrative domain).
Open Internet Explorer, click **Tools** and then click **Internet Options**. You can also find **Internet Options** using the system search.
1. Click the **Security** tab.
2. Click **Local intranet**.
3. Click **Sites**.
4. Click **Advanced**.
5. Add your domain to the list.
6. Click the **Security tab**.
7. Click **Local intranet**.
8. Click **Custom Level**.
9. Select **Automatic login only in Intranet zone**.
To automate the deployment of this configuration use a [Group policy](https://learn.microsoft.com/en-us/previous-versions/troubleshoot/browsers/administration/how-to-configure-group-policy-preference-settings).

View File

@ -0,0 +1,130 @@
---
title: Kerberos
---
This source allows users to enroll themselves with an existing Kerberos identity.
## Preparation
The following placeholders will be used:
- `REALM.COMPANY` is the Kerberos realm.
- `authentik.company` is the FQDN of the authentik install.
Examples are shown for an MIT Krb5 KDC system; you might need to adapt them for you Kerberos installation.
There are three 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](./browser.md) and their Kerberos credentials.
You can choose to use one or several of those methods.
## Common settings
In the authentik Admin interface, under **Directory** -> **Federation and Social login**, create a new source of type Kerberos with these settings:
- Name: a value of your choosing. This name is 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: define how Kerberos users get matched to authentik users.
- Group matching mode: define 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.
Note that 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 both a principal (a unique identity that represents a user or service in a Kerberos network) for authentik and a keytab file:
```bash
$ kadmin
> 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
```
In authentik, configure these extra options:
- Sync users: enable it
- Sync principal: `authentik/admin@REALM.COMPANY`
- Sync keytab: the base64-encoded 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.
## SPNEGO
You need to create both a principal (a unique identity that represents a user or service in a Kerberos network) for authentik and a keytab file:
```bash
$ kadmin
> add_principal HTTP/authentik.company@REALM.COMPANY
> ktadd -k /tmp/authentik.keytab HTTP/authentik.company@REALM.COMPANY
> exit
$ cat /tmp/authentik.keytab | base64
$ rm /tmp/authentik.keytab
```
In authentik, configure these extra options:
- SPNEGO keytab: the base64-encoded keytab created above.
If you do not wish to use a keytab, you can also configure authentik to use an existing credentials cache.
You can also override the SPNEGO server name if needed.
You might 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 might want to force the use of a specific server name. You can do so with the **Custom server name** option. The value must be in the form of `HTTP@authentik.company`.
If not specified, the server name defaults to trying out all entries in the keytab/credentials cache until a valid server name is found.
## 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 is automatically 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 with external sources.
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
Realms other than the one configured on the source are ignored, and log in is not allowed.
- 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 property mappings are configured with the most common Kerberos setups.
### Expression data
The following variable is available to Kerberos source property mappings:
- `principal`: a Python string containing the Kerberos principal. For example `alice@REALM.COMPANY` or `HTTP/authentik.company@REALM.COMPANY`.
## Troubleshooting
You can start authentik with the `KRB5_TRACE=/dev/stderr` environment variable for Kerberos to print errors in the logs.