Active Directory

Connect Microsoft Active Directory to Nametag with the directory agent.

The Active Directory agent connects Nametag to an on-premises Microsoft Active Directory domain. It synchronizes accounts and security groups and performs password resets and account unlocks. The agent runs in your environment, so you do not provide Active Directory credentials to Nametag.

Prerequisites

Before starting, prepare:

A Windows machine joined to the Active Directory domain.
The Nametag CLI.
The PowerShell ActiveDirectory module.
A dedicated domain account under which to run the agent.
Outbound access to nametag.co over HTTPS on TCP port 443.

The agent account typically receives sufficient read access from Active Directory’s default permissions. You must separately delegate the write permissions needed for password resets and account unlocks.

Choose which accounts to synchronize

By default, the agent synchronizes every account in the domain. You should limit the agent to the organizational units containing the people who will use Nametag recovery:

nametag dir agent ad `
  --search-base "OU=Employees,DC=example,DC=com" `
  --search-base "OU=Contractors,DC=example,DC=com"

Repeat --search-base to include more than one organizational unit. Each value must be the distinguished name of an existing organizational unit or container.

--search-base controls which accounts the agent synchronizes, but it is not an Active Directory security boundary. The permissions delegated to the agent account determine which accounts it can actually modify. Use the same organizational units for synchronization scope and delegated permissions whenever possible.

Delegate permissions to the agent account

Delegate permissions on each organizational unit named by --search-base. Do not delegate them at the domain root; doing so can grant the agent rights over every account in the domain, including administrative and built-in accounts.

Recovery operation	Permission to delegate
Reset a password	Reset Password and write access to `pwdLastSet`
Unlock an account	Write access to `lockoutTime`

Delegate only the permissions for operations you intend to enable. Reset Password is different from Change Password: the agent must be able to set a password without knowing the old one.

Register and run the agent

First, authenticate the CLI and list your Nametag environments:

nametag auth login
nametag env list

Copy the ID of the environment where you want to create the directory, and then register the agent:

nametag dir agent register --env <environment-id>

The registration command prints a directory agent token. Treat this token as a secret. Set it in the environment of the dedicated agent account, and then start the agent with the account scope you selected earlier:

$env:NAMETAG_AGENT_TOKEN = "<agent-token>"

nametag dir agent ad `
  --search-base "OU=Employees,DC=example,DC=com" `
  --search-base "OU=Contractors,DC=example,DC=com"

Run the command as the dedicated account to which you delegated permissions. A healthy agent remains running, reports that it is connected, and begins synchronizing the directory.

You can run a second agent with the same account and group scopes for high availability. Nametag distributes requests among compatible connected agents.

Configure groups used by recovery policies

By default, every security-enabled group in the domain is available when you create a recovery policy. Distribution groups are not included. To limit the available security groups, specify the containers in which they reside:

nametag dir agent ad `
  --search-base "OU=Employees,DC=example,DC=com" `
  --group-search-base "OU=Groups,DC=example,DC=com"

Repeat --group-search-base to include additional containers. This option limits both the groups shown in the Nametag console and the memberships used to evaluate recovery policies.

Group policies apply to a user’s direct group memberships and primary group. Nested membership is not expanded. For example, if a user belongs to Group A and Group A belongs to Group B, a policy on Group B does not apply to that user. Add users directly to any security group whose allow or deny policy must govern them.

The agent serves only the domain to which its machine is joined. Keep a one-to-one relationship between Nametag directories and Active Directory domains: one Nametag directory should contain accounts and groups from one domain. To connect another domain, register a separate directory in Nametag and run an agent for it on a machine joined to that domain, using the new directory’s agent token.

Changing an account or group search base requires a full synchronization so that Nametag can rebuild the directory under the new scope.

Synchronize dates of birth

Active Directory has no date of birth attribute, so the agent reads one only from an attribute you name:

nametag dir agent ad `
  --search-base "OU=Employees,DC=example,DC=com" `
  --birthdate-attribute extensionAttribute1

The attribute must be defined in the forest schema and readable on user objects. The agent verifies both at startup and refuses to serve the directory otherwise.

A value is read as a date when it is YYYY-MM-DD, RFC 3339, YYYYMMDD, or a Generalized-Time. Anything else: N/A, a note, or a day-first or month-first date, which cannot be told apart - is ignored, and the account synchronizes without a date of birth. The agent reports how many accounts this applied to at the end of each synchronization.

The attribute may hold a hashed birthdate instead of a plain date, in any of the formats Nametag accepts there. A hash is passed through as it is, so $hs256$ values require your directory’s shared secret to be set first; without it a synchronization that carries one fails rather than skipping the account.

Adding this option fills in the date of birth for each account the next time that account changes. Run a full synchronization to fill in all of them at once. Agents serving one directory must use the same attribute, just as they must use the same search bases.

Optional settings

Option	When to use it
`--birthdate-attribute extensionAttribute1`	Read each account’s date of birth from the named attribute. Active Directory has no date of birth attribute, so none is read unless you name one.
`--domain-controller dc01.example.com`	Pin account and group reads to a particular domain controller. Omit it to use automatic discovery.
`--verbose`	Include routine requests and synchronization diagnostics while troubleshooting.
`--allow-privileged-accounts`	Allow recovery of accounts that AD marks as administratively privileged. This disables an important safeguard and is not recommended.

Run nametag dir agent ad --help for the corresponding environment variables and all available options.

Troubleshooting

Password reset or unlock is denied

Confirm that the account running the agent has the required permission on every target account. A missing write permission may not be apparent during synchronization because ordinary directory reads can still succeed.

An administrative account cannot be recovered

By default, the agent refuses to reset or unlock an account for which Active Directory has set adminCount=1. Active Directory does not automatically clear this value after an account is removed from a protected administrative group, so former administrators can also be affected. Check the account with:

Get-ADUser -Identity jdoe -Properties adminCount |
  Select-Object SamAccountName,adminCount

Correct stale administrative-account attributes and ACL inheritance in Active Directory rather than disabling the safeguard. Use --allow-privileged-accounts only when your security policy explicitly requires it.

A user cannot be matched for recovery

The agent identifies accounts using mail, userPrincipalName, and sAMAccountName. For identity name matching, it prefers givenName and sn, then displayName, and finally the account’s common name. Populate givenName and sn with the user’s real name for the most reliable matching.

To inspect these attributes:

Get-ADUser -Identity jdoe -Properties mail,userPrincipalName,givenName,sn,displayName |
  Select-Object SamAccountName,mail,userPrincipalName,givenName,sn,displayName

More diagnostic output is needed

Restart the agent with --verbose, or set NAMETAG_AD_VERBOSE=true in its environment. Return to standard logging after troubleshooting.

After the directory has synchronized, configure recovery access using the self-service account recovery administrator’s guide.