Dominic R
899994027d
* core: add hash_password command and password_hash bootstrap support * core: prevent hash format exposure in validation error * core: remove redundant password length check * core: remove extra blank lines from hash_password command * core: add password_hash serializer tests, refine validation and imports * core: add null password fields test, add hash warning to docs * core: move hash validation to User.set_password_from_hash method * core: emit password_changed signal in set_password_from_hash * website: remove redundant hash security warning * core: wrap conflict error message for translation * core: wrap invalid hash error message for translation * web, core: add set_password_hash API endpoint and admin UI * core: simplify password_hash check to None comparison * core: use None check for password conflict validation * website: clarify Docker Compose $ escaping for .env vs compose.yml * website: lint * web: lint * core: add nosec comment for empty password string in signal * core: lint * web: Fix Password Hash help text * sources/kerberos,ldap: Gergo's review * add testing for ^^ and type fix * more general signal tests; not provider specific * only used in tests * add warning * we can do this * signals fix???? * core, web, website: review fixes * style(docs): format automated install guide * web: restore modal invoker import after rebase Co-authored-by: Codex <codex@openai.com> * fix generated clients * core: trim hash password command tests * core: add password hash permission * core: cover service account password hashes * web: remove password hash form * core: regenerate password hash migration * core: reuse password serializer for hashes * docs: clarify hashed password imports * Regenerate * core: deduplicate user serializer writes * core: deduplicate password update actions * core: deduplicate password change signaling * tests: reuse password hash API helper * tests: reuse SSF credential assertions * docs: centralize hashed password caveat * core: name password hash signal source * core: centralize password hash validation * core: deduplicate serializer password saves * docs: link source writeback caveats * api: clarify password hash request field * tests: deduplicate password hash API assertions * web: reuse user display-name helper * web: use existing user display formatter * core: reuse reset password permission for hash endpoint * core: keep separate password hash serializer * tests: remove redundant password hash permission test * 21745 Co-authored-by: Gergo <gergo@goauthentik.io> * core: preserve empty password handling in user serializer * core: inline blueprint user serializer fields * Use password hash constant * Simplify user serializer flow * Inline password update handling * Apply serializer cleanup * Clean blueprint password handling * Drop extra returns * Split password hash signal * Align hash signal receivers * Remove stale password guards * Inline password signal --------- Co-authored-by: Codex <codex@openai.com> Co-authored-by: Gergo <gergo@goauthentik.io>
7.9 KiB
title, authentik_preview, authentik_version
| title | authentik_preview | authentik_version |
|---|---|---|
| Kerberos | true | 2024.10 |
This source allows users to enroll themselves with an existing Kerberos identity.
Preparation
The following placeholders are used in this guide:
REALM.COMPANYis the Kerberos realm.authentik.companyis the FQDN of the authentik install.
Examples are shown for an MIT Krb5 KDC system; you might need to adapt them for your 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 and their Kerberos credentials.
You can choose to use one or more 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 - Icon: Optional icon or image shown for the source. See File picker values.
- 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) 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 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 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:
$ 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:
$ 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 on how to do so. You can now log in 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, and requires authentik to receive the raw password; hashed-password imports are not written back to Kerberos.
Kerberos source property mappings
See the overview for information on how property mappings work with external sources.
By default, authentik ships with pre-configured 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 logging in is not allowed.
- authentik default Kerberos User Mapping: Ignore system principals
System principals such as
K/Morkadmin/adminare 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 examplealice@REALM.COMPANYorHTTP/authentik.company@REALM.COMPANY.
When the property mapping is invoked from a SPNEGO context, the following variable is also available:
spnego_info: a Python dictionary with the following keys:initiator_name: the name of the initiator of the GSSAPI security contexttarget_name: the name of the target of the GSSAPI security contextmech: the GSSAPI mechanism used. Should always be Kerberosactual_flags: the flags set on the GSSAPI security context
When the property mapping is invoked from a synchronization context, the following variable is also available:
principal_obj: aPrincipalobject retrieved from the KAdmin API
Additional expression semantics
If you need to skip synchronization for a specific object, you can raise the SkipObject exception. To do so, create or modify a Kerberos property mapping to use an expression to define the object to skip.
Example:
localpart, realm = principal.rsplit("@", 1)
if localpart == "username":
raise SkipObject
Troubleshooting
You can start authentik with the KRB5_TRACE=/dev/stderr environment variable for Kerberos to print errors in the logs.
Reverse proxy caching can break the Kerberos authentication flow because, during negotiation, the server sends a second 401 Unauthorized response containing the WWW-Authenticate header that the client needs to continue the handshake; if the reverse proxy caches that 401 instead of forwarding it to authentik, the authentication process fails, so response caching should be disabled on any reverse proxy routes involved in Kerberos authentication.