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:
+69
-1
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user