update: Added OpenLDAP and OpenVPN to the router.

ADR.md

@@ -75,3 +75,76 @@ configuration file and in `/run/vpn-router/web.json`, both readable by root only
 the answer cross the network unencrypted, so the page is for a trusted internal network; HTTPS
 would need a certificate that the package does not have. The masking is by option name, so a new
 secret option needs a name that matches.
+
+## ADR-4: Users are kept in a local OpenLDAP directory
+
+Status: Accepted
+
+Context: OpenVPN needs user accounts with passwords, and the users are meant to cover every P2S
+system of the router. The options weighed were an external OIDC provider (Entra ID, Keycloak)
+with openvpn-auth-oauth2, an OIDC server embedded on the router, a file of password hashes, and
+OpenLDAP on the router. OIDC for OpenVPN needs a browser on the client and a program from outside
+the Ubuntu archive, and it cannot authenticate IKEv2 EAP-TLS or WireGuard. slapd, its Python
+module `python3-ldap` and the OpenVPN plugin `openvpn-auth-ldap` are all in the archive; the
+plugin checks a password by binding as the user, so the hash scheme is slapd's alone. A directory
+can also be read later by an OIDC provider through its LDAP connector.
+
+Decision: The users are entries in slapd. The package keeps its own database,
+`dc=vpn-router,dc=local` in `/var/lib/ldap/vpn-router` (the path the slapd AppArmor profile
+allows), next to the database the slapd package creates from the host's domain, so the package
+does not depend on the debconf answers of slapd. Its root DN is root's peer-credential DN on the
+local socket, so `vpn-router-setup` manages it with SASL EXTERNAL and no administrator password
+exists. Users are changed by `cn=user-manager,ou=services`, whose ACLs allow writing `ou=users`
+and setting passwords (`=wx`) but not reading them. Passwords are hashed with ARGON2, and the
+ppolicy overlay locks a disabled user (`pwdAccountLockedTime`, effective with `pwdLockout`).
+slapd listens on the local socket only. Provisioning checks every step before changing it, so it
+runs at every start of `vpn-router-setup`.
+
+Consequences: The package depends on `slapd`, `python3-ldap`, `openvpn` and
+`openvpn-auth-ldap`, and `vpn-router-setup` and `vpn-router-user` import `python3-ldap`, the first
+library outside the standard library besides `jinja2`. The service account's password is a
+root-only file. The directory is user data: it is kept when the features are switched off and
+on purge, and it is backed up with `slapcat`, not by copying files.
+
+## ADR-5: OpenVPN clients need a certificate and the password of the user it names
+
+Status: Accepted
+
+Context: The router CA already issues client certificates for IKEv2. OpenVPN can check a
+certificate, a password, or both. With both, a certificate alone and a password alone are not
+enough, but `openvpn-auth-ldap` checks only the password of the user name given at login, which
+need not be the user of the certificate.
+
+Decision: OpenVPN checks the certificate against the CA and the CRL, the password with
+`openvpn-auth-ldap`, and runs `openvpn-same-user` as `auth-user-pass-verify` with `via-env`,
+which accepts the login only when the user name equals the certificate's common name. OpenVPN
+calls both and needs both to pass. A user's certificate has the user name as its common name, is
+issued when the user is added and revoked when the user is removed. The CRL is created with the
+CA, so that `crl-verify` has a file from the start, and is valid for ten years, because the router
+renews it only when it revokes a certificate. The server uses the router's own certificate, whose
+common name is `wan.local_fqdn`; the client profile checks that name (`verify-x509-name`), since
+the CA's certificates carry both the server and the client purpose.
+
+Consequences: Disabling a user locks the password, which stops OpenVPN but not IKEv2, which
+checks certificates only; removing a user revokes the certificate for both. A user's
+certificate expires after the CA's default of a year and is renewed by removing and adding the
+user again.
+
+## ADR-6: The web service manages users by running vpn-router-user
+
+Status: Accepted
+
+Context: The web service has only the standard library (ADR-2), and managing users needs
+`python3-ldap` and `simple-ca`. Its unit is sandboxed with `ProtectSystem=strict`.
+
+Decision: `/users` runs `vpn-router-user` and returns its JSON answer, mapping its exit status
+to the HTTP status. Passwords go to the program on standard input, so they never appear in a
+command line. The unit allows writing the paths the program needs: `/run/vpn-router` for its
+lock, `/etc/vpn-router/pki` for the certificates and the CA's state, and `/etc/swanctl/x509crl`
+for the published CRL. A lock serializes the program's runs, because `simple-ca` keeps its state
+in one file.
+
+Consequences: The web service still imports nothing outside the standard library, and the same
+program serves the command line and the API. Each request starts a process, which is fine for
+user administration. The API is protected by the token of `/config`, so whoever has the secret
+can manage users.