> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/7/administrator-guide/ldap.md).

# LDAP

Flopsar can authenticate operators against an external LDAP directory (for example Microsoft Active Directory) in addition to local accounts. When LDAP is enabled, sign-in uses a **bind → search → bind** flow: the server binds with a service account, searches for the user entry, then re-binds as that user with the supplied password to verify the credentials. 

The directory is the source of truth for both identity and authorization. On each login Flopsar reads the user's **group memberships** and maps them to a Flopsar **role** (see *Group-to-Role Mapping*). An LDAP user's identity and role exist only for the duration of the session and are **not stored** in Flopsar's local database — they are recomputed from the directory at every login. 

Local accounts always take precedence: if a username matches a local account, that account is used and LDAP is not consulted.

<figure><img src="/files/lIExLKeuvcJ7yCfYPJ8I" alt=""><figcaption></figcaption></figure>

## Connection modes

The transport is controlled by two switches — **Use SSL/TLS** and **Skip Certificate Verification** — which combine into three meaningful modes. The **Server URL** field holds only the host (and optional port), e.g. `192.168.1.198` or `dc01.win.local:636`; the `ldap://` or `ldaps://` scheme is derived automatically from the SSL switch (default ports 389 for LDAP, 636 for LDAPS).

<figure><img src="/files/mOD57x2gXORD3IgHDxBB" alt="" width="375"><figcaption></figcaption></figure>

### 1. No SSL — plaintext LDAP

*Use SSL/TLS off.*&#x20;

The server connects over `ldap://`. The bind DN, bind password, user search, and the user's own password all travel **in clear text** over the network. The Skip Verify switch and the CA Certificate field have no effect in this mode.&#x20;

Use this only on an isolated, fully trusted segment (for example a localhost or back-to-back link). It is not appropriate for production directory traffic.

### 2. SSL with verification skipped

*Use SSL/TLS on, Skip Certificate Verification on.*&#x20;

The server connects over `ldaps://`, so the channel is **encrypted**, but the directory's certificate is **not validated** — any certificate, including a self-signed or mismatched one, is accepted. This protects against passive eavesdropping but **not against an active man-in-the-middle** attacker who can present a forged certificate.&#x20;

Use it only as a temporary measure while bootstrapping, or in lab environments. The interface flags it as "Not recommended for production."

### 3. SSL with verification (recommended)

*Use SSL/TLS on, Skip Certificate Verification off.*&#x20;

The server connects over `ldaps://` and **validates the directory's certificate** against a trust store. The trust store is built from the operating system's native CA certificates, plus any certificate you paste into the **CA Certificate (PEM)** field.

* If your directory's certificate chains up to a publicly trusted or OS-installed CA, you can leave the CA Certificate field empty.
* If your directory uses an **internal/enterprise CA** that is not in the host trust store, paste that CA certificate (PEM) into the field so the chain can be verified. See *Obtaining the CA certificate* below.&#x20;

This is the recommended mode for production: it provides both confidentiality and authentication of the directory server.

## Connection Settings

* **Server URL** — directory host, optionally with port, without a scheme (e.g. `dc01.win.local`).
* **Bind DN** — distinguished name of the service account used for the initial bind and the user/group searches (e.g. `CN=svc-flopsar,OU=Service,DC=win,DC=local`). Active Directory also accepts a `userPrincipalName` or `DOMAIN\user` form.
* **Bind Password** — password for the service account.
* **Use SSL/TLS**, **Skip Certificate Verification**, **CA Certificate (PEM)** — the transport settings described above.&#x20;

The service account needs only enough rights to bind and to read the user and group entries under the configured base DNs.

## User Settings

These settings tell Flopsar how to locate the person signing in.

* **User Base DN** — the subtree searched for user entries (e.g. `DC=win,DC=local`).
* **User UID Attribute** — the attribute matched against the login name. For Active Directory this is typically `sAMAccountName`; for generic LDAP, `uid`.
* **User Filter** — an optional additional LDAP filter, ANDed with the UID match, used to restrict which entries qualify (e.g. `(objectClass=person)`). Leave it empty to match on the UID attribute alone.

<figure><img src="/files/PhPpuXHSsODVt7sTv53a" alt="" width="563"><figcaption></figcaption></figure>

## Group Settings

These settings tell Flopsar how to discover the groups a user belongs to, which in turn drive role assignment.

* **Group Base DN** — the subtree searched for group entries (e.g. `OU=Groups,DC=win,DC=local`).
* **Group Filter** — an LDAP filter identifying group objects (e.g. `(objectClass=groupOfNames)`).&#x20;

Flopsar first reads the user entry's `memberOf` attribute, which Active Directory and OpenLDAP (with the memberof overlay) expose directly. If that attribute is not present, and a Group Base DN is configured, Flopsar performs a reverse search for group entries that list the user as a `member`, combined with the Group Filter. Either way, the result is a set of group DNs used for role mapping.

<figure><img src="/files/odlY8gZtXh8kdQlN7zxY" alt="" width="563"><figcaption></figcaption></figure>

## Group-to-Role Mapping

Authorization for LDAP users is driven entirely by their directory groups. The mapping itself is configured on each **role**, not on this page: a role may be given an **LDAP group DN**, and any user who belongs to that group receives that role (see *Roles*).&#x20;

Resolution rules at login:

* The user's group DNs are compared **case-insensitively** to each role's mapped group DN.
* Because a user holds a single role, if several mapped groups match, Flopsar assigns the **most privileged** matching role (the one with the most permissions; ties are broken deterministically by role).
* If no group matches any mapping, the user falls back to the built-in **Guest** role.&#x20;

Because identities are not persisted, changing a user's groups in the directory — or changing a role's group mapping — takes effect at the user's next login.

## Obtaining the CA certificate

The **CA Certificate (PEM)** field expects the **PEM-encoded certificate of the authority that issued your directory's TLS certificate** (your AD Certificate Services root, or its issuing CA) — not the domain controller's own (leaf) certificate. A PEM certificate is a text block delimited by `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.

How to obtain this certificate depends on how your directory and its CA are set up, so there is no single universal command. Ask your directory or PKI administrator for the CA certificate, or follow the export procedure in your directory vendor's documentation (for example, the documentation for your Active Directory / AD Certificate Services deployment). Request it in PEM format; if you receive a DER/`.cer` file, your administrator can convert it to PEM.&#x20;

Once you have the PEM text, paste it into the **CA Certificate (PEM)** field, keep *Use SSL/TLS* on and *Skip Certificate Verification* off, then confirm with **Test Login**.

## Testing the configuration

Three test actions let you validate settings incrementally, in increasing order of coverage. All of them honor the current SSL / Skip Verify / CA Certificate settings, so they exercise exactly the same transport that live sign-in will use.

* Test Connection — binds with the Server URL, Bind DN, and Bind Password. Confirms that the host is reachable, the TLS settings are correct, and the service-account credentials are valid. It does not search for any user.
* Test Query — performs the bind and then searches the User Base DN with your User UID Attribute and User Filter, returning the number of matching users. Use it to confirm that the base DN, UID attribute, and filter resolve to the expected set of accounts.
* Test Login — runs the full end-to-end flow: service-account bind, search for a specific username, then bind as that user with the supplied password. This is the definitive check that a real user can authenticate. Enter a sample user's credentials in the dialog.

<figure><img src="/files/JxhaE2K6WSsOcno4Yahp" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
The **Query Users** action is available only after the configuration has been saved **with Enable LDAP turned on** (it is hidden while you are editing and when LDAP is disabled). It lists matching directory users (common name, login, DN) so you can check your settings.
{% endhint %}