From dbe36855764c831b5ba051966b6f0e8b7e349857 Mon Sep 17 00:00:00 2001
From: Russ Garrett <russ@garrett.co.uk>
Date: Tue, 5 Sep 2023 13:09:44 +0100
Subject: [PATCH] Update README with some useful info
---
README.md | 29 +++++++++++++++++++++++++----
1 file changed, 25 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index 60fb62d..6a4e596 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,29 @@ Uffd LDAP Proxy Server
Proxy server to provide uffd user and group data via LDAP.
Based on [python-ldapserver](https://git.cccv.de/uffd/python-ldapserver).
-To install uffd-ldapd on Debian, add the [uffd Debian repository](https://packages.cccv.de/uffd/) to `/etc/sources.list` and install the package `uffd-ldapd`.
-Update the config file `/etc/uffd-ldapd.conf` and restart the service with `systemctl restart uffd-ldapd`.
-The proxy server listens on `ldap://127.0.0.1:389/`.
+`uffd-ldapd` communicates with uffd over the API. It is intended to run locally on the same host as each LDAP client, so it does not support TLS.
-uffd-ldapd requires at least uffd v1.2.0!
+## Installation
+
+`uffd-ldapd` requires at least uffd v1.2.0!
+
+To install `uffd-ldapd` on Debian, add the [uffd Debian repository](https://packages.cccv.de/uffd/) to `/etc/sources.list` and install the package `uffd-ldapd`.
+
+Create a new service and API client in uffd. The API client will need at least the `users` permission.
+If you need to check passwords, it will also need the `checkpassword` permission.
+
+Update the config file `/etc/uffd-ldapd.conf` with your API credentials and restart the
+service with `systemctl restart uffd-ldapd`. The proxy server listens on `ldap://127.0.0.1:389/`.
+
+## Usage
+
+This section assumes you've configured `dc=example,dc=com` as your `SERVER_BASE_DN`, but you should probably use your actual domain.
+
+If you've configured the `SERVER_BIND_PASSWORD` in the config, your LDAP clients will need to bind as `cn=service,ou=system,dc=example,dc=com` to list all users. Otherwise they can be listed anonymously.
+
+Users from uffd will be exposed under the `ou=users,dc=example,dc=com` OU. To check passwords you can perform a simple bind to `uid={username},ou=users,dc=example,dc=com` or use SASL PLAIN authentication.
+
+### Authentication errors
+
+* **Invalid credentials (49)**: the bind DN is not a child of `ou=users,dc=example,dc=com`, the `uid` component is not present in the bind DN, or the credentials are wrong.
+* **Insufficient access (50)**: the API client configured for `uffd-ldapd` does not have the `checkpassword` permission.
--
GitLab