Skip to main content

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​

  1. Delegaris connects to a domain controller and signs in as the service account.
  2. It looks the person up by what they typed.
  3. It signs in again as that person, with the password they typed. If the directory accepts it, the password is right.
  4. 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.

FieldWhat to enter
DomainThe domain's DNS name, for example ad.example.com
Service accountA user in the domain. A plain name (svc-delegaris), user@domain, or a full DN
Service account passwordThat user's password. Stored in the database and never shown again. Leave empty to keep the saved one

Then:

  1. Under Ways in, tick Active Directory (or leave every box unticked to use whatever is filled in).
  2. Choose the Connection security (see below).
  3. Press Test the directory (see Testing).
  4. Name your administrators under Administrators (see How sign-in works).
  5. 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.com when you give a plain name.

Connection security​

ChoicePortNotes
LDAPS (636, encrypted from the start; recommended)636Domain controllers accept it out of the box
STARTTLS (389, upgraded to TLS before anything is sent)389
Plain LDAP (389, no encryption)389Passwords 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.

FieldWhen to use it
Domain controllersTo 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 underTo 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 underTo search groups somewhere else. Empty means the same as users
User filterThe 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:

SettingDefaultPurpose
LDAP_DOMAINnoneThe domain's DNS name. Fills in the rest as described above
LDAP_BIND_DN, LDAP_BIND_PASSWORDnoneThe service account and its password
LDAP_URLfound through DNSDomain controllers, comma separated, for example ldaps://dc1.corp.example:636
LDAP_BASE_DNthe whole domainWhere to search for people
LDAP_GROUP_BASE_DNsame as LDAP_BASE_DNWhere to search for groups
LDAP_START_TLSfalseUse STARTTLS on 389
LDAP_ALLOW_INSECUREfalseAllow plain LDAP with no encryption
LDAP_TLS_VERIFYtrueCheck the domain controllers' certificates
LDAP_CA_CERT_FILEnoneThe internal CA's certificate, mounted into the container
LDAP_NESTED_GROUPStrueFollow groups inside groups
LDAP_USER_FILTERmatches sAMAccountName or userPrincipalNameThe search for a person; must contain {username}
LDAP_TIMEOUT_SECONDS10How 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.

warning

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.

  1. Optionally fill in Test as with someone in the domain, for example jsmith. Leave it empty to check only the service account.
  2. Optionally fill in Their password. It is checked and never saved.
  3. Press Test the directory.

Each step is shown with a tick or a cross:

StepWhat it checks
Connect to a domain controllerThe container can reach a controller and the TLS connection works
Sign in as the service accountThe service account's name and password are right
Find nameThe person exists under the search base, and exactly one account matched
List their groupsTheir group membership can be read. Shows how many groups
Sign in as themOnly 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 mail attribute, 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​