basic documentation on how the SSO currently works

content/auth.md

@@ -0,0 +1,43 @@
++++
+title = "Authentication"
+categories = [ "services", "lxc", "ldap" ]
++++
+
+Our SSO is currently handled via keycloak, though the user accounts themselves
+are stored in LDAP; keycloak just fetches them from there.
+
+Both LDAP and Keycloak are running in lxc containers containing debian systems
+rather than on nix directly (though they both run on `parsons`).
+
+## LDAP
+
+LDAP stores all user accounts except those that can admininster the keycloak
+master realm.
+
+It should be reachable from within keycloak's container under `10.1.2.103`; if
+it is not, keycloak will return confusingly generic errors to users.
+
+## Keycloak
+
+Keycloak provides other services with SSO.
+
+An admin password for the master realm should be available in [vaultwarden](pw.hacc.space);
+use it to log in to the [admin console](https://auth.infra4future.de/auth/admin/master/console/).
+
+Inside its lxc container, keycloak lives under `/opt/keycloak` and is not managed
+by any kind of package manager.
+
+Keycloak does not write any logs to systemd; either check the logs in the admin
+console or take a look at `/opt/keycloak/standalone/log/server.log` within the
+lxc container. Logs are rotated daily, and apparently we keep all of them, forever.
+
+User groups are sometimes fiddly, and currently synced with nextcloud via a
+script `/opt/ldap-provision-update.sh` that systemd runs regularly.
+
+## Useful commands
+ - login to a container as root with a usable shell
+   `lxc-attach -n keycloak -- /usr/bin/sudo -i`
+ - restarting the keycloak and ldap containers
+   `lxc-stop -n keycloak && lxc-start -n keycloak`
+ - restarting their network bridge:
+   `systemctl restart lxcbr0-netdev.services`