Active Directory
With Active Directory, people sign in to Delegaris with the same username and password they use for Windows. Delegaris checks the password against a domain controller over LDAPS and reads the person's groups, including groups inside groups.
What you need
- The domain's DNS name, for example
ad.example.com. - A service account: an ordinary domain user is enough. Delegaris only reads from the directory with it.
- Network access from the Delegaris container to your domain controllers on port 636 (LDAPS), or 389 for STARTTLS.
- If an internal CA issued the domain controllers' certificates, that CA's certificate in PEM form.
How a sign-in works
- Delegaris connects to a domain controller and signs in as the service account.
- It looks the person up by what they typed.
- It signs in again as that person, with the password they typed. If the directory accepts it, the password is right.
- It reads the groups the person belongs to.
People can type their username as jsmith, CORP\jsmith or jsmith@corp.example. The built-in search matches the account name (sAMAccountName) or the user principal name.
The sign-in page shows "Use the username and password you sign in to Windows with." under the form when Active Directory is switched on.
Setting it up under Settings > Sign-in
Sign in as the local administrator and open Settings > Sign-in. The Active Directory section is set up the way you would join a machine to the domain.
| Field | What to enter |
|---|---|
| Domain | The domain's DNS name, for example ad.example.com |
| Service account | A user in the domain. A plain name (svc-delegaris), user@domain, or a full DN |
| Service account password | That user's password. Stored in the database and never shown again. Leave empty to keep the saved one |
Then:
- Under Ways in, tick Active Directory (or leave every box unticked to use whatever is filled in).
- Choose the Connection security (see below).
- Press Test the directory (see Testing).
- Name your administrators under Administrators (see How sign-in works).
- Press Save sign-in settings. The change applies at once, on every copy of the service.
Once saved, a line under the password says what is in use now: the controllers found, where people are searched for, and the name the service signs in as.
What the domain fills in for you
From the domain name alone, Delegaris works out the rest:
- Domain controllers are found through the domain's DNS SRV records (
_ldap._tcp.dc._msdcs.<domain>), best first. If there are no SRV records, the domain name itself is used, which AD also resolves to its controllers. The list is remembered for five minutes. - The search base is the whole domain, for example
DC=ad,DC=example,DC=com. - The service account is used as
svc-delegaris@ad.example.comwhen you give a plain name.
Connection security
| Choice | Port | Notes |
|---|---|---|
| LDAPS (636, encrypted from the start; recommended) | 636 | Domain controllers accept it out of the box |
| STARTTLS (389, upgraded to TLS before anything is sent) | 389 | |
| Plain LDAP (389, no encryption) | 389 | Passwords cross the network in clear text. Only for a lab or a network you trust end to end |
Two more options sit under the choice:
- Check the domain controllers' certificates (on by default). Leave it on. If it is off, Delegaris logs a warning at startup.
- Follow groups inside groups (on by default). With it on, someone in group A, which is inside group B, counts as a member of B.
CA certificate (PEM) takes the certificate of an internal CA that issued the domain controllers' certificates. Paste it in, starting -----BEGIN CERTIFICATE-----. If one is already saved, leave the box empty to keep it.
Advanced settings
Open Advanced: name the controllers, search bases and filter yourself for unusual directories.
| Field | When to use it |
|---|---|
| Domain controllers | To name the controllers instead of finding them through DNS. Comma separated, with scheme and port, for example ldaps://dc1.ad.example.com:636, ldaps://dc2.ad.example.com:636. The first that answers is used |
| Search users under | To search only part of the directory. Empty means the whole domain. Write a path as AD Users and Computers shows it (Company/Staff) or a DN (OU=Staff,OU=Company); the domain part is added for you |
| Search groups under | To search groups somewhere else. Empty means the same as users |
| User filter | The LDAP filter that finds a person by what they type. It must contain {username}. The built-in filter matches sAMAccountName or userPrincipalName |
Setting it up in .env
The same settings can be given in .env instead. The simple form:
LDAP_DOMAIN=ad.example.com
LDAP_BIND_DN=svc-delegaris
LDAP_BIND_PASSWORD=change-me
ADMIN_GROUPS=Delegaris-Admins
The full list:
| Setting | Default | Purpose |
|---|---|---|
LDAP_DOMAIN | none | The domain's DNS name. Fills in the rest as described above |
LDAP_BIND_DN, LDAP_BIND_PASSWORD | none | The service account and its password |
LDAP_URL | found through DNS | Domain controllers, comma separated, for example ldaps://dc1.corp.example:636 |
LDAP_BASE_DN | the whole domain | Where to search for people |
LDAP_GROUP_BASE_DN | same as LDAP_BASE_DN | Where to search for groups |
LDAP_START_TLS | false | Use STARTTLS on 389 |
LDAP_ALLOW_INSECURE | false | Allow plain LDAP with no encryption |
LDAP_TLS_VERIFY | true | Check the domain controllers' certificates |
LDAP_CA_CERT_FILE | none | The internal CA's certificate, mounted into the container |
LDAP_NESTED_GROUPS | true | Follow groups inside groups |
LDAP_USER_FILTER | matches sAMAccountName or userPrincipalName | The search for a person; must contain {username} |
LDAP_TIMEOUT_SECONDS | 10 | How long to wait for a domain controller |
Without LDAP_DOMAIN, you must give LDAP_URL, LDAP_BIND_DN, LDAP_BIND_PASSWORD and LDAP_BASE_DN yourself.
What you save under Settings > Sign-in overrides .env.
If LDAP_URL is not ldaps:// and neither LDAP_START_TLS nor LDAP_ALLOW_INSECURE is set, Delegaris refuses to start rather than send passwords in clear text.
Testing the directory
The test does everything a real sign-in does, step by step, and stops at the first step that fails, saying why. It uses what is in the form, saved or not, so you can test before you save.
- Optionally fill in Test as with someone in the domain, for example
jsmith. Leave it empty to check only the service account. - Optionally fill in Their password. It is checked and never saved.
- Press Test the directory.
Each step is shown with a tick or a cross:
| Step | What it checks |
|---|---|
| Connect to a domain controller | The container can reach a controller and the TLS connection works |
| Sign in as the service account | The service account's name and password are right |
| Find name | The person exists under the search base, and exactly one account matched |
| List their groups | Their group membership can be read. Shows how many groups |
| Sign in as them | Only with a password: the directory accepts it |
When everything works, the result says so, with the controller used, how long it took and the person's groups. Use those group names in access rules.
Common failures and what they mean:
- The search base does not exist in the directory. It needs to end with the domain's DC parts, for example
OU=People,DC=ad,DC=example,DC=com. - The directory wants a signed-in connection for searches. Check the service account.
- The search base belongs to another domain. Use one under this domain.
- No account matched, or more than one did. Check the search base and the user filter.
Finding groups and people
Wherever Delegaris asks for a group or a person (access rules, approvers, administrators, roles), a Find… button searches the directory, so you can pick a name instead of typing it exactly.
- Groups are matched by account name, name or description.
- People are matched by account name, display name, name, email or user principal name.
- Results show the display name, the account name, and for groups the description and number of members.
- The first 50 results are shown; type more to narrow them down.
Under Settings > Sign-in, once Active Directory is on, Browse groups… and Browse people… show the same search, and tell you the exact name to use in rules.
The search uses the service account and is available to administrators only.
Groups and names
- Groups are matched by name, ignoring case. Both a group's account name and its common name count.
- Nested membership counts when Follow groups inside groups is on.
- A person's primary group (normally Domain Users) is not reported by AD. To give something to everyone, use Everyone who signs in in an access rule.
- Changes to someone's group membership count from their next sign-in.
- The person's email address for Slack comes from their
mailattribute, or failing that their user principal name.
When the directory cannot be reached
If no domain controller answers, or the service account is refused, people see "The directory could not be reached. Please contact an administrator." The reason is in the service log and in the activity log. The local administrator still works.
Next steps
- Two-step sign-in
- Access rules
- Entra ID, if you run both during a move