Directory integration (LDAP)
Tengri can authenticate users against an external directory — an Active Directory domain controller, or any LDAP server — over an encrypted connection. This page covers connecting a directory, matching its accounts to Tengri users, and verifying the result.
Overview
A directory is registered as an identity provider, alongside SAML. The binding is a single record whose configuration is encrypted at rest with the master key.
Two things use that binding:
- Service accounts
-
Before starting an internal subsystem, Tengri checks that the directory account mapped to it is still enabled.
- Ordinary users
-
A login name and password are verified by binding to the directory, and the result is resolved to the Tengri user that account is linked to.
Directory login is link-only. An administrator creates the user and links it to a directory identity in advance. A login whose identity is not already linked is refused: Tengri never creates a user automatically at login, and never derives roles from directory groups.
Directory login is also additive. The local administrator, loopback trust, and the recovery token all keep working, so an unreachable domain controller cannot lock you out of the platform.
|
Tengri accepts one directory binding. Creating a second is refused, and login always resolves against the single enabled binding — there is no way to choose a directory at login time. Several domain controllers are supported as several hosts inside that one binding. |
Before you start
You need:
-
A running Tengri server with a master key configured — the same key that encrypts SAML bindings.
-
A domain controller reachable over LDAPS, normally port 636, or over LDAP with StartTLS.
-
A read-only service account in the directory. Tengri binds as this account to search for users.
-
The CA certificate that signed the domain controller’s certificate, in PEM form.
|
Plain LDAP on port 389 is refused. A simple bind would send the password in the clear, so any binding whose transport is not LDAPS or StartTLS is rejected when it is created — not later, at login. |
|
Without a master key the directory subsystem is silently unavailable: there is nothing to decrypt a binding with, so directory logins fail as ordinary bad credentials. Check the master key first if nothing about the integration appears to work. |
Creating the binding
Bindings are created with SQL, or through the LDAP page in the administration interface. Run the following as an administrator:
CREATE IDP 'corp-ad' PROTOCOL ldaps DISPLAY NAME 'Corp Active Directory'
WITH (
host = 'dc1.corp.example.com,dc2.corp.example.com',
port = 636,
tls = 'ldaps',
ca_cert = '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----',
bind_dn = 'CN=svc-tngri,OU=Service,DC=corp,DC=example,DC=com',
bind_password = '<secret>',
base_dn = 'DC=corp,DC=example,DC=com',
user_filter = '(sAMAccountName={username})',
login_attr = 'sAMAccountName',
group_attr = 'memberOf'
);
Only the host, the search account and its password, and the search base are required. Everything else above is shown at its default value; see Binding options for the full list. Listing several hosts enables round-robin failover between domain controllers.
Checking the binding
The administration interface has a Test connection button that binds as the search account and reports what it found, without saving anything. It is the only such surface — there is no command-line equivalent.
A successful check reports the negotiated transport and the directory’s naming context:
ok
host=dc1.corp.example.com port=636 tls=ldaps
tls_version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384
naming_context=dc=corp,dc=example,dc=com
A failure names one of the codes in Error codes, so the cause can be told apart from a network problem.
|
Editing a binding merges into the stored configuration rather than replacing it, so leaving the bind password blank keeps the secret already on file. The password is masked everywhere the configuration is displayed. |
Linking service accounts
This is the smaller, lower-risk half of the integration, and it is worth doing first.
Tengri's internal service users authenticate over the loopback connection with a one-time password that is never stored. Linking one to the directory does not replace that credential — it adds a lifecycle check: before the subsystem starts, Tengri confirms that the mapped directory account still exists and is not disabled.
The directory account may be named differently from the Tengri user:
prostore user edit --username compaction \
--ldap-idp corp-ad \
--ldap-principal svc-tngri-compaction
You supply the principal — the login name in the directory. Tengri resolves it and stores the directory’s own immutable identifier, which is what lets the link survive a rename.
Deliberately omit the flag that enables directory login here. The link is recorded and the lifecycle check begins, while the one-time password remains the runtime credential.
Disabling that directory account now prevents the subsystem from starting at the next restart, and the refusal is written to the audit trail.
|
The web application and the websocket share one service account, so blocking it stops both. A blocked account stops only its own subsystem; the rest of the server keeps running. |
|
If the directory cannot be reached, the check is inconclusive and startup continues on the host-local credential, with a warning in the log. Only a definitive "this account is disabled" answer blocks a subsystem. A controller outage must not take the platform down. Detection of a disabled account relies on the attribute Active Directory uses for it. Directories that do not publish that attribute give liveness only by whether the entry still exists, and an unreadable value is read as enabled. |
Matching directory principals to users
This step binds a directory principal to a Tengri user. It is explicit by design: Tengri will not assume that the directory account alice.smith is the local user alice.
There are two surfaces, and they differ in whether the link also switches directory login on. That difference is the most common surprise in this feature.
With SQL
-- create a user that authenticates only against the directory
CREATE USER alice IDENTIFIED BY LDAP IDP 'corp-ad' PRINCIPAL 'alice.smith'
DEFAULT WORKER POOL default;
-- or bind an existing user to a directory identity
ALTER USER alice IDENTIFIED BY LDAP IDP 'corp-ad' PRINCIPAL 'alice.smith';
Both resolve the principal against the live directory as the statement runs, store the returned identifier, and switch directory login on immediately — which switches the local password off. Use this when the user should become a directory user from that moment.
Remove the link with:
ALTER USER alice RESET IDENTIFIED BY LDAP;
With the command line
prostore user edit --username alice \
--ldap-idp corp-ad \
--ldap-principal alice.smith
This records the link and resolves the identifier, but leaves directory login off: the user continues to log in exactly as before. It is the right surface for staging a migration, and it is what the service-account check above relies on.
Switch directory login on as a separate, deliberate step:
prostore user edit --username alice --enable-ldap
Reverse it with --disable-ldap, or drop the link entirely with --unlink-ldap.
All prostore user options are listed in Managing users from the command line.
What each state does
One user walked through the whole lifecycle, with the effect after each step:
| After | Local password stored | Directory login | Local password accepted | Directory password accepted |
|---|---|---|---|---|
user created with a local password |
yes |
off |
yes |
no |
principal linked |
yes |
off |
yes |
no |
directory login enabled |
yes |
on |
no |
yes |
link removed |
yes |
off |
yes |
no |
Enabling directory login switches the local password off but keeps it, so removing the link restores the previous password with no forced reset.
|
A user created by |
Rules that apply to both surfaces
- Linking verifies, it never adopts
-
The target user must already exist, except in the
CREATE USERform which makes it. Repeating a link is harmless. If the user is already linked to a different directory identity, the operation fails rather than rebinding. - Enabling requires a link
-
Switching directory login on for a user with no link is refused.
|
Do not link the built-in administrator account. That would make administrative login depend on the domain controller, so an outage or a mistaken link locks you out. Link a dedicated administrator account instead and keep the built-in one as local break-glass, together with its recovery token and loopback trust. |
Logging in
Web interface
The login endpoint tries the local password first and falls back to a directory bind if that fails. There is nothing to configure and no separate directory login form.
PostgreSQL wire protocol
Directory-backed users cannot use SCRAM. SCRAM requires Tengri to hold a password verifier, and the directory never exposes one. These users authenticate with the cleartext password method inside a required TLS tunnel — the same constraint PostgreSQL's own directory authentication carries.
TLS is enforced, not advised: connecting without it fails before any password is sent.
psql "host=tengri.example.com port=5432 user=alice sslmode=require"
The connection binds with the stored principal rather than the name typed at the prompt, and is refused if the identifier the directory returns no longer matches the stored one.
Security controls
These are enforced by the product and are not configurable.
| Control | Behavior |
|---|---|
Transport |
LDAPS or StartTLS only; a plain bind is refused when the binding is created |
Certificate validation |
On by default |
Empty password |
Rejected before binding — an empty password is an anonymous bind, which would otherwise read as success |
Filter injection |
The login name is escaped before it is placed into the search filter |
Referrals |
Referral chasing is disabled and referral results are discarded |
Connection |
Read-only, with a connect and receive timeout |
Brute force |
Directory logins pass through the same lockout and address throttle as local ones, with a random delay on failure |
Binding options
Stored encrypted with the binding. Set with CREATE IDP or ALTER IDP, or on the LDAP administration page.
| Option | Type | Default | Description |
|---|---|---|---|
|
string or list |
required |
One or more controller host names. Several hosts round-robin with failover. |
|
int |
|
Directory port. |
|
|
|
Transport security. Anything else is rejected. |
|
PEM |
empty |
The CA bundle the controller certificate is validated against. Empty means the system trust store. |
|
bool |
|
Validate the controller certificate. Setting it false removes that protection. |
|
int, seconds |
|
Connect and receive timeout. Must be positive. |
|
string |
required |
Distinguished name of the read-only search account. |
|
string |
required |
Its password. Masked when displayed; omit it when editing to keep the stored value. |
|
string |
required |
Search base for user lookups. |
|
string |
|
Search filter. Must contain |
|
string |
|
Attribute holding the login name. |
|
string |
|
Immutable identifier stored as the link key. Changing it gives up rename-safety. |
|
string |
|
Display name attribute. |
|
string |
|
Email attribute. |
|
string |
|
Attribute read for group membership. Recorded, but not used for authorization. |
On Active Directory the defaults are correct. On OpenLDAP, set the filter to (uid={username}), the login attribute to uid, the identifier attribute to entryUUID, and the display name attribute to cn.
|
The stored identifier is normalised: a 16-byte Active Directory identifier becomes an ordinary UUID string, anything else is encoded. Repointing the identifier attribute after users are linked invalidates every stored link. |
Binding lifecycle
| Operation | Effect on linked users |
|---|---|
Rename the binding |
The reference is rewritten on every linked user. |
Disable the binding |
Directory logins stop resolving; links are left intact. |
Drop the binding |
Refused while any user is linked. |
Drop the binding with |
Clears the directory link on every linked user. |
Error codes
The verifier reports a stable code, shown by the connection test and in the server log.
| Code | Meaning |
|---|---|
|
The options are rejected before any network call — most often plain LDAP, or a filter without the login placeholder. |
|
The directory could not be reached: wrong host or port, a firewall, or a failed TLS handshake. |
|
The search account could not bind — wrong distinguished name or password. |
|
The user’s password was refused by the directory. |
|
An empty password was supplied; refused before binding. |
|
No entry matched the search filter. |
|
Directory login was enabled for a user with no link. |
|
No master key, so no binding can be decrypted. |
Troubleshooting
- Plain LDAP is refused
-
The binding’s transport is missing or set to something other than LDAPS or StartTLS.
- A certificate error in the log
-
The controller’s certificate does not chain to the CA bundle you supplied. Correct the bundle. Turning validation off will confirm the diagnosis but leaves the connection open to interception — it is not a resting state.
--ldap-idp and --ldap-principal must be given together-
Both are needed; the principal is resolved against the named binding.
cannot enable LDAP auth-
Directory login was enabled for a user with no link. Link it first.
- A conflict when linking
-
The user is already bound to a different directory identity. Remove the existing link first if the rebind is intended.
auth unavailable-
The user has no enabled authentication method — usually a directory-created user that was unlinked. Set a local password for it.
An IdP with protocol 'ldaps' already exists-
Only one directory binding is supported. Alter the existing one instead of creating a second.
has N user(s) assigned; use CASCADE to also revoke-
Dropping a binding that users are linked to requires
CASCADE, which also clears those users' links. - A subsystem did not start
-
The directory account mapped to its service user is disabled or gone. Re-enable it in the directory, or remove the link.