Gatehouse
Sign inGet started
DocsEnterprise identity

Active Directory and LDAP

Sync groups and accounts from on-premises Active Directory or any LDAP directory, and optionally sign in with directory passwords.

Gatehouse can read groups and people straight from Active Directory, OpenLDAP, FreeIPA, 389 Directory Server or any LDAP v3 directory. You write policies for the groups you already have. When someone joins, moves or leaves in the directory, Gatehouse follows.

It only reads. Nothing is written back to the directory.

Your setup Use
On-premises Active Directory, or a self-hosted, air-gapped install Directory sync (this page)
Microsoft Entra ID (Azure AD), Okta, OneLogin, JumpCloud SCIM, or a groups claim at sign-in
AD with ADFS for sign-in Directory sync for groups, plus SAML for sign-in

How it works

Gatehouse connects out to a domain controller over LDAPS with a read-only service account, on a schedule you choose. There is no agent to install and no inbound port to open.

On each sync it:

  1. Reads the groups you selected, by name. * wildcards are allowed, like GH-*.
  2. Works out each group's members, including nested groups. It uses group member and user memberOf together, so it works on AD and OpenLDAP alike.
  3. Creates accounts for members who don't have one, with the role you choose (never Owner).
  4. Disables accounts that are disabled in the directory or deleted from it. Disabling signs the person out and revokes every agent token at once. If they are re-enabled in the directory, the next sync turns their account back on.
  5. Sets each synced group's members to match the directory.

If a local Gatehouse group has the same name as a directory group, the sync takes it over. An owner can create Platform, write policies for it, then connect AD, and the policies keep working.

A group that disappears from the directory, or from your selection, is kept but emptied. It is marked No longer in the directory, and its policies stay in place for you to review.

Connect a directory

You need to be an owner.

  1. Create a read-only service account in AD, like svc-gatehouse. It only needs to read users and groups.
  2. Go to Settings → Directory sync → Connect a directory.
  3. Fill in:
    • Server URL: ldaps://dc1.corp.example.com:636, or ldap://… with Use StartTLS.
    • CA certificate: paste your internal CA (PEM) if the domain controller's certificate comes from it.
    • Service account and Password: a DN like CN=svc-gatehouse,OU=Service,DC=corp,DC=example,DC=com, or a UPN like svc-gatehouse@corp.example.com.
    • Base DN: DC=corp,DC=example,DC=com.
    • Groups to sync: one name per line, like GH-* or Platform Engineering.
  4. Click Save and test. Gatehouse connects, then shows how many accounts and groups it found and which groups match your selection. Nothing changes yet.
  5. When the preview looks right, click Sync now.

After that, it syncs every 60 minutes by default. Set Sync every to 0 to sync only by hand.

The service account password is encrypted with the master key, like every other stored credential.

Options

Option Default What it does
Include members of nested groups On Members of Backend, nested in Engineering, count as members of Engineering.
Create accounts for group members On Members of synced groups get a Gatehouse account automatically.
Disable accounts that are disabled or deleted in the directory On Leavers lose access at the next sync. The last active owner is never disabled.
Let people sign in with their directory password Off See below.
New accounts get the role Member Member, Auditor or Admin.

Advanced lets you set separate search bases for users and groups, custom LDAP filters, and the attributes for email, name, unique ID and group name. The defaults are:

Active Directory OpenLDAP / other
Users (&(objectCategory=person)(objectClass=user)) (|(objectClass=inetOrgPerson)(objectClass=person))
Groups (objectClass=group) groupOfNames, groupOfUniqueNames or posixGroup
Unique ID objectGUID entryUUID
Name displayName cn

Accounts and groups are linked by unique ID, so renames in the directory carry over. Renaming a group also renames it in every policy.

People without an email address in the directory are skipped and listed in the sync result.

Signing in with directory passwords

Turn on Let people sign in with their directory password to have Gatehouse check passwords against the directory. This is useful when you have no SSO provider, such as in an air-gapped install. Gatehouse looks the person up with the service account, then binds as them with the password they typed.

  • Two-step verification, lockout and the network allow-list still apply.
  • Empty passwords are always refused. Many LDAP servers treat them as anonymous binds and would otherwise report success.
  • Locked and disabled Gatehouse accounts never reach the directory, so repeated failures can't lock someone out of Windows.

If you have ADFS, Entra ID or another SSO provider, prefer single sign-on. Use the directory for groups only.

Troubleshooting

Message Fix
The directory rejected the service account DN or password Check the DN or UPN and password. In AD, error 52e means bad credentials.
Could not reach the directory server Check the host, port (636 for LDAPS) and firewall from the Gatehouse host.
The directory's TLS certificate isn't trusted Paste your CA certificate. Only turn off certificate checks in a lab.
The base DN was not found Check spelling, like DC=corp,DC=example,DC=com.
None of the groups match your selection Compare the names in the test result with Groups to sync. Matching ignores case.

Every sync is recorded in the audit log as directory.synced or directory.sync_failed, with the counts. So is each account it created, disabled or re-enabled, and each change to a group's members.