LDAP directories

Taranac can connect to one or more directories — Active Directory, OpenLDAP, FreeIPA, Google Workspace Secure LDAP or any other LDAP server — and use them as a source of truth for identities. A directory connection does two things: it synchronises users, groups and (on Active Directory) computer objects into Taranac, and it acts as an authentication backend so directory accounts can sign in by binding against the server. Synced groups become first-class Taranac groups, so directory membership flows straight into RBAC, AAA and NAC policy.

You configure directories under Settings → LDAP. Most deployments need only one connection; several are only required for genuinely separate directories — as here, where one installation holds an Active Directory domain, an OpenLDAP server and a FreeIPA realm side by side.

The LDAP settings page: each card is one directory connection, tagged with its type, with inline Test, Edit and Delete actions.

A connection has a type, chosen as the first step of creating it. The answer is not cosmetic: an integration built only for Active Directory binds by UPN, looks accounts up by sAMAccountName, tracks them by objectGUID and filters on userAccountControl — every one of which is false for OpenLDAP and FreeIPA. The type decides both what the directory can do and what the form is prefilled with.

The type picker, the first step of Add Configuration. Each card states up front whether the directory can serve MS-CHAPv2 — worth knowing before the configuration exists, not after the first 802.1X login fails.

Type	MS-CHAPv2 / PEAP	Computer sync	domain_suffix	netbios_name	Schema defaults
Microsoft Active Directory	✅	✅	required	required	sAMAccountName, objectClass=user / group
OpenLDAP	❌	❌	optional	—	RFC 2307: uid, posixAccount, groupOfNames
FreeIPA	❌	❌	optional	—	RFC 2307 (same as OpenLDAP)
Google Workspace	❌	❌	optional	—	RFC 2307
Other LDAP directory	❌	❌	optional	—	RFC 2307

The two columns are different in kind, and the difference matters:

• Capabilities — facts about the protocol you cannot override. MS-CHAPv2 needs an NT hash and only a domain controller hands one out; a directory whose schema has no computer objects has nothing to enrich a NAC endpoint with. The UI hides the Computers and MS-CHAPv2 tabs for types that lack them, and the API refuses the calls independently (ldap.computer_sync_not_supported, domain.mschapv2_requires_active_directory) — a hidden tab is a courtesy, not the control.
• Defaults — guesses about a schema you can always override. Filters, attribute maps and the example values under each field are prefilled per type; being slightly wrong about your tree costs you one edit.

Upgrading an existing installation changes nothing: a configuration saved before directory types existed reads as Active Directory, and the Active Directory defaults are the values that always shipped.

Every synced user and group is tracked by an immutable identifier rather than by name or DN, so renaming or moving an object updates the existing Taranac record instead of creating a duplicate. Which attribute that is depends on the directory: objectGUID on Active Directory, entryUUID (RFC 4530) on OpenLDAP and FreeIPA.

Active Directory accepts user@domain and resolves it internally, so Taranac binds directly as the user. Everything else takes a distinguished name and answers a bare login with invalidDNSyntax — so for those types Taranac first resolves the DN with the service account, using the configuration’s own user_search_filter and user_search_bases, then binds as that DN.

That has a useful side effect: on OpenLDAP and FreeIPA, sign-in is scoped to the search bases you configured, which the direct UPN bind on Active Directory cannot be. If a login matches more than one entry the attempt is refused rather than guessed at, and an empty password is rejected outright (an empty simple bind is an anonymous bind, which most directories accept).

A standard RFC 2307 / inetOrgPerson tree: the login attribute is uid, groups are groupOfNames, and membership is a DN in member. The bind account is a full DN (cn=svc-taranac,ou=Services,…) — there is no UPN to type.

An OpenLDAP connection. The type is shown next to the config ID and cannot be changed; the search filters are prefilled for the RFC 2307 schema, and the tab row has no Computers or MS-CHAPv2 — OpenLDAP has neither.

Defaults prefilled for this type:

Field	Default
user_search_filter	(&(objectClass=posixAccount)(uid={username}))
group_search_filter	(objectClass=groupOfNames)
sync_user_filter	(objectClass=posixAccount)
sync_group_filter	(objectClass=groupOfNames)
user attributes	uid, mail, givenName, sn, displayName, telephoneNumber
group attributes	cn, description, members from member (DN values)

The same defaults serve Google Workspace Secure LDAP and the generic type. Google additionally requires a client certificate on the connection.

FreeIPA (Red Hat’s identity manager, backed by 389 Directory Server) publishes the same schema shape as OpenLDAP — uid + posixAccount + inetOrgPerson for users, groupOfNames + posixGroup for groups — so its filters are identical. What differs is the layout: accounts do not live in an OU but under cn=users,cn=accounts,$SUFFIX, with groups under cn=groups,cn=accounts,$SUFFIX. That is what you actually type, which is why FreeIPA is its own type: the example values in every field follow the IPA tree.

A FreeIPA connection. Same filters as OpenLDAP, different containers: the bind account is uid=svc-taranac,cn=users,cn=accounts,… and the search bases sit under cn=accounts.

FreeIPA installs its own CA, independent of anything Active Directory signs. Each connection carries its own trust anchor, so an installation can hold directories with two different CAs at once — paste each server’s CA into tls_ca_cert on its own connection.

• Connection (config). One directory you connect to, identified by a short, immutable config_id. It holds the type, the servers, the bind account, search bases and filters, and all sync options.
• Bind account. A service account Taranac uses to read the directory during sync and browsing (and, on non-AD types, to resolve a user’s DN at sign-in). Its credentials (bind_dn + bind_password) are stored encrypted.
• Search base / filter. The subtree and LDAP filter that scope what sync and the directory browser see. Scoping here is how you decide which accounts and groups become Taranac objects.
• auth_source. Synced users carry auth_source = ldap. They have no local password in Taranac; they authenticate against the directory. Locally created accounts are auth_source = local.
• Domain suffix / NetBIOS name / priority. Identifiers used to route a login to the right connection: domain_suffix (e.g. corp.example.com) matches user@corp.example.com logins, netbios_name matches CORP\user (Active Directory only), and priority orders connections when the login is a bare username.

Open Settings → LDAP → Add Configuration, pick the directory type, then fill in the connection form. The essential fields:

Field	Purpose
config_id	Short slug (lowercase, digits, -/_). Immutable once created.
display_name	Friendly name shown in the UI.
servers	One or more LDAP URIs, space- or newline-separated (e.g. ldaps://dc1.corp.example.com).
bind_dn / bind_password	Service-account credentials for read access — a UPN on Active Directory, a full DN elsewhere. Password is stored encrypted.
domain_suffix	Required on Active Directory, optional elsewhere: routes user@domain logins to this connection.
netbios_name	Short domain name (1–15 chars), e.g. CORP. Active Directory only; routes DOMAIN\user logins.
priority	1–999. Lower numbers are tried first for bare-username logins.
use_start_tls / tls_validate / tls_ca_cert	Transport security: StartTLS, certificate validation, and the CA certificate (PEM, pasted into the form) that signs the directory server’s certificate.
connection_timeout	Per-server connect timeout in seconds.

When the connection details are saved, use the operations bar at the top of the Users & Groups tab:

• Test Connection reports per-server reachability and latency, whether the bind succeeded, and a count for each search base — run this first. It names the stage that failed, so a name that does not resolve is reported as such rather than as a certificate problem.
• Sync Preview performs a dry run and shows exactly what would be created, updated, disabled or deleted, plus any conflicts. Nothing is written.
• Trigger Sync runs the sync for real.

Scope is everything. The connection has separate search bases and filters for users and groups, and separate sync filters applied during a sync run. Restrict the search bases to the subtrees you actually want in Taranac — point user search at an “Employees” OU (or cn=users,cn=accounts on FreeIPA) so service and disabled accounts never sync.

Browse opens the directory tree so you can pick bases instead of typing them. The browser understands non-AD schemas — groupOfNames, groupOfUniqueNames, posixGroup, ipausergroup for groups, inetOrgPerson / posixAccount for users, and the container objects FreeIPA nests its accounts in.

Sync runs in one of two modes:

Mode	Behaviour
groups_with_users	Walk the configured groups, resolve their members, and create/update those users. Use this when group membership defines who belongs.
users_only	Create/update users directly from the user search base, independent of group membership.

The lifecycle for each object is create → update → deactivate → delete, governed by these options:

Option	Effect
sync_create_users	Create a Taranac account for each directory user found. When off, sync only updates accounts that already exist.
sync_disable_missing	Set users no longer present in the directory to inactive (is_active = false) instead of leaving them enabled.
sync_remove_stale_users	Permanently delete users that have disappeared from the directory.
sync_remove_stale_groups	Permanently delete groups that have disappeared from the directory.
sync_enabled / sync_interval_minutes	Run the sync automatically on a schedule (a background worker).

Synced users are created with auth_source = ldap and no local password — authentication is delegated to the directory. Their group membership in Taranac mirrors the directory, and every action (created/updated/deactivated/deleted, per user and per group) is written to the audit log.

Because synced groups are ordinary Taranac groups, they work everywhere groups work:

• Admin RBAC. Assign an RBAC model to synced users via default_rbac_model_id (applied to all users of the connection) or group_rbac_mapping, which maps a specific directory group DN to a specific RBAC model. A group match takes precedence over the default.
• AAA policy. Reference directory groups as conditions in TACACS+/RADIUS policy to grant device-admin privilege levels, command sets or RADIUS attributes by group — see AAA policy.
• NAC policy. Use the same groups as conditions in 802.1X/MAB authorization to assign VLANs, ACLs or captive-portal flows — see NAC authentication.

This is the main reason to sync groups even when you do not need local admin accounts: it lets policy decisions key off directory membership without re-modelling your org chart inside Taranac.

Active Directory only — the tab does not appear on other types, which have no computer objects to import.

The Computers tab syncs AD computer objects into NAC endpoints, enriching them with hostname, OS and OU metadata. Configure computer_search_bases, computer_search_filter, the attribute holding the MAC (computer_mac_attr) and an attribute map, then preview and run it like user sync.

• Computers that have a MAC attribute become NAC endpoints directly (match source mac_address).
• Computers without a MAC are held as pending computers (shown in a table on the tab). When that machine later authenticates by certificate (EAP-TLS), Taranac matches it by DNS hostname and binds the AD data to the resulting endpoint (match source dns_hostname).

The connection also stores the EAP-TLS settings used to validate machine and user certificates for that directory (CA certificate, identity matching, CRL/OCSP revocation checks) on the EAP-TLS tab — that tab is available for every type. See NAC PKI / EAP-TLS for the certificate side.

A directory connection can authenticate sign-ins — the web admin UI, and TACACS+ / RADIUS / 802.1X through the daemons. The flow for admin login:

1. Taranac looks up the username among local users first.
2. On a miss, it falls back to multi-domain LDAP discovery: it picks the matching connection(s) and tries to authenticate. (For AAA and NAC the connection is not discovered — it is the one the synced user record already belongs to.)
3. The password is verified by binding as the user: directly as user@domain on Active Directory, or as the DN resolved by the service account on every other type.

ldap · login routing

login typed matched by connection

user@corp.example.com domain_suffix → CORP

CORP\user netbios_name → CORP

user priority order → CORP prio 1 BRANCH prio 2

active directory bind as user@domain no lookup needed

openldap · freeipa find DN, bind as DN scoped to search bases

Login routing depends on the format the user types:

Login format	Routed to
user@corp.example.com (UPN)	The connection whose domain_suffix matches the domain.
CORP\user (NetBIOS)	The connection whose netbios_name matches — Active Directory only.
user (bare)	All enabled connections, tried in priority order.

On Active Directory, a bare or unqualified username is qualified to username@<domain_suffix> before binding (falling back to the domain parsed from a UPN-style bind_dn if no suffix is set).

Usernames are matched case-insensitively, mirroring how AD treats sAMAccountName/UPN binds — so CORP\jsmith and CORP\JSmith resolve to the same account. The original casing from the directory is preserved for display.

Directory users cannot change or reset their Taranac password — those operations are local-only and return an error for auth_source = ldap accounts. Password changes happen in the directory. (MFA enrollment, however, still applies to directory users; newly synced users can be auto-sent a setup link.)

Password verification by bind covers everything that hands Taranac the password itself. MS-CHAPv2 does not: it proves knowledge of an NT hash, which only a domain controller will compare.

Method	Active Directory	OpenLDAP / FreeIPA / other
TACACS+ ASCII login	✅	✅
RADIUS PAP	✅	✅
802.1X — EAP-TTLS/PAP	✅	✅
802.1X — EAP-TLS	✅	✅ (no password involved)
802.1X — PEAP-MSCHAPv2	✅ (requires the node to be domain-joined)	❌
RADIUS MS-CHAPv2 (e.g. MikroTik admin login)	✅ (requires the node to be domain-joined)	❌

A PEAP attempt against a directory that cannot serve MS-CHAPv2 is refused by name rather than as a wrong password, and the refusal is not counted as a credential attempt — a rebooting domain controller does not look like password guessing. For those directories use EAP-TTLS/PAP or EAP-TLS for 802.1X; see EAP-TTLS with a directory.

Use…	When
A directory	You already run AD, OpenLDAP or FreeIPA and want a single source of truth; you want device-admin and NAC policy to follow directory group membership; you want joiners/leavers handled by directory lifecycle, not by hand.
Local users	Break-glass and bootstrap accounts (so you can still log in if the directory is unreachable); service or automation identities that should not live in the directory; small deployments with no directory at all.

A common pattern: keep one or two local break-glass admins, drive everyone else from the directory, and map directory groups to RBAC models and policy conditions. See Users & groups and RBAC.

• Device-admin by directory group. Sync the “Network Admins” group, map its DN to an RBAC model and reference it in TACACS+ policy to grant privilege 15 and a command set. Removing a person from the group removes their access at the next sync.
• 802.1X with machine certificates. Run computer sync to seed endpoints and pending computers, enable EAP-TLS on the connection with your CA certificate, and authorize by AD computer group in NAC authentication.
• 802.1X against a Linux directory. Point the connection at OpenLDAP or FreeIPA, sync the groups you authorize on, and run EAP-TTLS/PAP (or EAP-TLS) — no domain, no NT hashes, no Samba.
• Mixed estate. Add one connection per directory — an AD domain, an OpenLDAP server and a FreeIPA realm can coexist, each with its own type, trust anchor and search bases. priority orders bare-username logins across them.

Deleting a connection offers three cascade choices for the accounts it created:

Option	Result
Refuse if users exist	Deletion is blocked while synced users remain.
Disable users	Synced users are deactivated but kept.
Delete users and groups	Synced users and groups are removed.

• Users & groups
• RBAC
• MFA
• AAA policy
• EAP-TTLS with a directory
• NAC authentication · NAC PKI / EAP-TLS
• Taranac on GitHub