Skip to main content

After this article

You will be able to connect your on-premises (or cloud-hosted) Active Directory domain to Lumos through the On-Premise Agent. Lumos syncs users, groups, and organizational units, and it can create, update, deactivate, and move accounts and manage security-group membership.

Capabilities

User statuses: ACTIVE (userAccountControl 0x200 normal account), SUSPENDED (0x2 disabled bit set, and disabled users are still returned by queries), DELETED (no longer returned by the directory). There is no separate “activate” action. Re-enabling means clearing the disabled bit via an account update. If the service account can’t read userAccountControl on a user object, Lumos can’t determine the account’s status. In that case, the sync fails with a NO_USER_ACCOUNT_CONTROL error instead of reporting the account as ACTIVE. See Troubleshooting. Notes:
  • Last login is read from lastLogonTimestamp and requires custom attribute configuration (not synced by default). Values can be up to ~14 days stale because AD only replicates this attribute on large deltas.
  • Group memberships as user data also require custom attribute configuration.
  • How custom attributes are discovered: Lumos builds the attribute list from two sources: the AD server schema for user object classes, and the attributes that hold a value on the first 100 accounts returned under your Base DN. An attribute that is empty everywhere, or populated only on accounts outside that sample, will not appear as an option (Exchange extensionAttribute1–15 can only be discovered through the sample). There is no limit on how many custom attributes you can configure once an attribute is discovered.
  • Accounts in the OUs you list in the Service Account OUs setting (one OU per line) sync as service accounts rather than user accounts. They are still listed.
  • AD groups sync as assignable Entitlements only. They cannot be used as Lumos groups (e.g. in Allowed Groups or as Approvers). Lumos groups come from Entra, Okta, and Google Workspace.
  • accountExpires, pwdLastSet, and lastLogon values of 0 or 9223372036854775807 mean never. Use the Sync “Never” Dates as Empty setting to keep them from syncing as 1601-01-01 or 9999-12-31.

Required plan and roles

  • Agent: this connector runs through the Lumos On-Premise Agent. Set it up per the On-Premise Agent Quickstart Guide before connecting.
  • Service account: create a dedicated AD service account. It needs at least read access to the domain, specifically to entries under your Base DN. For provisioning it needs write capabilities under the Base DN.
  • Authentication: choose one in Authentication Method:
    • Basic: Simple BIND with the service account’s username and password. Credentials are encrypted and stored in Lumos.
    • gMSA: a Group Managed Service Account. The agent host authenticates with its own Windows Kerberos ticket, so no AD credentials are stored in Lumos. This needs the agent to run on Windows (bare metal, VM, or Windows container), not Linux or a Linux Docker container. See Connecting with a gMSA.
  • Granular permissions (least privilege):
    • Users, read: Read All Properties on user objects, List Contents on OUs containing users, and Read on the domain root (for searching).
    • Account status, read: Read on the userAccountControl attribute (part of the Account Restrictions property set) on user objects in every OU that holds users. Read All Properties covers it, but an OU with its own ACL can still block it. This includes OUs that your offboarding process moves accounts into, such as a Disabled Accounts OU. Make sure the permission applies to descendant user objects, not only to the OU itself.
    • Users, write: Write All Properties on user objects (includes userAccountControl, sAMAccountName, mail, givenName, sn, userPrincipalName, manager, and custom attributes). Create Child Objects on OUs where new users will be created. Delete Child Objects on OUs where users may be deleted.
    • Password management: Reset Password and Change Password on user objects (password operations require LDAPS).
    • Account status: Write on the userAccountControl attribute (enable/disable accounts).
    • Groups, read: Read All Properties on group objects, and List Contents on OUs containing groups.
    • Groups, write: Write on the member attribute (add/remove users), and Write All Properties on group objects if group modifications are needed.
    • OU moves: Write distinguishedName on user objects, Delete Child Objects on source OUs, and Create Child Objects on destination OUs.
    • Custom attributes: Read on all custom attributes retrieved, and Write on any custom attributes modified.
  • For a read-only connection, grant only the read permissions above.
  • Moving user objects cross-domain within the same forest requires the PowerShell connector and a service account with Enterprise Admin rights.

Read-only access vs provisioning

Is read-only possible? Yes. The permissions you grant the service account control Active Directory access entirely. To set up a fully supported read-only connection, grant only the read permissions. What read-only requires. A dedicated AD service account with Read All Properties on user objects, List Contents on OUs containing users, and Read on the domain root, connecting through the Lumos On-Premise Agent. Follow the steps below and grant only these read permissions when you create the service account. What full provisioning requires. The same service account with write permissions added under the Base DN: Write All Properties on user objects, Create and Delete Child Objects on the relevant OUs, Write on the userAccountControl attribute to change account status, and Write on the member attribute for group changes. Password reset and change operations additionally require LDAPS. Moving accounts across domains in the same forest requires the PowerShell connector and a service account with Enterprise Admin rights. Watch out for. Read-only and full provisioning use the same authentication method (Simple BIND or gMSA) and the same connector. Moving from read-only to provisioning means expanding the service account’s permissions rather than reconnecting with a different credential type. Password operations require LDAPS (port 636), and attempting them over plain LDAP (389) fails. Deactivating an account only sets the disabled bit. It does not delete or move the object.

Instructions

Phase 1: Prepare Active Directory
  1. Set up the Lumos On-Premise Agent following the On-Premise Agent Quickstart Guide.
  2. Create the service account with the permissions above (read-only for sync, write under the Base DN for provisioning). For gMSA, create the gMSA instead and grant it the same permissions (see Connecting with a gMSA).
Phase 2: Connect in Lumos
  1. Find the Active Directory card in your Lumos integrations (reconnect an existing card or add a new one). On a Windows agent, download the connector ZIP from the setup wizard, drop it into the agent’s connectors/ folder without unzipping it, and restart the agent. The Docker agent image already includes the connector. Allow a few minutes for the connector to appear.
  2. Enter the connection details:
    • Authentication Method: Basic (username and password) or gMSA.
    • Username: must include the domain, e.g. svc-lumos@testdomain.com. Leave blank for gMSA.
    • Password: the service account password. Leave blank for gMSA.
    • Host Name: the address Lumos sends LDAP queries to, including the TLD, e.g. testdomain.com or an IP address. For gMSA, use the domain controller’s fully qualified hostname, e.g. dc01.testdomain.com.
    • Base DN: use uppercase attribute names, e.g. DC=testdomain, DC=com.
    • Port: the LDAP port (389 for LDAP, 636 for LDAPS).
    • Protocol: LDAP or LDAPS. LDAPS encrypts all traffic, including credentials, and password operations require it.
    • Validate Certificate (optional, off by default): verify the domain controller’s certificate. Applies to LDAPS only.
    • Users Search Base DN and Groups Search Base DN (optional): narrow where Lumos searches for users and groups. Leave blank to search from the Base DN. Provisioning lookups use the same search bases as the sync. Don’t use these to filter users; use the search filters instead.
    • Users Search Filter and Groups Search Filter (optional): an LDAP filter added to every user or group search, e.g. (!(objectClass=computer)).
    • Service Account OUs (optional): OUs whose accounts sync as service accounts, one per line, e.g. OU=ServiceAccount,DC=example,DC=com.
    • Include Hierarchy (optional, off by default): include parent groups when finding a user’s entitlements. Lumos follows up to 5 levels and 20 parent groups per group. Turn on Enable Deep Group Search to remove those limits for deeper hierarchies.
    • Choose Username Source (optional): the AD attribute Lumos uses as the account username, sAMAccountName (default), userPrincipalName, or objectSid.
    • Sync “Never” Dates as Empty (optional, off by default): Active Directory stores “never” in accountExpires, pwdLastSet, and lastLogon as 0 or 9223372036854775807. By default those sync as the literal dates 1601-01-01 and 9999-12-31. Turn this on to sync them as empty, so an identity whose End Date comes from accountExpires does not get a 9999-12-31 end date.
  3. Click Connect. Lumos checks the details by binding to Active Directory with them, and the connection saves only if that succeeds.
Connecting or reconnecting the integration starts a sync right away, and users and groups appear in Lumos when it finishes. After that, Lumos syncs on its regular integration sync schedule. To refresh sooner, see Triggering Syncs Deep Dive.

Connecting with a gMSA

Use gMSA when your policy doesn’t allow storing AD credentials in Lumos.
  1. Create a Group Managed Service Account in Active Directory and allow the agent host to retrieve its password. See Microsoft’s Get started with group managed service accounts.
  2. Grant the gMSA the same permissions listed in Required plan and roles.
  3. Run the agent on Windows, and configure the Windows service that runs it to log on as the gMSA, so a Kerberos ticket is available at runtime.
  4. In Phase 2, set Authentication Method to gMSA, leave Username and Password blank, and enter the domain controller’s fully qualified hostname in Host Name (e.g. dc01.testdomain.com). Using only the domain name fails with a GSSAPI error.

API Endpoints Used

Troubleshooting

“Invalid credentials”. Check the domain name resolves, the username format (domain\\user or user@domain.com), and that the service account is unlocked and enabled. Verify the firewall allows port 389/636 and test with ldapsearch. “Permission denied” / NO_USER_ACCOUNT_CONTROL. The error code is PERMISSION_DENIED, with a message like Account CN=Jane Doe,OU=Disabled Accounts,DC=example,DC=com has no userAccountControl attribute. This usually means the service account is not permitted to read this property, so its enabled or disabled state cannot be determined. For enable and disable actions, the message ends with “cannot be changed” instead. It can happen during account syncs (listing accounts, listing updated accounts, or fetching a single account) and on enable or disable actions. Active Directory sets userAccountControl on every user object, so an empty value means the service account isn’t allowed to read it on that object. A common cause is an offboarding process that moves disabled accounts into an OU, such as Disabled Accounts, whose ACL blocks the service account. A single unreadable user object fails the whole sync. Previously, Lumos reported these accounts as ACTIVE, which hid the permission gap and could block reactivation. To fix the permission gap:
  • Use the distinguished name (DN) in the error message to find the OU that holds the object.
  • On that OU, grant the service account Read on the userAccountControl attribute (or the Account Restrictions property set). Set the entry to apply to Descendant User objects so it inherits to the user objects, not only the OU.
  • Repeat for every OU that holds users, including OUs your offboarding process moves accounts into.
  • Re-run the sync. Once the attribute is readable, the sync succeeds and disabled accounts show as SUSPENDED.
For example, you can grant the permission with dsacls from an elevated prompt on a domain controller:
“Cannot set password” / MODIFY_PASSWORD_ERROR. Password operations require LDAPS (port 636) with a valid SSL certificate on the domain controller, and the password must meet domain complexity policy. Users not syncing. Verify the LDAP bind succeeds, the Base DN is correct and readable by the service account, and network connectivity to the domain controller. “Cannot move user to OU” / MODIFY_DN_ERROR. Verify the Modify DN permission, that the target OU exists, and the DN format (OU=TargetOU,DC=example,DC=com). Group assignment not working. Check write access to the group’s member attribute, that the group and user DNs exist, and DN formatting. A few accounts fail attribute sync with “This is an unexpected error” while the rest succeed. The underlying cause is AD rejecting the modify for those specific accounts. The error now names the attribute the directory rejected or the value that could not be resolved, so check that field first. Common cases: the object was moved/renamed/deleted since the last sync (stale DN, LDAP error 32 noSuchObject), or a computed sAMAccountName exceeds AD’s 20-character limit or contains spaces (LDAP error 80). Fix the AD-side data or mapping for the affected accounts. Attribute-sync failures right after upgrading/restarting the agent. If all agent nodes restart at once, in-flight attribute syncs have nowhere to go. Use a rolling restart (one node at a time, and the agent takes about a minute to start), then retry failed actions individually before bulk-retrying. Last-login dates look very old. lastLogonTimestamp only replicates between domain controllers on ~9–14 day deltas, and the connector reads the DC it binds to. Stale values are AD attribute behavior, not a sync error. An AD attribute (e.g. extensionAttribute4) doesn’t appear in the custom attribute picker. Not a sync failure and not a count limit. Attributes are offered only if the server schema lists them for user object classes or they hold a value on one of the first 100 accounts sampled under the Base DN. extensionAttribute1–15 are only discoverable via that sample. Confirm the attribute is populated on users inside the connector’s Base DN scope. Populating it on an account that sorts early under the Base DN gets it discovered on the next sync’s schema refresh. AD groups don’t appear as Allowed Groups/Approvers. Expected: AD groups are assignable entitlements only, not Lumos groups. The on-prem agent shows connected, but Active Directory doesn’t appear on the Integrations page. Installing and connecting the agent is only the first step. You still have to add and enable the AD integration before it appears. Add and connect the Active Directory integration as described in Phase 2 (on a Windows agent, this includes deploying the connector ZIP), then it will appear. The agent is connected but sync returns zero users, or fails with NO_OBJECT and “best match of”. Both symptoms point at the Users Search Base DN, not at connectivity. A search base that exists but is empty returns zero users with no error. A search base that does not exist returns AD’s NO_OBJECT error. The “best match of” value in that error is the deepest part of the path AD could resolve. If it stops at your DC= components, the OU= in front of them is the part that does not exist. Things to check:
  • The most reliable way to get the right value is to read it off a real account rather than guess it. On a domain-joined machine, Get-ADUser <sAMAccountName> | Select-Object DistinguishedName returns a known user’s full DN, and the container portion of that DN is what belongs in the field. Get-ADOrganizationalUnit -Filter * | Format-Table Name, DistinguishedName -Auto lists every OU with its exact DN.
  • OU=Users is a common trap. Active Directory’s default users location is a container, CN=Users, not an organizational unit, so OU=Users,DC=... does not resolve in a default directory.
  • Watch for typos, stray spaces, and trailing commas in every DN field, including Base DN and Service Account OUs. A dangling comma makes the DN malformed.
  • Leaving Users Search Base DN blank searches the whole domain from your Base DN and sidesteps the OU path question entirely. This is the quickest way to get a first successful sync, and you can narrow it later.
Reconnect after changing any of these values, then re-run the sync. Newly provisioned accounts prompt the user to change their password at first login. This is Active Directory’s own behavior for an account that has never had a password set, not a Lumos setting. There is no “reset on next login” toggle to switch off. It happens when the Create Account action provisions the account without a password. To avoid it, open the Create Account action’s Password Settings, set Auto-generate password to Yes, and set a recipient. Lumos then sets a password at creation and the account comes up without the prompt. If you would rather manage the flag yourself, pwdLastSet can be set as a custom attribute on the Update Account action as a step after creation, where -1 clears the requirement and 0 forces it. Validate that against a test OU before rolling it out. It has to go on Update rather than Create, because Lumos applies custom attributes on Create before it sets the password. Password reset fails with unwillingToPerform even over LDAPS. If the connection is already LDAPS on port 636 and the reset still fails, the request is reaching your domain controller and Active Directory is declining it. That is a directory-side condition rather than a connector setting. Your AD team can check these areas, roughly in order:
  1. The service account Lumos binds with needs the Reset Password (User-Force-Change-Password) right on the target accounts. Service accounts built for directory sync often have read and group-management rights but not password-reset rights. AD’s AdminSDHolder protection also strips delegated rights from admin and other protected accounts, so a reset can fail on privileged accounts while working elsewhere.
  2. The domain controller the connector points at must be writable. Password writes are not performed directly on a read-only domain controller, which can surface as this same error.
  3. Domain or fine-grained password policy, including minimum password age, can reject the reset.
A quick way to narrow it down is to try the same reset on a regular, non-privileged test user. If that succeeds, the problem is specific to protected accounts and their delegated rights. LDAPS on port 636 fails with an SSL certificate error, even with Validate Certificate turned off. The domain controller has to present a certificate to bring up the encrypted connection at all. Turning off Validate Certificate only skips verifying that certificate, so if the DC has none installed the connection still fails. Port 389 continuing to work is expected, because plain LDAP involves no certificate. AD requires an encrypted connection for password writes, so resets will not work over 389. The fix is on the directory side: install a valid Server Authentication certificate for the DC’s FQDN, with its private key in the Local Computer store, issued by a CA that forest trusts. Forests with no certificate authority at all are the usual cause of an empty Certification Authorities container and no LDAPS certificate. The AD password reset runs successfully but no password email arrives. Generated passwords are sent by email only, never over Slack or another chat channel. If your Lumos domain has no Email notification channel enabled, Lumos drops the email while the reset itself still completes. This is why the password changes but nothing is delivered. An Admin can enable Email under Settings > Notifications. No request to Lumos is needed. Then run the reset again. Lumos emails the password at the moment the reset runs and does not store it afterward, so the earlier attempt cannot be resent. If a password email still does not arrive after enabling the channel, check mail filtering and spam on your side.