Init

plugins_auth_ldap.md

@@ -0,0 +1,58 @@
+# auth_ldap Plugin
+This plugin provides authentification over LDAP.
+
+## Configuration
+A basic configuration entry inside the `flaschengeist.toml` looks like this:
+```toml
+[auth_ldap]
+enabled = true
+host = "localhost"
+port = 389
+base_dn = "cn=example,cn=com"
+root_dn = "cn=Manager,cn=example,cn=com"
+root_secret = "superS3cret"
+```
+
+* `base_dn` defines the starting point an LDAP server uses when searching for users
+* `root_dn` is the DN of you manager account used for creating new entries
+* `root_secret` secret of the manager account
+
+### Set up password hash
+The default password hash algorithm used by common LDAP applications and OpenLDAP when using RFC3062 extensions is `{SSHA}`, this is `salted sha1`, it better than `md5` and of cause plain text, but it is not considered secure anymore.
+
+You can the the hashing algorithm by setting
+```toml
+password_hash = "SSHA1"
+```
+Available hashes are:
+* `SSHA` - OpenLDAP default (salted sha1)
+* `PBKDF2` - More secure and supported since OpenLDAP 2.4.40 (PBKDF2 with SHA512)
+* `Argon2` - Most secure algorithm of those three, supported since 2.4.50
+
+`PBKDF2` is only supported as a contrib module, so you might have to install the `openldap2-contrib` package on your LDAP server and configure `slapd.conf` like this: `moduleload pw-pbkdf2.la`
+
+`Argon2` was, like `PBKDF2`, provided as a contrib module until OpenLDAP 2.5.0. Starting with 2.5.0 it is a core module, but
+still needs to be configured like `moduleload argon2.la`
+
+### Set up SSL (LDAP over SSL)
+Regardless it is called SSL we will use TLS as SSL is deprecated.
+
+There two ways of securing LDAP: LDAP over TLS (STARTTLS) and LDAP over SSL (LDAPS).
+STARTTLS works by establishing an unsecured channel and securing it afterwards, this method is not supported!
+
+We support LDAPS, so your ldap server has to work in LDAPS mode and should be configured to support at least TLSv1.1, please note TLSv1.1 is deprecated and considered unsecure, so consider using at least TLSv1.2 and better TLS1.3.
+A simple LDAPS config for flaschengeist looks like this:
+
+```toml
+# Enable LDAPS
+use_ssl = true
+# Default port for LDAPS
+port = 636
+```
+
+If you use selfsigned certificates you can also specify your CA by setting
+```toml
+ca_cert = "/etc/ssl/my-ca.crt"
+```
+
+###