From 6c0e827677c21d77bccb6134bd54cb910c365f76 Mon Sep 17 00:00:00 2001 From: Marc 'risson' Schmitt Date: Tue, 29 Apr 2025 20:32:59 +0200 Subject: [PATCH] website/docs: add LDAP 'Lookup using user attribute' docs (#13966) * website/docs: add LDAP 'Lookup using user attribute' docs Signed-off-by: Marc 'risson' Schmitt * Updated the doc to new template, removed incorrect screenshot, clarified instructions * Change in group field explanation as per Marc's comment * Added examples for filters and changed some language. * Removed additional info link * fixup Signed-off-by: Marc 'risson' Schmitt * Minor formatting changes * Update website/docs/users-sources/sources/protocols/ldap/index.md Signed-off-by: Tana M Berry * Update website/docs/users-sources/sources/directory-sync/active-directory/index.md Signed-off-by: Tana M Berry * Update website/docs/users-sources/sources/directory-sync/active-directory/index.md Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Added more information to service account creation and LDAPS testing * Added examples for fields based on issue #3801 --------- Signed-off-by: Marc 'risson' Schmitt Signed-off-by: Tana M Berry Signed-off-by: Dewi Roberts Co-authored-by: Dewi Roberts Co-authored-by: Tana M Berry Co-authored-by: Dominic R --- .../directory-sync/active-directory/index.md | 105 ++++++++++-------- .../sources/protocols/ldap/index.md | 37 ++---- 2 files changed, 70 insertions(+), 72 deletions(-) diff --git a/website/docs/users-sources/sources/directory-sync/active-directory/index.md b/website/docs/users-sources/sources/directory-sync/active-directory/index.md index 6b10fdfc10..73dd0c0d7e 100644 --- a/website/docs/users-sources/sources/directory-sync/active-directory/index.md +++ b/website/docs/users-sources/sources/directory-sync/active-directory/index.md @@ -7,66 +7,79 @@ support_level: community The following placeholders are used in this guide: -- `ad.company` is the Name of the Active Directory domain. +- `ad.company` is the name of the Active Directory domain. - `authentik.company` is the FQDN of the authentik install. -## Active Directory setup +## Active Directory configuration -1. Open Active Directory Users and Computers +To support the integration of Active Directory with authentik, you need to create a service account in Active Directory. -2. Create a user in Active Directory, matching your naming scheme +1. Open **Active Directory Users and Computers** on a domain controller or computer with **Active Directory Remote Server Administration Tools** installed. +2. Navigate to an Organizational Unit, right click on it, and select **New** > **User**. +3. Create a service account, matching your naming scheme, for example: ![](./01_user_create.png) -3. Give the User a password, generated using for example `pwgen 64 1` or `openssl rand 36 | base64 -w 0`. +4. Set the password for the service account. Ensure that the **Reset user password and force password change at next logon** option is not checked. -4. Open the Delegation of Control Wizard by right-clicking the domain and selecting "All Tasks". + Either one of the following commands can be used to generate the password: -5. Select the authentik service user you've just created. + ```sh + pwgen 64 1 + ``` -6. Ensure the "Reset user password and force password change at next logon" Option is checked. + ```sh + openssl rand 36 | base64 -w 0 + ``` + +5. Open the **Delegation of Control Wizard** by right-clicking the domain Active Directory Users and Computers, and selecting **All Tasks**. +6. Select the authentik service account that you've just created. +7. Grant these additional permissions (only required when _User password writeback_ is enabled on the LDAP source in authentik, and dependent on your AD Domain) ![](./02_delegate.png) -7. Grant these additional permissions (only required when _Sync users' password_ is enabled, and dependent on your AD Domain) +## authentik Setup + +To support the integration of authentik with Active Directory, you will need to create a new LDAP Source in authentik. + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Directory** > **Federation & Social login**. +3. Click **Create** and select **LDAP Source** as the type. +4. Provide a name, slug, and the following required configurations: + + Under **Connection Settings**: + + - **Server URI**: `ldap://ad.company` + + :::note + For authentik to be able to write passwords back to Active Directory, make sure to use `ldaps://` as a prefix. You can verify that LDAPS is working by opening the `ldp.exe` tool on a domain controller and attempting a connection to the server via port 636. If a connection can be established, LDAPS is functioning as expected. More information can be found in the [Microsoft LDAPS documentation](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/ldap-over-ssl-connection-issues). + + Multiple servers can be specified by separating URIs with a comma (e.g. `ldap://dc1.ad.company,ldap://dc2.ad.company`). If a DNS entry with multiple records is used, authentik will select a random entry when first connecting. + ::: + + - **Bind CN**: `@ad.company` + - **Bind Password**: the password of the service account created in the previous section. + - **Base DN**: the base DN which you want authentik to sync. + + Under **LDAP Attribute Mapping**: + + - **User Property Mappings**: select all Mappings which start with "authentik default LDAP" and "authentik default Active Directory" + - **Group Property Mappings**: select "authentik default LDAP Mapping: Name" + + Under **Additional Settings** _(optional)_ configurations that may need to be adjusted based on the setup of your domain: + + - **Group**: if enabled, all synchronized groups will be given this group as a parent. + - **Addition User/Group DN**: additional DN which is _prepended_ to your Base DN configured above, to limit the scope of synchronization for Users and Groups. + - **User object filter**: which objects should be considered users (e.g. `(objectClass=user)`). For Active Directory set it to `(&(objectClass=user)(!(objectClass=computer)))` to exclude Computer accounts. + - **Group object filter**: which objects should be considered groups (e.g `(objectClass=group)`). + - **Lookup using a user attribute**: acquire group membership from a User object attribute (`memberOf`) instead of a Group attribute (`member`). This works with directories and nested groups memberships (Active Directory, RedHat IDM/FreeIPA), using `memberOf:1.2.840.113556.1.4.1941:` as the group membership field. + - **Group membership field**: the user object attribute or the group object attribute that determines the group membership of a user (e.g. `member`). If **Lookup using a user attribute** is set, this should be a user object attribute, otherwise a group object attribute. + - **Object uniqueness field**: a user attribute that contains a unique identifier (e.g. `objectSid`). + +5. Click **Finish** to save the LDAP Source. An LDAP synchronization will begin in the background. Once completed, you can view the summary by navigating to **Dashboards** > **System Tasks**: ![](./03_additional_perms.png) -Additional info: https://support.microfocus.com/kb/doc.php?id=7023371 +6. To finalise the Active Directory setup, you need to enable the backend "authentik LDAP" in the Password Stage. -## authentik Setup - -In authentik, create a new LDAP Source in Directory -> Federation & Social login. - -Use these settings: - -- Server URI: `ldap://ad.company` - - For authentik to be able to write passwords back to Active Directory, make sure to use `ldaps://`. You can test to verify LDAPS is working using `ldp.exe`. - - You can specify multiple servers by separating URIs with a comma, like `ldap://dc1.ad.company,ldap://dc2.ad.company`. - - When using a DNS entry with multiple Records, authentik will select a random entry when first connecting. - -- Bind CN: `@ad.company` -- Bind Password: The password you've given the user above -- Base DN: The base DN which you want authentik to sync -- Property mappings: Control/Command-select all Mappings which start with "authentik default LDAP" and "authentik default Active Directory" -- Group property mappings: Select "authentik default LDAP Mapping: Name" - -Additional settings that might need to be adjusted based on the setup of your domain: - -- Group: If enabled, all synchronized groups will be given this group as a parent. -- Addition User/Group DN: Additional DN which is _prepended_ to your Base DN configured above to limit the scope of synchronization for Users and Groups -- User object filter: Which objects should be considered users. For Active Directory set it to `(&(objectClass=user)(!(objectClass=computer)))` to exclude Computer accounts. -- Group object filter: Which objects should be considered groups. -- Group membership field: Which user field saves the group membership -- Object uniqueness field: A user field which contains a unique Identifier - -After you save the source, a synchronization will start in the background. When its done, you can see the summary under Dashboards -> System Tasks. - -![](./03_additional_perms.png) - -To finalise the Active Directory setup, you need to enable the backend "authentik LDAP" in the Password Stage. - -![](./11_ak_stage.png) + ![](./11_ak_stage.png) diff --git a/website/docs/users-sources/sources/protocols/ldap/index.md b/website/docs/users-sources/sources/protocols/ldap/index.md index a59e8dc2a4..87078a82ca 100644 --- a/website/docs/users-sources/sources/protocols/ldap/index.md +++ b/website/docs/users-sources/sources/protocols/ldap/index.md @@ -12,18 +12,13 @@ For FreeIPA, follow the [FreeIPA Integration](../../directory-sync/freeipa/index ## Configuration options for LDAP sources -To create or edit a source in authentik, open the Admin interface and navigate to **Directory -> Ferderation and Social login**. There you can create a new LDAP source, or edit an existing one, using the following settings. +To create or edit a source in authentik, open the Admin interface and navigate to **Directory > Ferderation and Social login**. There you can create a new LDAP source, or edit an existing one, using the following settings. - **Enabled**: Toggle this option on to allow authentik to use the defined LDAP source. - - **Update internal password on login**: When the user logs in to authentik using the LDAP password backend, the password is stored as a hashed value in authentik. Toggle off (default setting) if you do not want to store the hashed passwords in authentik. - - **Sync users**: Enable or disable user synchronization between authentik and the LDAP source. - - **User password writeback**: Enable this option if you want to write password changes that are made in authentik back to LDAP. - - **Sync groups**: Enable/disable group synchronization. Groups are synced in the background every 5 minutes. - - **Parent group**: Optionally set this group as the parent group for all synced groups. An example use case of this would be to import Active Directory groups under a root `imported-from-ad` group. #### Connection settings @@ -34,13 +29,9 @@ To create or edit a source in authentik, open the Admin interface and navigate t - **Use Server URI for SNI verification**: this setting is required for servers using TLS 1.3+ - **TLS Verification Certificate**: Specify a keypair to validate the remote certificate. - - **TLS Client authentication**: Client certificate keypair to authenticate against the LDAP Server's Certificate. - - **Bind CN**: CN of the bind user. This can also be a UPN in the format of `user@domain.tld`. - - **Bind password**: Password used during the bind process. - - **Base DN**: Base DN (distinguished name) used for all LDAP queries. #### LDAP Attribute mapping @@ -54,19 +45,13 @@ To create or edit a source in authentik, open the Admin interface and navigate t #### Additional Settings - **Group**: Parent group for all the groups imported from LDAP. - - **User path**: Path template for all new users created. - - **Addition User DN**: Prepended to the base DN for user queries. - - **Addition Group DN**: Prepended to the base DN for group queries. - - **User object filter**: Consider objects matching this filter to be users. - - **Group object filter**: Consider objects matching this filter to be groups. - -- **Group membership field**: This field contains the user's group memberships. - +- **Lookup using a user attribute**: Acquire group membership from a User object attribute (`memberOf`) instead of a Group attribute (`member`). This works with directories with nested groups memberships (Active Directory, RedHat IDM/FreeIPA), using `memberOf:1.2.840.113556.1.4.1941:` as the group membership field. +- **Group membership field**: The user object attribute or the group object attribute that determines the group membership for a user. If **Lookup using a user attribute** is set, this should be a user object attribute, otherwise a group object attribute. - **Object uniqueness field**: This field contains a unique identifier. ## LDAP source property mappings @@ -90,14 +75,14 @@ return { LDAP property mappings are used when you define a LDAP source. These mappings define which LDAP property maps to which authentik property. By default, the following mappings are created: -- authentik default Active Directory Mapping: givenName -- authentik default Active Directory Mapping: sAMAccountName -- authentik default Active Directory Mapping: sn -- authentik default Active Directory Mapping: userPrincipalName -- authentik default LDAP Mapping: mail -- authentik default LDAP Mapping: Name -- authentik default OpenLDAP Mapping: cn -- authentik default OpenLDAP Mapping: uid +- `authentik default Active Directory Mapping: givenName` +- `authentik default Active Directory Mapping: sAMAccountName` +- `authentik default Active Directory Mapping: sn` +- `authentik default Active Directory Mapping: userPrincipalName` +- `authentik default LDAP Mapping: mail` +- `authentik default LDAP Mapping: Name` +- `authentik default OpenLDAP Mapping: cn` +- `authentik default OpenLDAP Mapping: uid` These are configured with most common LDAP setups.