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: the attribute list offered in Lumos is built from two sources, the AD server schema for user object classes plus 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.
  • Service accounts in specific OUs can be excluded from user listings via the service_account_ous multiline setting.
  • 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 guide in the Lumos Developer Docs 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: Simple BIND with username/password. Lumos recommends using an API token instead of the account password when possible. Credentials are encrypted and stored securely. Authentication via a Group Managed Service Account (gMSA) is also supported for organizations whose policy forbids storing AD credentials in the cloud.
  • 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. Active Directory access is controlled entirely by the permissions you grant the service account, and a read-only connection is fully supported by granting 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, so 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 Lumos Developer Docs (On-Premise Agent section).
  2. Create the service account with the permissions above (read-only for sync, write under the Base DN for provisioning).
Phase 2: Connect in Lumos
  1. Find the Active Directory box in your Lumos integrations (reconnect an existing card or add a new one) and download the connector package.
  2. Enter the authentication details:
    • Username: must include the domain, e.g. svc-lumos@testdomain.com.
    • Password: the service account password (or API token).
    • Domain Name: must include the TLD, e.g. testdomain.com.
    • Base DN: use uppercase attribute names, e.g. DC=testdomain, DC=com.
    • Port: the LDAP port (389 for LDAP, 636 for LDAPS).
    • 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.
    • 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. Connect.

​
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 it:
  • 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 — the AD integration still has to be added and enabled before it surfaces. Complete the post-agent configuration step to add the Active Directory integration, 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, and the “best match of” value in that error is the deepest part of the path AD could actually resolve, so 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=... genuinely 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, so 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, and note it has to go on Update rather than Create, because custom attributes on Create are applied before the password is set. 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, and these are the areas for your AD team to check, 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. Note that 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, but 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, the send has nowhere to go and is dropped while the reset itself still completes, which is why the password changes but nothing is delivered. An admin can enable Email under Settings > Notifications, no request to Lumos needed. You then need to run the reset once more, because 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.