Heavy refactoring: New CT API incl. token usage, async/await and more

.dockerignore

@@ -1,9 +1,5 @@
-.git
-.idea
-test/
-.env
-.gitignore
-*.iml
-ctldap_raw.sh
-docker-compose.yml
-install.sh
+*
+!ctldap.js
+!ctldap.yml
+!package.json
+!yarn.lock

.env.dist

@@ -1,24 +1,34 @@
-# Add debug infos to log
-DEBUG=false
+# Add debug infos to log, non-empty string means "true"!
+#DEBUG=true
 # This is required for clients using lowercase DNs, e.g. ownCloud/nextCloud
 IS_DN_LOWER_CASE=true
+# This is required for clients that need lowercase email addresses, e.g. Seafile
+IS_EMAIL_LOWER_CASE=true
 
-# LDAP admin user, can be a "virtual" root user or a ChurchTools user name (virtual root is recommended!)
+# LDAP admin user, can be a "virtual" root user or a ChurchTools username (virtual root is recommended!)
 LDAP_USER=root
-# The static password to be used for the ldap_user if it is NOT a CT account, or the account password of the chosen user otherwise
-# If you did not use install.sh, choose a LONG SECURE RANDOM password from a password generator like KeePass!
-LDAP_PW=XXXXXXXXXXXXXXXXXXXX
-# LDAP server port
-LDAP_PORT=1389
-# LDAP base DN o=xxx, e.g. churchtools
+# The static password to be used for the virtual ldapUser, i.e. if that one is NOT a CT account.
+# Ideally, choose a LONG SECURE RANDOM password from a password generator like KeePass and hash it with argon2!
+LDAP_PW=some-bcrypt-hash-or-argon2-hash-or-plaintext-password
+# LDAP base DN, "o=<xxx>", e.g. "o=churchtools"
 LDAP_BASE_DN=churchtools
 
+# LDAP server ip to listen on, change it to 0.0.0.0 when external access required
+LDAP_IP=0.0.0.0
+# LDAP server port, you may change this to the privileged default port 389.
+LDAP_PORT=1389
+
 # The URI pointing to the root of your ChurchTools installation
-CT_URI=https://mysite.church.tools/
-# This user credentials are used to authenticate against ChurchTools for API access
-# The user must be granted "churchcore:administer persons" and "churchdb:view" rights for the wrapper to work properly!
+CT_URI=https://mysite.church.tools
+# This access token is used to authenticate against ChurchTools for API access.
+# The backing user must be granted sufficient rights for the wrapper to work properly! Typically, these are:
+# churchdb:{ view | view alldata(-1) | view grouptype(-1) | security level person(1,2*) | security level group(1*) }
+# * = additional security levels might be required, depending on your ChurchTools settings.
 # IMPORTANT: It is strongly recommended to use a LONG SECURE RANDOM password from a generator like KeePass for this user!
-CT_USER=XXXXXXXXXXXXXXXXXXXX
-CT_PW=XXXXXXXXXXXXXXXXXXXX
+# You can obtain the API token from the API:
+# - Login via https://your.ct.domain/api > "General" > "login" (copy your "personId" from the shown output!)
+# - Get your token via "Person" > "/persons/{personId}/logintoken"
+API_TOKEN=">>>insert API token here<<<"
+
 # This controls (in milliseconds) how old the user/group data can be until it is fetched from ChurchTools again
-CACHE_LIVETIME=10000
+CACHE_LIFETIME_MS=300000

.gitignore

@@ -1,4 +1,3 @@
-/ctldap.config
 /ctldap.sh
 /node_modules
 /.idea/

Dockerfile

@@ -1,37 +1,30 @@
-FROM node:12-alpine
+FROM node:18-alpine
 LABEL maintainer="Michael Lux <[email protected]>"
 
-RUN mkdir /app && chown node:node /app
-USER node
 WORKDIR /app
+RUN chown node:node /app
+USER node
 
-COPY . .
+COPY --chown=node:node package.json .
+COPY --chown=node:node yarn.lock .
 RUN yarn install
 
+COPY --chown=node:node ctldap.js .
+COPY --chown=node:node ctldap.yml .
+
 EXPOSE 1389
 
-ENV DEBUG false
+ENV DEBUG ""
 ENV IS_DN_LOWER_CASE true
+ENV IS_EMAIL_LOWER_CASE true
 ENV LDAP_USER root
 ENV LDAP_PW XXXXXXXXXXXXXXXXXXXX
-ENV LDAP_PORT 1389
+ENV LDAP_PW_BCRYPT ""
 ENV LDAP_BASE_DN churchtools
+ENV LDAP_IP 0.0.0.0
+ENV LDAP_PORT 1389
 ENV CT_URI https://mysite.church.tools/
-ENV CT_USER XXXXXXXXXXXXXXXXXXXX
-ENV CT_PW XXXXXXXXXXXXXXXXXXXX
-ENV CACHE_LIVETIME 10000
+ENV API_TOKEN ""
+ENV CACHE_LIFETIME_MS 10000
 
-# Update config by environment variables and start ctldap server
-CMD cp ctldap.example.config ctldap.config && \
-    sed -i "s/^\(debug\s*=\s*\).*\$/\1$DEBUG/" ctldap.config && \
-    sed -i "s/^\(dn_lower_case\s*=\s*\).*\$/\1$IS_DN_LOWER_CASE/" ctldap.config && \
-    sed -i "s/^\(ldap_user\s*=\s*\).*\$/\1$LDAP_USER/" ctldap.config && \
-    sed -i "s/^\(ldap_password\s*=\s*\).*\$/\1$LDAP_PW/" ctldap.config && \
-    sed -i "s/^\(ldap_ip\s*=\s*\).*\$/\10.0.0.0/" ctldap.config && \
-    sed -i "s/^\(ldap_port\s*=\s*\).*\$/\1$LDAP_PORT/" ctldap.config && \
-    sed -i "s/^\(ldap_base_dn\s*=\s*\).*\$/\1$LDAP_BASE_DN/" ctldap.config && \
-    sed -i "s#^\(ct_uri\s*=\s*\).*\$#\1$CT_URI#" ctldap.config && \
-    sed -i "s/^\(api_user\s*=\s*\).*\$/\1$CT_USER/" ctldap.config && \
-    sed -i "s/^\(api_password\s*=\s*\).*\$/\1$CT_PW/" ctldap.config && \
-    sed -i "s/^\(cache_lifetime\s*=\s*\).*\$/\1$CACHE_LIVETIME/" ctldap.config && \
-    node ctldap.js
+CMD ["node", "ctldap.js"]

README.md

@@ -1,38 +1,26 @@
-# LDAP Wrapper for ChurchTools v2.2.2
+# ctldap 3.0.0 - LDAP Wrapper for ChurchTools
 
-This software acts as an LDAP server for ChurchTools >= 3.25.0
+This software acts as an LDAP server for ChurchTools 3
 
 **This software was tested in a common environment, yet no warranties of any kind!** 
 
 # Installation
-Node.js is required to run this software.
-http://nodejs.org/
+`Docker` is required to run `ctldap`, `docker compose plugin` is strongly recommended.
 
-## Node.js install
+The old installation methods are discouraged and won't be supported any further.
 
-### Run the install.sh script as root user. It will
-- run "npm install" to install required Node.js dependencies for the server
-- create a new user "ctldap" to run the server with limited privileges
-- create the configuration file, asking for a reset if it already exists
-- *[new config or reset]* ask for the ChurchTools domain (and directory)
-- *[new config or reset]* ask for the ChurchTools API user credentials and insert them into the config file
-- *[new config or reset]* insert a secure random LDAP root user password into the config file
-- *[new config or reset]* offer to customize the config file
-- *optionally adapt and create the ctldap.sh file in /etc/init.d and call "update-rc.d ctldap.sh defaults"*
+## Migration from version 2.2.2
+Version 3.0.0 includes some breaking changes in the configuration format and some parameters.
+Assuming Docker setup, the necessary adaptations are not that difficult, though.
 
-#### ctldap.sh remarks:
-The file "ctldap.sh" contains a shell script for (re)starting ctldap.sh with Node.js as a background service, redirecting all output to the system log with systemd-cat. The logs can be reviewed with the shell command `journalctl -t ctldap`. See https://wiki.ubuntuusers.de/systemd/journalctl/ for further options.
-
-The script will attempt to create/remove an iptables NAT rule on start/stop in order to redirect traffic from a standard LDAP port (< 1024) to ldap_port without root.
-
-It can be used to start/stop the service manually, but will not work correctly without root privileges!
-
-Usage: ctldap.sh {start|stop|status|restart}
-
-### If you don't have root privileges:
-- run `yarn install` or `npm install` manually or otherwise trigger the installation of required dependencies
-- copy "ctldap.example.config" to "ctldap.config" and adjust the required settings accordingly
-- register "ctldap.js" to be run by Node.js, or start the server directly by executing `node ctldap.js`
+- The `CT_USER` and `CT_PW` env vars have been replaced by `API_TOKEN`. You should remove these.
+- You can also delete `LDAP_PW_BCRYPT`. The password encoding is now auto-detected.
+  ctldap 3.0.0 supports plaintext, bcrypt hashes, and argon2 hashes (recommended) for your LDAP admin user.
+- Specify `API_TOKEN`. You can obtain your token as follows:
+  - Login with **your CT LDAP user** via https://your.ct.domain/api > `General` > `login`
+  (copy the `personId` from the shown output!)
+  - Fetch the token via `Person` > `/persons/{personId}/logintoken`
+- Apply the typo fix on `CACHE_LIVETIME` by renaming it to `CACHE_LIFETIME_MS`.
 
 # Usage
 The LDAP DNs depend on your configuration. Let's assume the following configuration:
@@ -41,7 +29,7 @@ ldap_user=root
 ldap_password=0a1b2c3d4e5f6g7h8i9j
 ldap_base_dn=churchtools
 ```
-For this configuration, the
+For such a configuration, the
 - admin DN for initial binding is `cn=root,ou=users,o=churchtools`
 - password for initial binding is `0a1b2c3d4e5f6g7h8i9j`
 - users are found in the organizational unit `ou=users,o=churchtools`