diff --git a/README.md b/README.md
index 60fb62d04e0da271535c28c15e3226c9bbf6c400..6a4e5969522a41787968ebd829a832440c18caa3 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.