> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kvelden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LDAP / Active Directory sign-in

> Let users sign in to the appliance with their existing LDAP or Active Directory credentials, alongside local accounts and SSO.

<Info>
  Configure this under **Organization → LDAP / AD** as the appliance **owner**.
  Directory sign-in is an **appliance-only** feature — it is not available on the
  hosted (SaaS) service.
</Info>

## How it works

When a user signs in with a directory identifier, the appliance binds to your
LDAP/AD server to verify their password, then transparently creates a local
account for them the first time (**just-in-time provisioning**). No passwords
from your directory are ever stored on the appliance.

New directory users are provisioned as **members**. An owner elevates them to a
higher role (admin, security officer, auditor) afterwards, exactly like any other
user.

<Warning>
  Your directory password is used **only** to verify your identity. It never
  unlocks a zero-knowledge room. Zero-knowledge vaults are protected by a
  separate **vault passphrase** you set the first time you open an encrypted
  room — never reuse your directory password for it.
</Warning>

## Sign-in format

The sign-in identifier tells the appliance which login path to use:

| You type                                      | Routed to                            |
| --------------------------------------------- | ------------------------------------ |
| `directory\username` or `directory\|username` | **LDAP / AD** (the named connection) |
| `you@example.com`                             | Local account or SSO                 |
| `username`                                    | Local account                        |

`directory` is the **connection name** you choose below (for example `corp`), so a
user signs in as `corp\jsmith`.

## Step 1 — Create a connection

Under **Organization → LDAP / AD → Add connection**, fill in:

<AccordionGroup>
  <Accordion title="Identity">
    * **Name** — a short lowercase label (letters, digits, hyphens), used as the
      prefix in the sign-in identifier, e.g. `corp`.
    * **Enabled** — turn the connection on once it tests green.
  </Accordion>

  <Accordion title="Connection">
    * **Hosts** — one or more `host:port` entries (comma-separated). Additional
      hosts are tried in order for failover. Default ports are `636` (LDAPS) and
      `389` (StartTLS).
    * **TLS mode** — `ldaps` (implicit TLS, recommended) or `starttls`. Plaintext
      LDAP is **not permitted**.
    * **CA certificate** — paste the PEM of the CA that signed your directory's
      certificate if it is not publicly trusted.
    * **Timeout** — per-operation timeout in seconds (default 10).
  </Accordion>

  <Accordion title="Service account">
    * **Bind DN** and **Bind password** — a read-only account used to look up
      users before verifying their password. Leave blank only if your directory
      permits anonymous search. The bind password is encrypted at rest with the
      platform KMS and is never returned to the browser.
  </Accordion>

  <Accordion title="User search">
    * **User base DN** — where to search for users, e.g.
      `OU=Staff,DC=corp,DC=example,DC=com`.
    * **User filter** — must contain exactly one `%s` placeholder for the typed
      username, e.g. `(sAMAccountName=%s)` for AD or `(uid=%s)` for OpenLDAP.
    * **Attributes** — which directory attributes map to username, email, first
      name, last name, and the immutable ID. Defaults are AD-friendly
      (`sAMAccountName`, `mail`, `givenName`, `sn`, `objectGUID`); OpenLDAP
      typically uses `uid`, `mail`, `givenName`, `sn`, `entryUUID`.
  </Accordion>
</AccordionGroup>

## Step 2 — Test before enabling

Use **Test** to dial the server, negotiate TLS, bind the service account, and
confirm the base DN is searchable. Fix any reported error before you enable the
connection — a disabled or untested connection cannot be used to sign in.

## Security notes

* **TLS is mandatory.** Connections must use LDAPS or StartTLS; plaintext binds
  are rejected.
* **Injection-safe.** Usernames are escaped before they are placed into the
  search filter.
* **Empty passwords are rejected** before binding, to defeat LDAP
  "unauthenticated bind" acceptance.
* **Disabled directory accounts are refused** (AD `userAccountControl`).
* **Lockout** applies to wrong-password attempts just like local sign-in;
  transient server/config failures (a domain controller being unreachable) do
  **not** count toward lockout.
* **Rename-safe.** Users are de-duplicated by their immutable directory ID
  (`objectGUID` / `entryUUID`), so renaming or re-emailing a user in the
  directory does not create a duplicate appliance account.
* **Skip TLS verification** is available for lab use only and is clearly marked;
  never enable it in production.

## What directory users can do

Once provisioned and elevated by an owner, a directory user has the **same
capabilities as any other user** — including every room encryption mode
(standard, zero-knowledge, and zero-knowledge strict). The vault passphrase they
set on first use of an encrypted room protects their private key independently of
their directory credentials.