Document connecting a 3rd-party app or container to LDAP

Adds a concrete "Connecting a 3rd-party app or container" section:
a bind-parameter reference table, a worked Gitea example, a generic
Docker LDAP_* env var pattern, and a pointer to theta42/ldap-client for
full host-level (SSH/sudo/PAM) integration as opposed to a single app.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-15 17:25:54 -04:00
parent cbc09a7fdd
commit db8f44b721
+69 -1
View File
@@ -95,7 +95,10 @@ The entrypoint leaves existing certs untouched (idempotent).
For apps that bind LDAP directly, create a dedicated **service account** under For apps that bind LDAP directly, create a dedicated **service account** under
`ou=people` (e.g. `cn=ldapclient,ou=people,<base>`) with a strong password — `ou=people` (e.g. `cn=ldapclient,ou=people,<base>`) with a strong password —
**don't reuse the admin DN**. The theta-env bootstrap creates this account **don't reuse the admin DN**. The theta-env bootstrap creates this account
automatically (`cn=ldapclient`) and the proxy binds as it. automatically (`cn=ldapclient`) and the proxy binds as it. For anything else,
create a normal user via the Users page (or `POST /api/user`) and just don't
put it in `app_sso_admin` or any other privileged group — a plain
`posixAccount` with a strong password is all a read-only bind account needs.
Example bind test: Example bind test:
@@ -105,6 +108,71 @@ ldapsearch -x -H ldaps://sso.example.com:636 \
-b "ou=people,dc=yourdomain,dc=com" '(objectClass=posixAccount)' cn mail -b "ou=people,dc=yourdomain,dc=com" '(objectClass=posixAccount)' cn mail
``` ```
## Connecting a 3rd-party app or container
Most self-hosted apps with an "LDAP authentication" settings page — Gitea,
Nextcloud, Grafana, Emby, Jenkins, etc. — or containers configured via
`LDAP_*` env vars, all ask for the same handful of values. These are the
`conf.ldap` values from [Configuration](configuration.html), applied to
*your* domain:
| Field the app asks for | Value |
|---|---|
| Host / URL | `ldaps://<your-sso-host>:636` (preferred), or `ldap://<host>:389` + StartTLS |
| Bind DN | a dedicated service account — e.g. `cn=ldapclient,ou=people,<base>` (see above) |
| Bind password | that service account's password |
| User search base | `ou=people,<base>` |
| User search filter | `(objectClass=posixAccount)` |
| Username attribute | `uid` |
| Email attribute | `mail` |
| Group search base | `ou=groups,<base>` |
| Group membership attribute | `memberOf` (on the user entry — populated by the `memberof` overlay) |
| TLS | required for 636 (LDAPS); if using the bundled self-signed cert, either trust it (see *TLS* above) or set the app's "don't verify cert" option for LAN-only use |
### Worked example: Gitea
Gitea's **Admin → Authentication Sources → Add Authentication Source** (type
LDAP, "Bind DN/Password") maps directly:
- Security Protocol: `LDAPS`
- Host / Port: your SSO host / `636`
- Bind DN: `cn=ldapclient,ou=people,dc=yourdomain,dc=com`
- Bind Password: the service account's password
- User Search Base: `ou=people,dc=yourdomain,dc=com`
- User Filter: `(&(objectClass=posixAccount)(uid=%s))`
- Username Attribute: `uid`
- E-mail Attribute: `mail`
Other apps with an LDAP settings UI follow the same shape — the field names
above are the constants; only the base DN and hostname change per deployment.
### Generic Docker container (`LDAP_*` env vars)
For images that take a flat env-var LDAP config (there's no single standard,
but most look like this):
```yaml
environment:
LDAP_URL: ldaps://sso.example.com:636
LDAP_BIND_DN: cn=ldapclient,ou=people,dc=yourdomain,dc=com
LDAP_BIND_PASSWORD: <service-account-password>
LDAP_USER_BASE: ou=people,dc=yourdomain,dc=com
LDAP_USER_FILTER: (objectClass=posixAccount)
LDAP_GROUP_BASE: ou=groups,dc=yourdomain,dc=com
```
Check the specific image's docs for its actual variable names — the values
you plug in are still the ones from the table above.
### Full Linux host auth (SSH, sudo, login) instead of a single app
If you want a *host* (not just one app) to authenticate logins, SSH keys, and
sudo against this LDAP directory — not just one application — that's a
different integration (SSSD + PAM + NSS, not a single bind). See
[theta42/ldap-client](https://github.com/theta42/ldap-client): a script that
configures SSSD on Ubuntu/Debian hosts against this directory, including
group-based access control and SSH public key retrieval from LDAP.
## Modules + overlays (external LDAP servers) ## Modules + overlays (external LDAP servers)
If you point the app at your own LDAP server instead of the bundled slapd, it If you point the app at your own LDAP server instead of the bundled slapd, it