Skip to main content

Connect Active Directory

G8 connects to one Active Directory. With the connection in place, people sign in on the usual form with their domain account, a directory group maps to a role in an environment, and one person can be added from the directory without a group. Everything on this page lives on the Directory tab under Users & access, apart from Add from directory, which sits on the Users tab. The tab's empty state says: Connect Active Directory to sign users in with their domain accounts and grant access by group.

Who may open it​

The Directory tab, the connection test, the group mappings and the resync need the platform permission identity.manage. Searching the directory for a person and Add from directory need users.manage. Only the Platform administrator holds platform permissions, and the menu shows Users & access to no one else. Every change on the tab is written to the platform audit log: the connection saved, each test with its outcome, a mapping added or removed, and a resync.

Connect Active Directory​

A directory connection lets people sign in with their domain account and gives them roles by group. Set it up once, on the Directory tab, which says Directory is not configured until you do. Select Connect Active Directory and fill in three sections. The team that runs the directory gives you the values.

SectionFieldValue
ServersServersA domain controller, as host or host and port, one entry per controller. They are tried in the order listed.
ServersTLSLDAPS · port 636 or StartTLS · port 389. Plain LDAP is not accepted.
ServersCA certificateThe certificate of the authority that issued the controllers' certificates, as PEM text.
Bind accountBind DN and Bind passwordA read-only service account the server searches users and groups with. The password is stored sealed and never shown again.
SearchUser base DN and Group base DNWhere users and groups are looked up. People are matched by their account name or their principal name.

Select Test connection to have the server bind with those values, then Save connection. The tab then shows the connection's state: Connected, Unreachable or Misconfigured.

What the server checks when you save​

A controller is written as a host, or as a host and a port. Without a port, LDAPS uses 636 and StartTLS uses 389; the help under the field adds: Host or host:port. Use 3269 for the Global Catalog. Referrals are not followed. A value written as an address with a scheme is refused, and a plain ldap:// address is refused as plain LDAP. Both modes end in TLS. With LDAPS the connection is encrypted from the first byte; with StartTLS it opens plain and is upgraded before anything else is sent, and a controller that refuses the upgrade is reported as such. The server verifies the controller's certificate against the CA you pasted, with the host name you typed as the expected name, and uses TLS 1.2 or newer. The help under the certificate field says: PEM. The server name must match the certificate; verification cannot be turned off.

The bind DN and the two base DNs have to look like distinguished names, with an = in every comma-separated part. The bind password is required the first time and optional afterwards, when an empty field keeps the stored one. A new password replaces the old one and is sealed under the server's secrets key before it is stored. The bind account is used for every search the server makes: A read-only service account used to search users and groups. It never signs anyone in; a person's own password is checked by binding as that person, see below.

What Test does​

Test connection on the form tests the values in the form, saved or not. Test connection on the tab tests the saved connection. Either way the server tries every controller in the list, in order: it opens the connection in the chosen TLS mode and binds with the bind DN and password. With the first controller that answers, it then reads the two base DNs, each with a one-object search at the base itself. The test passes only when every controller bound and both bases were read. The result lists one line per controller and per base, each naming what failed. The server tells these causes apart:

  • no answer from the controller;
  • a certificate that does not match the host name, has expired, or is not signed by the CA you pasted;
  • StartTLS refused by the controller;
  • the bind account rejected;
  • a controller that demands a signed connection;
  • a base DN the controller does not hold;
  • a port that answered, but not in the TLS mode chosen here.

A pass names the controller that answered, how long the bind took and the bind DN it used.

The form page runs that test once more right after Save connection, so the tab's state is current when it opens.

Run in the lab against the lab's domain controller, with a read-only bind account made for this installation: the test passed on the one controller, the bind took well under a second, and both base DNs were read. A connection saved through the API without that test showed as Unreachable until the first sign-in recorded a bind, which is what the states below say.

The three states​

The tab reads the state from the last bind the server recorded. A bind is recorded by the tab's test, by the test after a save, and by every use of the connection: a sign-in, a search, a membership refresh, a mapping added. The form's own test of unsaved values records nothing.

StateWhen it is shown
ConnectedThe last recorded bind succeeded.
UnreachableNo bind has succeeded yet, or the last one failed for any reason but a missing base DN: no controller answered, the certificate was refused, or the bind account was rejected.
MisconfiguredThe last failure was a base DN the controller does not hold. The bind itself worked; the user base DN or the group base DN is wrong.
The Directory tab with a connected directory: the card with the servers, TLS, CA, bind account and base DNs on the left, the last bind, the refresh and the user count on the right, and the group mappings table below.

Under the state, the card shows the last successful bind with the controller that answered, the last failure, the certificate's expiry and the number of users that came from the directory. A connection that cannot be reached does not sign anyone out on its own; the next section says what it does to signed-in people.

How a person is matched and signed in​

The sign-in form is the one everyone uses, as Sign in and first setup describes. A username the server does not know as a local account goes to the directory. The server searches under the user base DN for a person whose account name or principal name equals what was typed, and the description under the search section says the same: Users are matched by sAMAccountName or userPrincipalName; groups are resolved through the transitive chain. A domain prefix before a backslash is dropped first. When exactly one person matches, the server binds to the controller as that person's DN with the typed password; that bind is the password check, and the password is never stored. No match, two matches, or a refused bind all answer the same failed sign-in as a wrong local password.

The groups are read next, under the group base DN, with the directory's own chain rule, so a group that holds the person through other groups counts as theirs, and the person's primary group is added. A person the console has not seen before is created at that first sign-in with the roles their groups map to; a person whose groups map to no role is refused and the refusal is recorded. A person already known is refused when their account is disabled in G8, and otherwise their name, email and groups are refreshed from what the directory returned.

Run in the lab: a group of the directory was mapped to the Viewer role in one environment, and a person in that group who had never opened the console signed in with their domain account. The server created their account from the directory, with the name and email it holds there. The Directory tab then counted one user from the directory and showed the connection as connected, with the time and the controller of that bind.

Give a directory group a role​

Under Group mappings on the same tab, select Add mapping. In the dialog, type the group's name into Directory group and pick it from the matches, choose a Role and the Environment it applies in, and select Add mapping. The hint under the environment reads: Platform administrator needs no environment. Members of nested groups count as members.

The Add group mapping dialog: the directory group to search, the role, the environment and the Add mapping button.

From then on, a member of the group signs in on the same sign-in form as everyone else, with their directory username and password. Their account is created at their first sign-in, with the roles their groups map to. A person the console does not know yet, whose groups map to no role, is refused at sign-in. Group memberships are read again every 5 minutes while the person is signed in, and the last known memberships are kept when the directory cannot be reached.

The dialog says what the mapping does: Members of the group, including nested groups, get the role at their next sign-in or membership refresh. When you add it, the server looks the group up in the directory by its identifier and stores its name and DN with the mapping, so the directory has to answer at that moment. Group search returns up to 200 matches and asks you to narrow a wider query. A mapping is one row in the access table of every member: the role, the environment or every environment, and the group it came through.

A mapping is removed from its row under Group mappings, with Remove mapping. The server deletes the assignment, drops the group from its list when no other mapping names it, and writes an audit row. Access is computed at every request from the direct assignments and the group snapshot of the person, so a removed mapping, and a removed direct access, take effect at the person's next request. A new mapping counts for a signed-in member whose snapshot already holds the group at their next request, and for everyone else at their next sign-in or refresh. The empty table says: No group mappings yet. Members of a mapped group get the role at their next sign-in.

How memberships stay current​

The server keeps a snapshot of each directory user's groups, taken at sign-in. On a request made 5 minutes or more after the snapshot, the server reads the person's groups again under the bind account and replaces the snapshot. A failed attempt is retried a minute later at the earliest, not on every request. The card states it in one line: Every 5 minutes while signed in · last known kept for 1 hour when unreachable

  • When the directory cannot be reached, the snapshot stays as it was and the person keeps working. Once an hour has passed since the last successful refresh, the next request ends the session instead, and the person has to sign in again, which needs the directory. Each failed attempt to reach the directory writes directory.unreachable to the audit log, with one line per controller tried.
  • When the directory no longer has the person, the session ends and the account is marked as removed in G8; its roles stay until an administrator removes them, which is what the user's page says in that case.
  • When the directory has disabled the account, the session ends.
  • The directory's own changes to the mapping or the person apply at the next sign-in or refresh, as the form says: Changes apply to new sign-ins and the next membership refresh. Signed-in users keep their sessions.

Resync all under the mappings refreshes every active directory user now and reports how many were refreshed, which were removed or disabled in the directory, and how many could not be read. Resync groups on one user's page does the same for that person. When the directory does not answer, the user's page says: The directory did not answer. Memberships are unchanged. When the person is gone from the directory, it says: The directory has no entry for this user any more. The account keeps its access until you remove it.

Give one directory user a role​

A person can also get access on their own, without a group. On the Users tab, select Add from directory, type the person's name or username into Directory user, pick them, choose a Role and an Environment, and select Add user. Without a directory connection, the dialog says: Directory is not configured. Set the connection on the Directory tab first.

A person added this way signs in whether or not their groups are mapped. The Access table on their page lists every role they hold and says in Granted via whether it came as Direct or by Group. Removing access, or removing a mapping, takes effect at the person's next request.

The dialog describes itself as: Search the directory for a person and grant their first access. The search runs under the bind account and shows up to 200 people, marking those already added and those disabled in the directory. On Add user the server reads the person and their groups from the directory, refuses a disabled account and a person already added, creates the account with its group snapshot and grants the role. A directory that does not answer during the search or the add is reported as: The directory did not answer. Try again in a moment.

What stays in the directory​

A directory user's password is never stored in G8 and cannot be reset here; the user's page offers no password reset for them, and the account menu shows them no password change. Their username, display name and email are read from the directory and refreshed with their groups; the edit form of a local user is refused for them. Disabling the account in G8 stops their sign-in whatever the directory says, and the directory disabling them ends their session at the next refresh.

G8 dev