> ## 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. # Active Directory (NHI) > Connect a read-only account to on-prem Active Directory so Lumos can inventory service accounts, managed service accounts, computers and trust accounts, with their credentials and access. ## What You're Setting Up You're giving Lumos a **read-only account** in your on-prem Active Directory domain. The connector runs on the [Lumos On-Premise Agent](https://docs.lumos.com/integrations/on-premise-agent/agent-quickstart-guide.md) inside your network and reads the directory over LDAP. In Lumos, the integration card is named **Active Directory (NHI)**. The sync reads your domain's non-human identities into the NHI inventory: | Account type | What it is | | :- | :- | | Service account | A user account classified as non-human (see **How user accounts are classified**) | | sMSA | Standalone managed service account | | gMSA | Group managed service account | | Computer | Computer accounts, including domain controllers | | krbtgt | The domain `krbtgt` account and per-RODC `krbtgt_*` accounts | | Trust | Interdomain trust accounts | For each one, Lumos also reads the credentials that authenticate as it (one password per account, plus one credential per certificate or certificate mapping), the hosts it runs on, and the access that scopes it: group memberships, Kerberos constrained and resource-based delegation, gMSA password retrieval rights, and directory control rights (reset password, write SPN, write DACL). This is a separate connector from the standard **Active Directory** integration, which manages human accounts. Connecting one does not connect the other. **What Lumos does NOT do:** * **No writes.** The connector never modifies the directory. * **No secret reads.** Lumos never reads password hashes, `msDS-ManagedPassword`, or other secret material. Credentials are inventoried by metadata only: expiry, rotation interval, whether the password must change, and certificate thumbprint and validity dates. *** ## Prerequisites * A **Lumos On-Premise Agent** that can reach a domain controller on the LDAP port (389) or the LDAPS port (636). * A **domain administrator**, or someone who can create an account and delegate read access in the domain. * The domain's **Base DN**, for example `dc=example,dc=com`. *** ## Step 1: Create the read-only account Choose one of two credentials. **Service account (username and password).** Create a standard domain user for Lumos, for example `svc-lumos-nhi`. Don't add it to any privileged group. You enter its password in Lumos, which stores it encrypted. **Group Managed Service Account (gMSA).** Use this when your policy doesn't allow storing AD credentials in Lumos. The agent host binds with its own Windows Kerberos ticket, so no password is entered in or stored by Lumos. 1. Create a gMSA and allow the agent host to retrieve its password. See Microsoft's [Get started with group managed service accounts](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-managed-service-accounts/group-managed-service-accounts/getting-started-with-group-managed-service-accounts). 2. Run the On-Premise Agent on Windows (bare-metal, VM, or Windows container). Linux hosts and Linux Docker containers are not supported. 3. Configure the Windows service that runs the agent to log on as the gMSA. ## Step 2: Confirm the account can read security descriptors Every object in Active Directory carries a security descriptor: an owner and a DACL, the list of who may do what to that object. Lumos reads the DACL on each user, computer and group object to find who can reset an account's password, write its SPNs, or change its permissions. It reads the gMSA password-retrieval list the same way. Lumos reads only the owner and DACL, never the SACL (the audit settings). Reading a DACL takes the **Read Permissions** right on the object. In a default domain, Authenticated Users hold it on most objects, so a new domain user usually needs nothing extra. Two common exceptions: * **Hardened OUs.** Some domains remove Authenticated Users from sensitive OUs, such as a Tier 0 or admin-accounts OU. * **Protected accounts.** Accounts in Domain Admins and other protected groups take their permissions from the `AdminSDHolder` object, which may have been tightened in your domain. If either applies, grant the Lumos account **Read Permissions** on those OUs, applied to descendant user, computer and group objects, and on `AdminSDHolder` (`CN=AdminSDHolder,CN=System,`). Lumos checks this when you connect, but only on a small sample of user objects. If none of them are readable, validation fails. If the sample is readable but some OUs are not, validation passes and the objects Lumos can't read show no control rights. Those are usually the most sensitive accounts, so check this step before you connect. ### Required access Active Directory has no permission scopes for LDAP clients. The account reads whatever the directory's object permissions allow, so this is the full list of what it needs. All of it is read-only. | Access | On | Feeds | | :- | :- | :- | | Read properties | User, computer, group, managed service account and trust objects under the Base DN | Inventory, classification, credentials, group memberships, delegation, hosts | | Read Permissions (owner and DACL) | User, computer and group objects under the Base DN | Control rights: reset password, write SPN, write DACL | The attributes Lumos reads are `sAMAccountName`, `userPrincipalName`, `objectGUID`, `objectSid`, `objectClass`, `userAccountControl`, `servicePrincipalName`, `memberOf`, `member`, `primaryGroupID`, `pwdLastSet`, `lastLogon`, `lastLogonTimestamp`, `logonCount`, `adminCount`, `whenCreated`, `userCertificate`, `altSecurityIdentities`, `msDS-AllowedToDelegateTo`, `msDS-AllowedToActOnBehalfOfOtherIdentity`, `msDS-GroupMSAMembership`, `msDS-ManagedPasswordInterval`, `msDS-HostServiceAccountBL`, `operatingSystem`, `dNSHostName`, `trustDirection`, `trustPartner`, `trustType`, and `nTSecurityDescriptor` (owner and DACL only). ## Step 3: Connect in Lumos 1. In Lumos, go to **Integrations → Add Integration** and search for **Active Directory (NHI)**. 2. Choose **Service Account** or **Group Managed Service Account (gMSA)**. For a service account, enter: * **Username**: any format AD accepts, such as a distinguished name (`CN=Lumos,OU=Service Accounts,DC=example,DC=com`), a UPN (`lumos@example.com`), or `DOMAIN\samaccountname`. * **Password** 3. Fill in the settings: | Setting | What to enter | | :- | :- | | **Host Name** | A domain controller, for example `dc01.example.com`. The domain name also works. For gMSA, this must be the domain controller's fully qualified hostname. | | **Base DN** | The directory's base DN, for example `dc=example,dc=com` | | **Port** | `389` for LDAP, `636` for LDAPS. Defaults to `389` | | **Protocol** | **LDAP** or **LDAPS**. LDAPS encrypts all traffic, including the bind credentials | | **Validate Certificate** | LDAPS only. Off by default | | **Service Account OUs** | Optional. OUs whose user accounts count as service accounts. One per line | | **Service Account Name Prefixes** | Optional. `sAMAccountName` prefixes that mark a service account, for example `svc-`. One per line | | **Classify Non-Expiring Passwords as Service Accounts** | Optional. Off by default. See below | | **App Identifier** | Optional. Defaults to the Host Name | 4. Select **Validate**, then **Complete**. *** ## How user accounts are classified Managed service accounts, computers, krbtgt and trust accounts are always non-human. A regular user account is classified as a service account when any of these is true: * It has a `servicePrincipalName`. * Its `sAMAccountName` starts with a listed prefix. * It sits under a listed OU. * **Classify Non-Expiring Passwords as Service Accounts** is on and its password never expires (`userAccountControl` flag `0x10000`). Everything else is a human account. The non-expiring password option is off by default because admin and break-glass accounts often have the same flag. Review the results before you rely on it. Exchange system mailboxes are skipped everywhere. *** ## Scan behavior * **Last login.** `last_login` comes from `lastLogonTimestamp`, which Active Directory replicates only every 9 to 14 days, so it lags real logons by that much. `last_logon` and `logon_count` are not replicated: they come from whichever domain controller answered. Point **Host Name** at one domain controller if you need those two values to be consistent. * **Hosts.** A computer account runs on its own host, and an sMSA runs on the computer it is bound to. A gMSA is linked to every computer allowed to retrieve its password, directly or through nested groups. That list shows where the gMSA can run, not proof that it does. * **Privileged groups.** Domain Admins, the operator groups, and Key Admins are flagged as privileged, identified by SID. * **Everyone and Authenticated Users.** These appear as fixed groups. Every account is a member of both, so a right granted to either reaches every account. * **Deny ACEs are ignored.** A right that a DACL grants and then denies is reported as granted, so the access graph can overstate access but never understate it. * **Primary group.** Lumos resolves each account's primary group. When that group sits outside the Base DN, for example Domain Users under an OU-scoped Base DN, the membership is skipped. *** ## Troubleshooting **"Failed to connect to Active Directory".** The agent can't reach the domain controller. Check the Host Name, the Port, and the network path from the agent host. **"SSL/TLS connection failed".** The domain controller's certificate is invalid, expired, or not trusted by the agent. Fix the certificate, [add your CA to the agent](https://docs.lumos.com/integrations/on-premise-agent/adding-additional-ca-certificates.md), or turn off **Validate Certificate**. **Validation fails: "The account cannot read security descriptors (DACLs)".** Grant the account Read Permissions on the user, computer and group objects in the Base DN (Step 2). **A sync fails with `security_descriptor_unreadable`.** The account lost read access to security descriptors after you connected. Lumos fails the sync instead of reporting no control rights. Restore the permission from Step 2. **gMSA bind fails.** Check that the agent runs on Windows, that the gMSA is installed on that host, and that Host Name is the domain controller's fully qualified hostname, not an IP address. *** ## Security FAQ **Does Lumos read password hashes or gMSA passwords?** No. The connector never reads password hashes, `msDS-ManagedPassword`, or other secret material. For gMSAs it reads only who is allowed to retrieve the password, from `msDS-GroupMSAMembership`. **Does the account need administrative rights?** No. It needs to read directory objects and their security descriptors. Don't add it to Domain Admins or any other privileged group. **How are credentials handled?** With a service account, Lumos stores the password encrypted, and the agent uses it for a simple LDAP bind. Use LDAPS so the password is encrypted in transit. With a gMSA, Lumos stores nothing: the agent host authenticates with its own Kerberos ticket, and Windows rotates the gMSA password. **Can I remove the integration later?** Yes. Disable or delete the account in Active Directory. The next sync fails to bind.