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 <marc.schmitt@risson.space> * 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 <marc.schmitt@risson.space> * Minor formatting changes * Update website/docs/users-sources/sources/protocols/ldap/index.md Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> * Update website/docs/users-sources/sources/directory-sync/active-directory/index.md Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> * Update website/docs/users-sources/sources/directory-sync/active-directory/index.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Added more information to service account creation and LDAPS testing * Added examples for fields based on issue #3801 --------- Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Dewi Roberts <dewi@goauthentik.io> Co-authored-by: Dewi Roberts <dewi@goauthentik.io> Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Co-authored-by: Dominic R <dominic@sdko.org>
This commit is contained in:
Marc 'risson' Schmitt
committed by
GitHub
GitHub
parent
812cf6c4f2
commit
bcefe7123c
@ -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:
|
||||
|
||||
|
||||
|
||||
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)
|
||||
|
||||
|
||||
|
||||
7. Grant these additional permissions (only required when _Sync users' password_ is enabled, and dependent on your AD Domain)
|
||||
|
||||
|
||||
|
||||
Additional info: https://support.microfocus.com/kb/doc.php?id=7023371
|
||||
|
||||
## authentik Setup
|
||||
|
||||
In authentik, create a new LDAP Source in Directory -> Federation & Social login.
|
||||
To support the integration of authentik with Active Directory, you will need to create a new LDAP Source in authentik.
|
||||
|
||||
Use these settings:
|
||||
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:
|
||||
|
||||
- Server URI: `ldap://ad.company`
|
||||
Under **Connection Settings**:
|
||||
|
||||
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`.
|
||||
- **Server URI**: `ldap://ad.company`
|
||||
|
||||
You can specify multiple servers by separating URIs with a comma, like `ldap://dc1.ad.company,ldap://dc2.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).
|
||||
|
||||
When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
|
||||
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: `<name of your service user>@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"
|
||||
- **Bind CN**: `<service account>@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.
|
||||
|
||||
Additional settings that might need to be adjusted based on the setup of your domain:
|
||||
Under **LDAP Attribute Mapping**:
|
||||
|
||||
- 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
|
||||
- **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"
|
||||
|
||||
After you save the source, a synchronization will start in the background. When its done, you can see the summary under Dashboards -> System Tasks.
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
To finalise the Active Directory setup, you need to enable the backend "authentik LDAP" in the Password Stage.
|
||||
6. To finalise the Active Directory setup, you need to enable the backend "authentik LDAP" in the Password Stage.
|
||||
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user