Adding an Active Directory Connector
How to point a XONA appliance at Active Directory so your users sign in with their domain credentials, and their AD group membership decides what they can reach. Nine steps, in order.
Naming: this article uses the v5.5.4 product names - Gateway (formerly CSG) and Manager (formerly XCM). Appliances on older versions, and their documentation, use the old names for the same things.
What a connector actually does
A connector tells the appliance one domain, one directory server, over LDAPS. When a user signs in as jsmith@corp.example.com, the appliance matches the domain part to a connector and authenticates against that server.
ℹ There is no service account, and no Base DN field - this surprises people
The appliance binds to LDAP as the user who is logging in, using the password they just typed. Nothing is stored on the appliance for the directory, and nobody needs to create a bind account for you.
The search base is derived from the domain automatically:
corp.example.combecomesDC=corp,DC=example,DC=com.
Before you start
- ☐ The fully qualified domain name users will log in with, for example
corp.example.com - ☐ The hostname or IP of a domain controller that answers LDAPS
- ☐ TCP 636 open from the appliance to that domain controller
- ☐ If you intend to verify the server certificate: the PEM-encoded CA certificate that issued the domain controller's LDAPS certificate
- ☐ One test AD account you can log in with
⛔ LDAPS is required. There is no way around it
XONA appliances do not connect to Active Directory without TLS. Plain LDAP on port 389 will not work, and STARTTLS is not supported either - it must be LDAPS, normally on port 636. If your domain controllers do not have LDAPS certificates yet, that is the first piece of work, and it happens on the Windows side, not on the appliance.
⚠ Check the appliance clock first
Go to Settings → Appliance → Date/Time and confirm Last Sync Time does not read "Pending". A skewed clock makes certificate validation fail and breaks MFA at the same time, which sends people hunting for an LDAP problem that is not there.
Adding the connector
1. Appliance - Prove the appliance can reach the directory over LDAPS
Do this before touching any settings - it separates "the network is blocked" from "the connector is wrong", and those two look identical once you are staring at a failed login.
| Test LDAPS reachability from the appliance CLI - CLI |
|---|
ctl networking test-tls-server dc01.corp.example.com 636 true |
The last argument is whether to verify the server certificate. Run it with true first. If that fails but false succeeds, the network path is fine and your problem is certificate trust - which is step 2.
2. Appliance - Load the issuing CA certificate, if you will verify certificates
Skip this step if you plan to leave Verify Server Cert off. If you plan to turn it on, the appliance has to trust whoever issued the domain controller's LDAPS certificate - and for a Microsoft internal CA it will not by default.
Go to Settings → System Settings → Certificates and add the CA certificate to the trusted CA certificates set. It must be PEM-encoded; a file containing several CAs in a chain is accepted. No private key is involved.
⚠ This is not the appliance's own server certificate
The same page holds two different things, and they point in opposite directions:
Server certificate Trusted CA certificates What the appliance presents to browsers and ctl, so they trust it. Needs a private keyWhat the appliance uses to validate the servers it connects out to, including the domain controller. Public CA certificates only Replacing the web UI's server certificate does nothing for Active Directory. Conversely, Reset server certificate does not clear the trusted CA set, so it will not break a working connector.
3. Appliance - Open the Active Directory page and start a new connector
Go to Settings → Authentication → Active Directory, then press Add Active Directory Connector.
You can add more than one. The domain is what picks between them at login time, so each connector needs its own.
4. Appliance - Fill in the connector fields
| Field | What to enter |
|---|---|
| Name | A label for you, for example Corporate AD. Must be unique on the appliance |
| Hostname | The domain controller, for example dc01.corp.example.com. A hostname is better than an IP if you are verifying the certificate, because the name has to match what the certificate says |
| Port | 636 for LDAPS. Use 3269 only if you deliberately want the Global Catalog over SSL |
| Domain | The fully qualified domain, for example corp.example.com. This is the part users type after the @ in their username |
| Verify Server Cert | On is the secure choice, and requires step 2. Off skips validation of the directory server's certificate |
| Enable Group Sync | On if you want AD group membership to drive appliance group membership. See step 7 |
| Enable Nested Group Search | Leave off unless you know you need it. See the warning below |
| Disabled | Leave off. A disabled connector rejects logins for its domain outright. It is also the switch you use to park AD logins during a fabric upgrade - see below |
⚠ Nested Group Search is not free, and it has a history
It costs performance on both the appliance and the domain controller even on directories with no nested groups. Only turn it on if users get their appliance access through a parent-of-a-parent group.
On v5.5.0 and v5.5.1 it was enabled by default, and it broke login with a bare "Unauthorized" for any user whose DN contained special characters. The fix is hotfix v5.5.1.2657 or later; the workaround is turning it off. If you are on one of those builds, check this box's state rather than assuming.
A domain can only belong to one connector, and it cannot be a domain already claimed by a SAML SSO connector. If saving is rejected for a duplicate domain, look at your SSO connectors too, not just the AD ones.
5. Appliance - Press Test TLS Connection
This checks the hostname, the port, and whether your Verify Server Cert choice will actually work. Do not skip it - it is the difference between finding a problem now and finding it when a user cannot log in.
A failure here is a network or certificate problem, never a credentials problem: no user account is involved in this test.
6. Appliance - Save the connector
Save, and confirm it appears in the list on the Active Directory page and is not marked disabled.
7. Appliance + AD - Map your AD groups to appliance groups
Only needed if you turned on Enable Group Sync. Nothing maps itself - you have to name the AD group on the appliance side.
Go to User and Groups, open (or create) the appliance group that should hold these users, and set its Active Directory Name field to the AD group's name. At login the appliance reads the user's AD groups and adds them to every appliance group whose Active Directory Name matches.
Removal works the same way in reverse: clear the Active Directory Name, remove the user from the AD group, or delete the AD group, and the user drops out of the appliance group at their next login.
Assign permissions to the group, not to the individual user. Anything granted directly to an AD user is lost if that user ever has to be removed and re-created - and with group sync that happens more often than you would expect.
⚠ Group changes only take effect at the next login
Changing AD group membership does not reach into a session that is already running. The user has to sign in again. There is no per-user "end this session" control - the only ways to force it are removing the user or restarting the appliance, and a restart affects everyone who is connected.
Leaving Active Directory Name empty is a deliberate feature. A user added to a group that has no AD name mapping stays in it regardless of AD, which is how you make local exceptions. You then have to remove them by hand when their access should end. This behaviour arrived in v5.5.2.
8. Appliance - Log in as a real AD user to test
Sign in with the username plus the full domain, in email format:
| Login format - Web UI |
|---|
jsmith@corp.example.com |
There is no separate button for AD the way there is for SAML SSO - it goes in the normal username box. The username is case-insensitive and gets stored in lowercase.
⚠ A local user with the same name blocks the AD user
If a Local account already exists with that login name, the AD credentials are refused until the local account is deleted. This bites during migrations, when the local accounts were created first.
9. Appliance - Confirm what the login actually produced
After that first successful login, check the user in User and Groups: they should now exist as an Active Directory user and, if group sync is on, already be a member of the mapped groups. Then confirm they see the connections you expect.
The user record is created by the first login - you do not pre-create AD users.
If you have a Manager
Fabric-joined estates have their own rules here, and getting them wrong locks users out of Gateways rather than producing an obvious error.
| Rule | Why it matters |
|---|---|
| Configure the same AD connector on the Manager and on every joined Gateway | This is the standard practice. Do the Manager first |
| An AD user who logs in to the Manager is synchronized down to every joined Gateway | This is how connection permissions on the Gateways get a user to attach to |
| An AD user that a Gateway already knew gets overwritten by the Manager copy once that user signs in to Manager | Permissions assigned directly to the Gateway-side user are lost. Use Manager-managed groups with AD name mappings instead |
| Clear Active Directory Name on groups owned by a joined Gateway | If a Gateway-owned group still maps to an AD group, affected AD users cannot log in to that Gateway at all until the mapping is removed |
| After changing AD membership or a mapping, the user logs in to Manager first | That is what propagates the change. Going straight to a Gateway may be refused |
AD users do not use the MGR\ or XCM\ prefix |
That prefix is for Local users only. AD users always use user@domain |
⚠ Turn AD logins off while you upgrade the fabric to v5.5.4
v5.5.4 begins moving the appliance's underlying storage database. Two consequences, both stated in the v5.5.4 release note:
- Upgrade the Manager first, then every joined Gateway, before making any configuration change - no adding users, groups or connections in between.
- Temporarily disable AD and SSO logins for the duration, and re-enable them only once every appliance in the fabric is running v5.5.4. This is what the connector's Disabled switch is for.
An AD user signing in mid-upgrade is exactly the event that writes user and group records across a fabric whose members are on different storage versions.
If it does not work
| What you see | Where to look |
|---|---|
| Test TLS Connection fails | TCP 636 to that host, then certificate trust. Re-run the step 1 CLI test with true and then false to tell the two apart |
| Login refused with no useful message | Did the user type the full domain after the @? Is a Local account holding that name? Is the connector disabled? |
| "Unauthorized" for some users but not others, on v5.5.0 or v5.5.1 | Nested Group Search with special characters in the user's DN. Upgrade to v5.5.1.2657 or turn the option off |
| Login works, but the user lands in no groups | Enable Group Sync off, or Active Directory Name not set on the appliance group, or spelled differently from the AD group |
| Intermittent login failures that track directory load | Look for could not execute ldap search ... likely being rate limited in the logs. retry 9 means the retry ladder is exhausted, not recovering - the directory is throttling the appliance |
| Correct MFA codes rejected at the same time as AD problems | Clock skew. Fix time sync before investigating anything else |
| A connector will not delete | Connectors with users still assigned to them cannot be deleted. Remove the users first, or just disable the connector |
Doing it from the CLI
Useful for building the same connector on many appliances. Start from the template, edit the JSON, then add it.
| Active Directory connector commands - CLI |
|---|
ctl active-directory template > adconn.json |
The template prints the field names exactly as the appliance expects them - name, hostname, port, domain, verifyServerCert, enableGroupSync, disabled, plus enableNestedGroups. The id field is only used when updating.
✓ A working connector, in one line
LDAPS reachable, one connector per domain, Active Directory Name set on the groups that grant access, permissions attached to those groups, and a real user logged in to prove it.