example_configs: add PAM configuration guide

README.md

@@ -48,6 +48,7 @@
 - [Client configuration](#client-configuration)
   - [Compatible services](#compatible-services)
   - [General configuration guide](#general-configuration-guide)
+  - [Integration with OS's](#integration-with-os-s)
   - [Sample client configurations](#sample-client-configurations)
   - [Incompatible services](#incompatible-services)
 - [Migrating from SQLite](#migrating-from-sqlite)
@@ -538,6 +539,13 @@ admin rights in the Web UI. Most LDAP integrations should instead use a user in
 the `lldap_strict_readonly` or `lldap_password_manager` group, to avoid granting full
 administration access to many services.
 
+### Integration with OS's
+
+Integration with Linux accounts is possible, through PAM and nslcd. See [PAM
+configuration guide](example_configs/pam/README.md).
+
+Integration with Windows (e.g. Samba) is WIP.
+
 ### Sample client configurations
 
 Some specific clients have been tested to work and come with sample

example_configs/pam/README.md

@@ -0,0 +1,89 @@
+# Configure lldap
+
+You MUST use LDAPS. You MUST NOT use plain ldap. Even over a private network
+this costs you nearly nothing, and passwords will be sent in PLAIN TEXT without
+it.
+
+```toml
+[ldaps_options]
+enabled=true
+port=6360
+cert_file="cert.pem"
+key_file="key.pem"
+```
+
+You can generate an SSL certificate for it with the following command. The
+`subjectAltName` is REQUIRED. Make sure all domains are listed there, even your
+`CN`.
+
+```sh
+openssl req -x509 -nodes -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 36500 -nodes -subj "/CN=lldap.example.net" -addext "subjectAltName = DNS:lldap.example.net"
+```
+
+# Install the client packages.
+
+This guide used `libnss-ldapd` (which is different from `libnss-ldap`).
+
+PURGE the following ubuntu packages: `libnss-ldap`, `libpam-ldap`
+
+Install the following ubuntu packages: `libnss-ldapd`, `nslcd`, `nscd`, `libpam-ldapd`
+
+# Configure the client's `nslcd` settings.
+
+Edit `/etc/nslcd.conf`. Use the [provided template](./nslcd.conf).
+
+You will need to set `tls_cacertfile` to a copy of the public portion of your
+LDAPS certificate, which must be available on the client. This is used to
+verify the LDAPS server identity.
+
+You will need to add the `binddn` and `bindpw` settings.
+
+The provided implementation uses custom attributes to mark users and groups
+that should be included in the system (for instance, you don't want LDAP
+accounts of other services to have a matching unix user).
+
+For users, you need to add an (integer) `is-unix-user` attribute, set manually
+to 1 for the users you want to enable. This could also be implemented as a
+group membership.
+
+For groups, you need an (integer) `is-unix-group` attribute, similarly set to 1
+(this cannot be replaced by group membership until LLDAP supports nested group
+memberships).
+
+If you want to change this representation, update the `filter passwd` and
+`filter group` accordingly.
+
+You should check whether you need to edit the `pam_authz_search` setting. This
+is used after authentication, at the PAM `account` stage, to determine whether
+the user should be allowed to log in. If someone is an LDAP user, even if they
+use an SSH key to log in, they must still pass this check. The provided example
+will check for membership of a group named `YOUR_LOGIN_GROUP_FOR_THIS_MACHINE`.
+
+You should review the `map` settings. These contain custom attributes that you
+will need to add to lldap and set on your users.
+
+# Configure the client OS.
+
+Ensure the `nslcd` and `nscd` services are installed and running. `nslcd`
+provides LDAP NSS service. `nscd` provides caching for NSS databased. You want
+the caching.
+
+```
+systemctl enable --now nslcd nscd
+```
+
+Configure PAM to create the home directory for LDAP users automatically at
+first login.
+
+```
+pam-auth-update --enable mkhomedir
+```
+
+Edit /etc/nsswitch.conf and add "ldap" to the END of the "passwd" and "group"
+lines.
+
+You're done!
+
+## Clearing nscd caches.
+
+If you want to manually clear nscd's caches, run `nscd -i passwd; nscd -i group`.

example_configs/pam/nslcd.conf

@@ -0,0 +1,59 @@
+# /etc/nslcd.conf
+# nslcd configuration file. See nslcd.conf(5)
+# for details.
+
+# The user and group nslcd should run as.
+uid nslcd
+gid nslcd
+
+# The location at which the LDAP server(s) should be reachable.
+uri ldaps://lldap.example.net:6360/
+
+# The search base that will be used for all queries.
+base dc=example,dc=net
+
+# The LDAP protocol version to use.
+#ldap_version 3
+
+# The DN to bind with for normal lookups.
+#binddn cn=...,ou=people,dc=example,dc=com
+#bindpw ...
+
+# The DN used for password modifications by root.
+#rootpwmoddn cn=admin,dc=example,dc=com
+
+# SSL options
+#ssl off
+tls_reqcert demand
+tls_cacertfile /etc/cert-lldap.example.com.pem
+
+# The search scope.
+#scope sub
+
+reconnect_invalidate passwd group
+nss_initgroups_ignoreusers ALLLOCAL
+
+# Do you have users/groups that aren't for linux?  These filters determine which user/group objects are used.
+filter passwd (&(objectClass=posixAccount)(is-unix-user=1))
+filter group (&(objectClass=groupOfUniqueNames)(is-unix-group=1))
+
+# This check is done AFTER authentication, in the pam "account" stage.
+# Regardless of if they used a LDAP password, or an SSH key, if they're an LDAP user, they have to pass this check.
+pam_authz_search (&(objectClass=posixAccount)(is-unix-user=1)(unix-username=$username)(memberOf=cn=YOUR_LOGIN_GROUP_FOR_THIS_MACHINE,ou=groups,dc=example,dc=com))
+
+
+map passwd uid unix-username
+map passwd uidNumber unix-uid
+map passwd gidNumber unix-uid
+map passwd gecos unix-username
+map passwd homeDirectory "/home/${unix-username}"
+map passwd loginShell unix-shell
+
+map group gidNumber unix-gid
+map group memberUid member
+
+nss_min_uid 1000
+
+pam_password_prohibit_message "Please use the forgot password link on https://lldap.example.com/ to change your password."
+
+