> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Directories with Lumos

Connect Lumos to your directory to sync users, groups, and memberships, and to provision group access. Both directory connectors run on the On-Premise Agent, since domain controllers and LDAP servers aren't reachable from the internet.

Two connectors, one decision:

* **Active Directory**: for Microsoft AD. Full configuration surface including OU scoping, nested-group hierarchy, and service-account OU designation.
* **LDAP**: for any other LDAP-compatible directory. Accounts, attributes, and group membership sync, plus group assignment.

## Prerequisites

* The On-Premise Agent is installed and connected. See [Installation](/integrations/on-premise-agent/installation).
* A dedicated service account in the directory for Lumos to bind with. Read access is enough for a sync-only connection; add write access under the Base DN only if you provision. For the per-permission breakdown in Active Directory, see [Connecting Active Directory](/integrations/library/active-directory).

## Active Directory

### Authentication and connection

| Setting | Required | Guidance |
| :- | :- | :- |
| **Username** | Yes | The AD service account, typically as UPN (`serviceAccount@example.com`). Use a dedicated service account. Read access to user and group objects is enough for sync; add write access under the Base DN only if you provision |
| **Password** | Yes | Store in your credential vault |
| **Domain Name** | Yes | FQDN preferred (`example.com`). IP acceptable but less flexible. Must be reachable from the agent machine |
| **Base DN** | Yes | The root of the search, usually your domain components (`dc=example,dc=com`) |
| **Port** | Yes | 389 for LDAP, 636 for LDAPS |
| **Protocol** | Yes | Use **LDAPS** wherever possible. Plain LDAP only with network-level encryption in place |
| **Validate Certificate** | LDAPS only | On for production. The certificate chain must be trusted by the agent machine |

### Scoping the sync (optional settings)

| Setting | Purpose |
| :- | :- |
| **Service Account OUs** | OUs containing service accounts, one per line, so Lumos classifies them correctly |
| **Users Search Base DN** | Start user searches at a specific OU instead of the Base DN, for efficiency |
| **Users Search Filter** | An LDAP filter narrowing which users sync, for example `(objectCategory=person)` |
| **Groups Search Base DN** | Start group searches at a specific OU |
| **Groups Search Filter** | An LDAP filter narrowing which groups sync |
| **Include Hierarchy** | When checked, nested group memberships resolve recursively, so a member of a child group also counts as a member of its parents |

Filter recipes for common scoping cases, including importing only members of specific groups and excluding disabled accounts, are on [Directory Search Filter Examples](/integrations/generics/directory-ad/examples).

### Connect in Lumos

1. Find the Active Directory card in your Lumos integrations (reconnect an existing card or add a new one) and download the connector package.
2. Enter the authentication and connection settings above, plus any scoping settings you need.
3. Click **Connect**. Lumos tests connectivity and begins synchronizing based on your configuration.

## LDAP

### Requirements

* The server host, a **Base DN**, and bind credentials that can read the directory. Use a dedicated service account. Read access is enough for sync; add write access only if you provision.
* An **account search filter** that selects the entries Lumos should treat as accounts.

You can point more than one LDAP connection at the same server host. Each connection is scoped by its own search filter, so a single host can back several applications as separate integrations.

### Connect in Lumos

1. Find the LDAP card in your Lumos integrations.
2. Enter the server host, the **Base DN**, and the bind credentials.
3. Set the **account search filter** for the entries you want synced.
4. Click **Connect**.

### Custom attributes

Lumos builds the custom attribute picker by sampling the **first 100 entries** matching your account filter. Only attributes holding a value on at least one sampled entry appear. An attribute that's empty across the sample, or populated only on entries beyond the first 100, won't show up. Once discovered, there's no limit on how many attributes you can sync.

## Capabilities

| Functionality | Type | AD | LDAP | Description |
| :- | :- | :- | :- | :- |
| Accounts | Account | Sync + Provision | Sync + Provision | Directory users or entries matching your filters |
| Groups and membership | Entitlement | Sync + Provision | Sync + Provision | Group membership assignment and removal |
| Custom attributes | Attribute | Sync + Provision | Sync + Provision | |

### Deprovisioning actions

For Active Directory, see the deprovisioning actions table in [Connecting Active Directory](/integrations/library/active-directory).

For LDAP:

| Deprovisioning Action | Description |
| :- | :- |
| Deactivate Account | Locks the account by setting `pwdAccountLockedTime`. Works only when the directory exposes that attribute through its password policy (ppolicy) overlay. On other directories, deactivation isn't supported |
| Unassign Entitlement | Removes the user from a group |
| Remove from All Groups | Removes the user from every group they belong to |

## Troubleshooting

**Authentication failures.** Verify the username and password, and confirm the service account isn't locked or disabled.

**Connection errors.** Check the domain name or IP resolves and is reachable from the agent machine (DNS, firewall rules). For LDAPS, confirm the port is open and the certificate is trusted.

**Incorrect or empty search results.** Validate the Base DN and search base DNs. Temporarily remove or simplify search filters to verify objects appear, then reintroduce them. Confirm the service account can read the OUs in scope.

**Certificate validation failures.** With Validate Certificate on, the chain must be trusted by the machine running the connector. Add your root or intermediate CA to the agent machine's trusted store, covered in [Adding Additional CA Certificates](/integrations/on-premise-agent/adding-additional-ca-certificates).

**Group assignment fails with "Unsupported group type" (LDAP).** Lumos can change membership only on groups whose `objectClass` includes `posixGroup`, `groupOfNames`, or `groupOfUniqueNames`. Check the group's `objectClass` values in your directory. If the group has one of these classes and the error persists, contact [support@lumos.com](mailto:support@lumos.com) with the group's `objectClass` values.

**Membership adds fail unexpectedly (LDAP).** Some directories store membership on `uniqueMember` rather than `member`. The connector handles both.

**An add returns** `attributeOrValueExists `**(LDAP result 20).** The user is already a member. Lumos treats this as a no-op success.

**A custom attribute isn't in the picker (LDAP).** It's empty across the first 100 entries matching your filter. Make sure it holds a value on at least one sampled entry. Credential-related attribute names are filtered out by design.