---
title: LDAP Source
---

Sources allow you to connect authentik to an existing user directory. This source allows you to import users and groups from an LDAP server.

:::info
For Active Directory, follow the [Active Directory Integration](../../directory-sync/active-directory/index.md)

For FreeIPA, follow the [FreeIPA Integration](../../directory-sync/freeipa/index.md)
:::

## Configuration options for LDAP sources

To create or edit a source in authentik, open the Admin interface and navigate to **Directory > Federation 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 between authentik and the LDAP source.
- **Delete Not Found Objects**: :ak-version[2025.6] This option synchronizes user and group deletions from LDAP sources to authentik. User deletion requires enabling **Sync users** and group deletion requires enabling **Sync groups**.

#### Connection settings

- **Server URI**: URI to your LDAP server/Domain Controller. You can specify multiple servers by separating URIs with a comma, like `ldap://ldap1.company,ldap://ldap2.company`. When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
    - **Enable StartTLS**: Enables StartTLS functionality. To use LDAPS instead, use port `636`.
    - **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 certificate**: 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

- **User Property Mappings** and **Group Property Mappings**: Define which LDAP properties map to which authentik properties. The default set of property mappings is generated for Active Directory. See also our documentation on [property mappings](#ldap-source-property-mappings).

    :::warning
    When the **Sync users** and/or the **Sync groups** options are enabled, their respective property mapping options must have at least one mapping selected, otherwise the sync will not start.
    :::

#### Additional Settings

- **Parent Group**: Parent group for all the groups imported from LDAP. An example use case would be to import Active Directory groups under a root `imported-from-ad` group.
- **User path**: Path template for all new users created.
- **Additional User DN**: Prepended to the base DN for user queries.
- **Additional 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.
- **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 group 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.
- **User membership attribute**: Attribute name on authentik user objects which is checked against the **Group membership field**. Two common cases are:
    - If your groups have `member` attributes containing DNs, set this to `distinguishedName`. (The `distinguishedName` attribute for User objects in authentik is set automatically.)
    - If your groups have `memberUid` attributes containing `uid`s, set this to `uid`. Make sure that you've created a property mapping that creates an attribute called `uid`.
- **Object uniqueness field**: This field contains a unique identifier.

## LDAP 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 LDAP setups. These mappings can be found on the LDAP Source Configuration page in the Admin interface.

You can assign the value of a mapping to any user attribute. Keep in mind, though, data types from the LDAP server will be carried over. This means that with some implementations, where fields are stored as an array in LDAP, they will be saved as an array in authentik. To prevent this, use the built-in `list_flatten` function. Here is an example mapping for the user's username and a custom attribute for a phone number:

```python
return {
    "username": ldap.get("uid"), # list_flatten is automatically applied to top-level attributes
    "attributes": {
        "phone": list_flatten(ldap.get("phoneNumber")), # but not for attributes!
    },
}
```

The same LDAP source property mapping type is used for both users and groups. A mapping only applies to groups when you assign it under **Group Property Mappings** on the LDAP source. If you only use the built-in group property mappings, synced groups will keep the automatically populated LDAP attributes, such as `distinguishedName`, but custom LDAP attributes won't be copied unless you add your own group mapping.

### Copy a custom LDAP group attribute

To store a custom LDAP group attribute in authentik's group `attributes`, create an **LDAP Source Property Mapping** and assign it to **Group Property Mappings** on the source:

```python
return {
    "attributes": {
        "acl": list_flatten(ldap.get("acl")),
    },
}
```

If your LDAP server stores the value as JSON text and you want authentik to keep it as structured data instead of a string, decode it in the mapping:

```python
import json

raw_acl = list_flatten(ldap.get("acl"))
return {
    "attributes": {
        "acl": json.loads(raw_acl) if raw_acl else None,
    },
}
```

### Built-in property mappings

LDAP property mappings are used when you define an 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`

These are configured with most common LDAP setups.

### Expression data

The following variables are available to LDAP source property mappings:

- `ldap`: A Python dictionary containing data from LDAP.
- `dn`: The object DN.

### 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 an LDAP property mapping to use an expression to define the object to skip.

**Example:**

```python
if ldap.get("cn") == "doNotSync":
    raise SkipObject
```

## Password login

By default, authentik doesn't update the password it stores for a user when they log in using their LDAP credentials. That means that if the LDAP server is not reachable by authentik, users will not be able to log in. This behavior can be turned on with the **Update internal password on login** setting on the LDAP source.

:::info
Sources created prior to the 2024.2 release have this setting turned on by default.
:::

Be aware of the following security considerations when turning on this functionality:

- Updating the LDAP password does not invalidate the password stored in authentik; however for LDAP Servers like FreeIPA and Active Directory, authentik will lock its internal password during the next LDAP sync. For other LDAP servers, the old passwords will still be valid indefinitely.
- Logging in via LDAP credentials overwrites the password stored in authentik if users have different passwords in LDAP and authentik.
- Custom security measures that are used to secure the password in LDAP may differ from the ones used in authentik. Depending on threat model and security requirements this could lead to unknowingly being non-compliant.

## Troubleshooting

To troubleshoot LDAP sources and their synchronization, see [LDAP Troubleshooting](../../../../troubleshooting/ldap_source.md).
