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 CREATE USER …​ IDENTIFIED BY LDAP never had a local password. Removing its link leaves it with no usable authentication method at all, and logins fail with auth unavailable. Give such a user a password before unlinking it.

Rules that apply to both surfaces

Linking verifies, it never adopts

The target user must already exist, except in the CREATE USER form 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.

Scheduled jobs

Scheduled work re-checks its owner before running, so a schedule owned by someone since disabled in the directory fails instead of running. The same check also refuses an owner deactivated locally.

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

host

string or list

required

One or more controller host names. Several hosts round-robin with failover.

port

int

636

Directory port.

tls

ldaps | starttls

ldaps

Transport security. Anything else is rejected.

ca_cert

PEM

empty

The CA bundle the controller certificate is validated against. Empty means the system trust store.

require_cert

bool

true

Validate the controller certificate. Setting it false removes that protection.

timeout

int, seconds

10

Connect and receive timeout. Must be positive.

bind_dn

string

required

Distinguished name of the read-only search account.

bind_password

string

required

Its password. Masked when displayed; omit it when editing to keep the stored value.

base_dn

string

required

Search base for user lookups.

user_filter

string

(sAMAccountName={username})

Search filter. Must contain {username}, which is escaped before substitution.

login_attr

string

sAMAccountName

Attribute holding the login name.

uid_attr

string

objectGUID

Immutable identifier stored as the link key. Changing it gives up rename-safety.

display_name_attr

string

displayName

Display name attribute.

email_attr

string

mail

Email attribute.

group_attr

string

memberOf

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 CASCADE

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

config_invalid

The options are rejected before any network call — most often plain LDAP, or a filter without the login placeholder.

connect_failed

The directory could not be reached: wrong host or port, a firewall, or a failed TLS handshake.

bind_failed

The search account could not bind — wrong distinguished name or password.

invalid_credentials

The user’s password was refused by the directory.

empty_password

An empty password was supplied; refused before binding.

user_not_found

No entry matched the search filter.

link_target_missing

Directory login was enabled for a user with no link.

master_key_missing

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.