doc: Document usage for end users

Dockerfile

@@ -26,4 +26,5 @@ RUN apt update && apt install ca-certificates -y
 RUN mkdir -p /opt/${PROJECT_NAME}
 WORKDIR /opt/${PROJECT_NAME}
 COPY --from=builder /app/target/release/${PROJECT_NAME} /usr/local/bin/${PROJECT_NAME}
-ENTRYPOINT ["/usr/local/bin/${PROJECT_NAME}"]
+ENV FAMEDLY_LDAP_SYNC_CONFIG="/opt/config.yaml"
+ENTRYPOINT ["/usr/local/bin/ldap-sync"]

README.md

@@ -2,6 +2,57 @@
 
 Sync LDAP/AD users with Zitadel.
 
+## Usage
+
+The easiest way to deploy this tool is using our published docker
+container through our [composefile](./docker-compose.yaml).
+
+To prepare for use, we need to provide a handful of files in an `opt`
+directory in the directory where `docker compose` will be
+executed. This is the expected directory structure of the sample
+configuration file:
+
+```
+opt
+├── certs
+│  └── test-ldap.crt   # The TLS certificate of the LDAP server
+├── config.yaml        # An example can be found in config.sample.yaml
+└── service-user.json  # Provided by famedly
+```
+
+Once this is in place, the container can be executed in the parent
+directory of `opt` with:
+
+```
+docker compose up
+```
+
+Or alternatively, without `docker compose`:
+
+```
+docker run --rm -it --network host --volume ./opt:/opt docker-oss.nexus.famedly.de/famedly-sync-agent:latest
+```
+
+## Quirks & Edge Cases
+
+- Changing a user's LDAP id (the attribute from the `user_id` setting)
+  is unsupported, as this is used to identify the user on the Zitadel
+  end.
+- Disabling a user on the LDAP side (with `status`) results in the
+  user being deleted from Zitadel.
+- Providing multiple values for an LDAP attribute is not supported.
+- Zitadel's API is not fully atomic; if a request fails, a user may
+  not be fully created and still not be functional even if the tool is
+  re-used.
+  - In particular, the matrix localpart, the preferred user name, and
+    whether the user has permissions to use Famedly may not be synced.
+- If a user's email or phone number changes, they will only be
+  prompted to verify it if the tool is configured to make users verify
+  them.
+- Changing a user's email also immediately results in a new
+  login/username.
+- If SSO is turned on later, existing users will not be linked.
+
 ## Testing & Development
 
 This repository uses [`nextest`](https://nexte.st/) to perform test
@@ -48,41 +99,7 @@ client certificates, but if one is provided, it must be verified
 correctly. This allows us to test scenarios with and without client
 certificates.
 
-## Quirks & Edge Cases
-
-- Changing a user's LDAP id (the attribute from the `user_id` setting)
-  is unsupported, as this is used to identify the user on the Zitadel
-  end.
-- Disabling a user on the LDAP side (with `status`) results in the
-  user being deleted from Zitadel.
-- Providing multiple values for an LDAP attribute is not supported.
-- Zitadel's API is not fully atomic; if a request fails, a user may
-  not be fully created and still not be functional even if the tool is
-  re-used.
-  - In particular, the matrix localpart, the preferred user name, and
-    whether the user has permissions to use Famedly may not be synced.
-- If a user's email or phone number changes, they will only be
-  prompted to verify it if the tool is configured to make users verify
-  them.
-- Changing a user's email also immediately results in a new
-  login/username.
-- If SSO is turned on later, existing users will not be linked.
-
-[![rust workflow status][badge-rust-workflow-img]][badge-rust-workflow-url]
-[![docker workflow status][badge-docker-workflow-img]][badge-docker-workflow-url]
-
-[badge-rust-workflow-img]: https://github.com/famedly/rust-project-template/actions/workflows/rust.yml/badge.svg
-[badge-rust-workflow-url]: https://github.com/famedly/rust-project-template/commits/main
-[badge-docker-workflow-img]: https://github.com/famedly/rust-project-template/actions/workflows/docker.yml/badge.svg
-[badge-docker-workflow-url]: https://github.com/famedly/rust-project-template/commits/main
-
-Short description of the project.
-
-## Getting Started
-
-Instructions of how to get the project running.
-
-## Pre-commit usage
+### Pre-commit usage
 
 1. If not installed, install with your package manager, or `pip install --user pre-commit`
 2. Run `pre-commit autoupdate` to update the pre-commit config to use the newest template

config.sample.yaml

@@ -1,41 +1,76 @@
 ldap:
-  url: ldap://localhost:1389
+  # The URl of the ldap server to be synced.
+  # Using `ldaps` as the scheme will enable TLS.
+  url: ldap://ldap.example.invalid
+  start_tls: false
+  no_tls_verify: false
+  root_certificates_path: /opt/certs/test-ldap.crt
+  # The base DN whose users to sync.
   base_dn: ou=testorg,dc=example,dc=org
+  # The DN to bind - this should be a user with sufficient permissions
+  # to read the above DN.
   bind_dn: cn=admin,dc=example,dc=org
+  # The password of the bound user.
   bind_password: adminpassword
+  # The LDAP filter to identify user entries.
   user_filter: "(objectClass=shadowAccount)"
+  # The LDAP connection timeout
   timeout: 5
+  # Whether to sync entry deletion.
   check_for_deleted_entries: true
+  # A mapping of the LDAP attributes to Famedly attributes. This is
+  # different for different LDAP server implementations and
+  # organizations, so needs to be configured on a case-by-case basis.
+  #
+  # This sample configuration is for a reasonably standard OpenLDAP
+  # implementation.
   attributes:
-    first_name: "cn"                  # objectClass: person
-    last_name: "sn"                   # objectClass: person
-    preferred_username: "displayName" # objectClass: inetOrgPerson
-    email: "mail"                     # objectClass: inetOrgPerson
-    phone: "telephoneNumber"          # objectClass: person
+    first_name: "cn"
+    last_name: "sn"
+    preferred_username: "displayName"
+    email: "mail"
+    phone: "telephoneNumber"
     user_id: "uid"
-    status: "shadowInactive"          # objectClass: shadowAccount
+    status: "shadowInactive"
     enable_value: 512
     disable_value: 514
 
   tls:
+    # The client TLS key/certificate. If both this and the certificate
+    # are unset, the client will not send any certificates.
     client_key: ./tests/environment/certs/client.key
     client_certificate: ./tests/environment/certs/client.crt
+    # Path to the LDAP server's root certificate. If unset, only the
+    # host's default certificates will be used to verify the server.
     server_certificate: ./tests/environment/certs/server.crt
-    # Disable server TLS certificate validation
+    # Disable root certificate verification - should only be used in
+    # testing.
     danger_disable_tls_verify: false
-    # Use STARTTLS to perform the connection; this is less secure than
-    # using ldaps, but the only option for some servers.
-    #
-    # If you just want to enable TLS, use an `ldaps` URL, and the port
-    # on which the ldap server hosts TLS, instead.
+    # Whether to use STARTTLS to start the TLS connection - this is not
+    # needed with the `ldaps` scheme, as the server will already be
+    # hosting TLS.
     danger_use_start_tls: false
 
+# Configuration for the Famedly side of the sync - this has to be
+# provided by Famedly
 famedly:
-  url: http://localhost:8080
-  key_file: tests/environment/zitadel/service-user.json
-  organization_id: @ORGANIZATION_ID@
-  project_id: @PROJECT_ID@
+  # The Famedly user endpoint to sync to.
+  url: https://auth.famedly.de
+  # The Famedly-provided service user credentials.
+  key_file: /opt/service-user.json
+  # The organization whose users to sync.
+  organization_id: 278274756195721220
+  # The project to grant users access to.
+  project_id: 278274945274880004
+  # The identity provider ID to enable SSO login for
   idp_id: tbd
 
-feature_flags: []
-cache_path: ./test
+feature_flags:
+  - verify_email    # Whether to ask users to verify their email addresses post sync
+  - verify_phone    # Whether to ask users to verify their phone numbers post sync
+  # - sso_login     # Whether to enable SSO login - Please note that his has some drawbacks and limitations, see the help center article for more information
+
+# Path to the file that keeps track of previously synced entries -
+# this file should be persisted, otherwise users may become out of
+# sync.
+cache_path: /opt/famedly-sync.cache

docker-compose.yaml

@@ -0,0 +1,8 @@
+services:
+  ldap-sync:
+    image: docker-oss.nexus.famedly.de/famedly-sync-agent:latest
+    volumes:
+      - type: bind
+        source: ./opt
+        target: /opt
+    network_mode: host