LDAP Channel
- Connect
Point the client at a configured LDAP listener.
- Sign in
Use a supported bind method.
- Search
Verify a search against the expected entries.
You can configure a listener and test an existing client before switching its traffic.
Next: Authentication
Point your existing LDAP apps at Scribe. They’ll keep working — same protocol, same tools, same queries — but now they’re reading from PostgreSQL instead of hitting your directory server directly.
Quick start
Section titled “Quick start”Configure one or more listeners:
channels.ldap { listen = [ { port = 10389 } # Plain LDAP { port = 10636, ssl { # LDAPS ca = "certs/ca.pem" cert = "certs/server.pem" key = "certs/server-key.pem" }} ]}Test with any LDAP client:
ldapsearch -H ldap://localhost:10389 -x -D "u:alice" -W \ -b "ou=users,dc=example,dc=com" "(cn=john*)" cn mailFor all listener settings (host binding, client certificates, socket options, connection limits), see Configuration Reference.
Authentication
Section titled “Authentication”Scribe authenticates LDAP bind requests locally using the unified auth infrastructure. Several bind DN formats are supported:
| Bind DN format | Example | How it works |
|---|---|---|
bearer:<token> | bearer:eyJhbGci... | JWT or opaque token — password is ignored |
dn:<dn> | dn:uid=alice,ou=users,dc=example,dc=com | Backend DN + password. Backend DNs must be under auth.ldap.base; a matching configured local DN is handled locally |
u:<username> | u:alice | Username + password, resolved through LDAP or a configured local alias |
| Plain value | alice or uid=alice,... | DN-like strings bind as a configured local account or backend DN (backend DNs are subject to base enforcement); other values resolve as usernames |
Every sign-in names a directory account: a dn: value that is not a DN, or a bearer token or username that maps to no DN, fails with INVALID_CREDENTIALS. Bearer and username binds find the DN through auth.ldap.
# Bind with bearer tokenldapsearch -H ldap://localhost:10389 -x \ -D "bearer:eyJhbGciOiJSUzI1NiJ9..." -w "ignored" \ -b "ou=users,dc=example,dc=com" "(cn=*)"
# Bind with usernameldapsearch -H ldap://localhost:10389 -x \ -D "u:alice" -W \ -b "ou=users,dc=example,dc=com" "(cn=*)"Local technical accounts
Section titled “Local technical accounts”Use local for a configured technical account that must authenticate repeatedly without a backend bind or username lookup:
auth { enabled = true methods = [local] local.accounts = [{ bind-dn = "cn=scribe,dc=example,dc=com" bind-password = ${SCRIBE_LOCAL_PASSWORD} username = "scribe" # optional; enables u:scribe and plain scribe delegation.enabled = false proxy-authorization.enabled = false # default; true lets the account act for other identities }]}The local DN is the canonical authenticated identity and does not need to be a directory entry. A successful local bind does not contact backend LDAP. LDAP Who-Am-I reports dn:<canonical local DN>. Reads of that DN remain ordinary directory operations: Scribe does not create a synthetic entry or merge profile attributes. A matching local account with a wrong password is rejected without falling through to another authentication method. Unknown names may use another explicitly configured method.
delegation.enabled defaults to true. The backend account is the account’s complete delegation.bind-dn and delegation.bind-password pair; when omitted, Scribe uses the root ldap.bind-dn and ldap.bind-password pair. With delegation disabled, the rejection is UNWILLING_TO_PERFORM. Scribe access rules still apply to local callers, and local authentication does not grant roles or administrative access.
Authentication methods are tried in configured order for unknown credentials (for example, local, bearer, ropc, or ldap). A matching local account owns the Basic credential decision before fallback methods; local must be first in every mixed list. Both channels.ldap.auth and channels.identity-hub.auth inherit from global auth {} and can override enabled, methods, and rules per channel. See Authentication for method configuration.
If a service account binds with the ldap method, that account must pass auth.ldap.filter before channel access rules run. Use auth.ldap.filter to decide who may authenticate, then use channels.ldap.auth.rules, monitoring.observe.auth.rules, and auth.ldap.roles for LDAP-channel and operator UI authorization.
SASL binds
Section titled “SASL binds”SASL binds are off by default. List the mechanisms a listener forwards to the directory:
channels.ldap.sasl.mechanisms = [PLAIN]Names are compared regardless of letter case; each has up to 20 letters, digits, hyphens or underscores. A SASL bind with any other mechanism receives AUTH_METHOD_NOT_SUPPORTED before Scribe contacts the directory. The Identity Hub listener uses its own channels.identity-hub.sasl.mechanisms; when that is not set, it takes a root ldap.sasl.mechanisms, as it does for proxy-authorization.allowed.
EXTERNAL cannot be enabled; listing it stops startup. The directory would see Scribe’s connection, not the client’s, and authenticate Scribe’s own certificate instead of the client.
The directory checks the credentials of an enabled SASL bind. SASL ignores the name in the bind request, and so does Scribe. Once the bind succeeds, Scribe asks the directory on the same connection which account it signed in, with the Who-Am-I operation (RFC 4532). A u:<username> answer counts only when the username resolves under auth.ldap.base, as it does in a ProxyAuth control. Channel access rules, Proxy Authorization, and the identity Scribe names to the directory all use that account.
With channel authentication enabled, an enabled mechanism counts as the ldap method, exactly like a simple bind:
- the listener’s
auth.methodsmust includeldap; - the account must lie under
auth.ldap.baseand matchauth.ldap.filter; - an account whose DN is a local account’s
bind-dnsigns in only with the local password, so SASL cannot sign it in; - its roles come from
auth.ldap.roles; - while directory sign-ins fail fast during an outage, a new SASL bind fails with
UNAVAILABLEwithout being forwarded. When it is the one sign-in let through to check whether the directory answers again, Scribe checks the directory itself first and forwards the bind only if it answers. The later steps of a multi-step bind are forwarded as they arrive. A SASL bind that cannot reach the directory counts toward detecting an outage, as a failed sign-in check does: once enough have failed in a row, Scribe checks the directory configured for LDAP sign-in itself, and sign-ins fail fast only when that check fails too. Both listeners share this outage detection. SASL binds that fail only on the Identity Hub listener’s own servers therefore never make sign-ins fail fast.
If the directory does not support Who-Am-I, reports no account, or reports one that these checks refuse, the bind fails with INVALID_CREDENTIALS and Scribe closes the directory connection the bind authenticated. With channels.ldap.auth.enabled = false, the listed mechanisms and the EXTERNAL rule still apply, and the account the directory reports is used as it is, just as a simple bind’s DN is: neither auth.ldap nor the listener’s access rules apply.
Proxy Authorization
Section titled “Proxy Authorization”A bound client can run a request as another identity with the Proxy Authorization control (RFC 4370; the older V1 control is accepted too). Scribe checks that the client may act for that identity before it looks the identity up or contacts the backend:
ldapsearch -e '!authzid=dn:uid=alice,ou=users,dc=example,dc=com' \
-H ldap://localhost:10389 -x \
-D "cn=portal,ou=services,dc=example,dc=com" -W \
-b "ou=users,dc=example,dc=com" "(cn=*)"ProxyAuth accepts the same formats as bind: bearer:<token>, dn:<dn>, u:<username>, or plain values. Who may use which format:
| Bound as | bearer:<token> | dn:, u: or plain value |
|---|---|---|
LDAP or bearer bind listed in proxy-authorization.allowed | Allowed | Allowed |
| Any other LDAP or bearer bind | Allowed | AUTHORIZATION_DENIED |
Local account with proxy-authorization.enabled = true | Allowed | Allowed |
| Local account without it (default) | AUTHORIZATION_DENIED | AUTHORIZATION_DENIED |
| Anonymous | AUTHORIZATION_DENIED | AUTHORIZATION_DENIED |
A bearer token proves its subject, so any bound client may present one, on a listener whose auth.methods include bearer; elsewhere it returns AUTHORIZATION_DENIED, as a bearer bind does. A DN or username proves nothing, so only identities you list may name one. The list is empty by default:
channels.ldap.proxy-authorization.allowed = [ "cn=portal,ou=services,dc=example,dc=com"]Entries are compared as DNs, so letter case and spacing do not matter. List the DN the client binds as; for a bearer bind, that is the DN its token maps to. The Identity Hub listener uses its own channels.identity-hub.proxy-authorization.allowed. A local account opts in with proxy-authorization.enabled = true in its auth.local.accounts entry.
The requested identity is validated like a bind. DN and username formats (including plain values) require auth.ldap configuration so Scribe can verify DNs and resolve usernames; without it, ProxyAuth with those formats returns AUTHORIZATION_DENIED. The DN must lie under auth.ldap.base, and so must the dn claim of a bearer token. Exceptions: with the ldap listener disabled, the Identity Hub listener takes a bearer token’s subject as its DN without that check, and so does every listener without auth.ldap.base. A bearer token must name a directory account: one that maps to no DN, such as a client-credentials token without a subject, returns AUTHORIZATION_DENIED.
Channel access rules (channels.ldap.auth.rules) apply to the signed-in account. The backend account is Scribe’s configured backend account, or a local account’s delegation account, so it needs the backend directory’s permission to act for these identities. For a local account, the backend connection adds ProxyAuth only for an identity the account named with its permission. When Scribe forwards the bind itself, with a SASL bind or with channels.ldap.auth.enabled = false, the backend connection is authenticated as the client, and the backend also checks the client’s own permission. If that directory connection is lost, Scribe does not continue the session with its own backend account: later requests that need this directory connection return UNAVAILABLE until the client binds again. After a SASL bind, the DN compared with the list is the account the directory reports through Who-Am-I (see SASL binds).
The control must be critical, may appear only once, and must use its exact control type; a non-critical, repeated, or malformed control, or a misspelled control type such as one with leading zeros, returns PROTOCOL_ERROR. A bind or StartTLS request with a ProxyAuth control returns UNAVAILABLE_CRITICAL_EXTENSION, or PROTOCOL_ERROR for a control that breaks these rules, before Scribe checks any credentials or contacts the directory; an abandon request with one is ignored. On StartTLS, a local account without the permission gets AUTHORIZATION_DENIED instead, as on every other operation. Who-Am-I reports the proxied identity. A paging cookie or VLV context belongs to the identity it was issued to: continuing a paged or VLV search as a different identity returns UNWILLING_TO_PERFORM, so restart the search instead.
Searching
Section titled “Searching”Standard LDAP search with filters, scopes, and attribute selection:
# Subtree search with filter and specific attributesldapsearch -H ldap://localhost:10389 -x -D "..." -W \ -b "ou=users,dc=example,dc=com" \ -s sub "(|(cn=john*)(mail=*@example.com))" cn mail uidPagination
Section titled “Pagination”Use Simple Paged Results for large result sets:
ldapsearch -H ldap://localhost:10389 -x -D "..." -W \
-b "ou=users,dc=example,dc=com" \
-E pr=100/noprompt "(objectClass=inetOrgPerson)"VLV (Virtual List View) is also supported.
LDAP paging response controls use channels.ldap.default-count, which inherits query.default-count unless overridden.
The default is exact so clients can use the response size as a membership count. eDirectory clients that do not need a
count can send the disable-count control to skip count work for that request.
Sorting
Section titled “Sorting”Server-Side Sorting works on indexed attributes:
ldapsearch -H ldap://localhost:10389 -x -D "..." -W \ -b "ou=users,dc=example,dc=com" \ -E sss=-sn "(objectClass=inetOrgPerson)"Auth gating by operation type
Section titled “Auth gating by operation type”Access rules are evaluated for all operation types. The exact checks differ:
| Operation type | Auth gating |
|---|---|
| Search | (1) Auth required flag (if configured), (2) access rules, (3) ProxyAuth control validation |
| Add, Compare, Delete, Modify, ModifyDN | (1) Access rules, (2) ProxyAuth control validation |
| Extended | Before bind, StartTLS is forwarded (RFC 4513 pre-bind transport); a ProxyAuth control on StartTLS is rejected. Other extended operations: access rules and ProxyAuth control validation; after a local bind, local forwarding policy |
Search has the strictest gating: when channels.ldap.auth.enabled is true, unauthenticated Search requests are rejected before access rules are evaluated. Non-Search operations (add, modify, etc.) rely on access rules and, when present, the ProxyAuth check. Extended operations: StartTLS is forwarded to the backend before authentication (RFC 4513 requires pre-bind transport negotiation). Once a local account is bound, local forwarding policy and ProxyAuth validation also apply; disallowed requests are rejected before backend access.
Bind failure delay: failed bind attempts use auth.failure-delay (default 2s) before responding, including local wrong, empty, unknown, and malformed credentials. It does not apply when authentication itself is delegated to the backend.
Size limits: a password or SASL credential larger than 64 KiB, a bind DN or username larger than 8 KiB, or bind request controls larger than 8 KiB in total get INVALID_CREDENTIALS before Scribe contacts the directory, with or without channel authentication. Kerberos tokens fit within these limits, and a bearer: token may be up to 64 KiB. A listener disconnects a client that sends a request larger than max-message-size-bytes, 10 MiB by default. Raise it, or set 0 to remove the limit, only if your clients write larger entries through Scribe and the directory accepts them.
Modify forwarding
Section titled “Modify forwarding”Modify operations (including multi-attribute batch modifications from clients such as Apache Directory Studio) are forwarded to the upstream directory as a single atomic operation exactly as received — the modification list is never inspected, split, reordered, or deduplicated by Scribe. Atomicity and schema enforcement are governed by the upstream directory. If a Modify would leave the entry schema-invalid, the upstream returns an error result code (see Common issues below) and Scribe relays it unchanged.
Search delegation
Section titled “Search delegation”Some requests can’t be answered from the local cache — schema queries, unsupported filters, directory browser operations. When that happens, Scribe forwards the request to the upstream LDAP server.
Set channels.ldap.prevent-delegation = true to fail these requests instead of forwarding them. A local account with delegation.enabled = false applies the same rejection to that account even when channel-wide delegation is allowed. See Configuration Reference for delegation reasons and telemetry.
Common issues
Section titled “Common issues”| Symptom | Check |
|---|---|
Can't contact LDAP server | Listener configured? Port not blocked? |
| ResultCode 49 (INVALID_CREDENTIALS) | Bind DN and password correct? For bearer tokens: token valid and not expired? For SASL: does the directory answer Who-Am-I, and does the account it reports lie under auth.ldap.base and match auth.ldap.filter? Passwords and SASL credentials over 64 KiB, and bind names or bind controls over 8 KiB, are always refused |
| ResultCode 52 (UNAVAILABLE) | A forwarded request could not open a directory connection, or a service needed for sign-in is temporarily unavailable. Check directory reachability and the service logs, then retry. After a SASL bind, or any bind with channels.ldap.auth.enabled = false, a lost directory connection stays unavailable until the client binds again or reconnects. |
| Connection closed while sending a large request | The request is larger than max-message-size-bytes (10 MiB by default); raise it if the directory accepts such requests |
| ResultCode 7 (AUTH_METHOD_NOT_SUPPORTED) | A SASL bind whose mechanism is not listed in channels.ldap.sasl.mechanisms |
| ResultCode 123 (AUTHORIZATION_DENIED) | ProxyAuth that names a DN or username from a bind DN not in proxy-authorization.allowed, from a local account without proxy-authorization.enabled, or without auth.ldap configured; an empty or invalid bearer token, one that maps to no directory account, or one sent to a listener without the bearer method |
| ResultCode 2 (PROTOCOL_ERROR) | ProxyAuth control sent non-critical, more than once, with a malformed value, or with a misspelled control type, on any request, a bind or StartTLS included. A local account without proxy-authorization.enabled gets 123 instead for a ProxyAuth control with a correctly spelled control type, on every operation except a bind |
| ResultCode 12 (UNAVAILABLE_CRITICAL_EXTENSION) | A valid ProxyAuth control on a bind or StartTLS request (one that is non-critical, repeated or malformed gets 2); send it on the operations that should run as the other identity instead |
| ResultCode 53 (UNWILLING_TO_PERFORM) | A paging cookie or VLV context continued as a different ProxyAuth identity, or after a rebind or a completed SASL bind; restart the search |
| ResultCode 4 (SIZE_LIMIT_EXCEEDED) | Use pagination (-E pr=100/noprompt) or refine the filter |
| ResultCode 65 (OBJECT_CLASS_VIOLATION) | Returned by the upstream when a Modify would leave the entry schema-invalid — for example, removing a structural objectClass, or removing an auxiliary class whose MUST attributes are still present. Sequence removals so each intermediate state is schema-valid, or remove dependent attributes first. Scribe relays this result code unchanged. |
See Signals for metrics, Logging and Traces for trace debugging, Error Handling for the complete ResultCode mapping.