WebLDAPPasswd/README.md

# WebLDAPPasswd

WebLDAPPasswd is a web application that provides a single form with which users
of an LDAP3 accessible directory can change their passwords.

## Setup

The following steps provide a guideline to setting up WebLDAPPasswd. Adapt them
to your liking.

0. Copy the `webldappasswd` exectuable to `/usr/bin/`. If you choose a different
   location, you have to adapt the Systemd unit file `webldappasswd.service`
   later on.
1. Create a user `webldappasswd` without shell and without home directory. If
   you choose a different username or do not create a new one, you have to adapt
   the Systemd unit file `webldappasswd.service` later on.
2. Ensure that the directory `/etc/webldappasswd` exists
3. Copy the configuration file `config.json` to `/etc/webldappasswd/`. If you
   want to place the configuration file in a different location, you have to
   adapt the Systemd unit file `webldappasswd.service` by providing the
   configuration file path as an argument to the `webldappasswd` exectuable
   (see section "Executable").
4. Adapt the configuration file `config.json` in `/etc/webldappasswd/` to your
   needs (see section "Configuration")
5. Setup your reverse proxy (for example Nginx):
   1. Choose a root for the application (for example `https://example.com/wlp/`)
   2. Forward every request under that root except for the following to the
      configured host and port of `webldappasswd`
   3. Serve your own `legal.html` under that root
   4. Optionally serve your own `webldappasswd.css`, `cross.svg`,
      `checkmark.svg`, `hourglass.svg`, or `logo.svg` under that root.
6. Setup the Systemd service
   1. Copy the Systemd unit file `webldappasswd.service` to
      `/etc/systemd/system`
   2. Enable and start the service `webldappasswd`.

## Configuration

The configuration file `config.json` is, as the file extension indicates, a
JSON file. It must contain an object with up to four key-value pairs,  exactly
one of which is mandatory:

- The key `"dn"` must be present and point tothe distinguished name (DN) pattern
  for users of the directory. The pattern `{{username}}` must be used as a
  placeholder for the username of a user.
- The key `"ldap_url"` may be present and point to a value for the URL of the
  directory's LDAP3 API endpoint. The default value is `"ldap://localhost"`.
- The key `"host"` may be present and sets the host under which `webldappasswd`
  listens for HTTP requests. The default value is `"localhost"`.
- The key `"port"` may be present and sets the port under which `webldappasswd`
  listens for HTTP requests. The default value is `8000`.

## Executable

The executable takes one optional parameter, `-c CONFIG_FILE_PATH` or
`--config CONFIG_FILE_PATH`, that takes a path to a configuration file that
overrides the default of `/etc/webldappasswd/config.json`. The expected
contents are described in the configuration section.

WebLDAPPasswd logs errors to `stderr` (file descriptor 2).

## License

WebLDAPPasswd is published by Philipp Matthias Schäfer
<philipp.matthias.schaefer@posteo.de> under the AGPL3 license. See
[LICENSE](LICENSE) for a copy of that license.

## Dependencies

WebLDAPPasswd directly depends on the following Rust libraries all published by
their copyright holders under the MIT License:

* [anyhow](https://github.com/dtolnay/anyhow)
* [clap](https://clap.rs)
* [serde](https://serde.rs)
* [serde_derive](https://serde.rs)
* [serde_json](https://serde.rs)
* [ldap3](https://github.com/inejge/ldap3)
* [rocket](https://rocket.rs)
* [rocket_contrib](https://rocket.rs)