docs: document detect_cached_ticket feature (#920)

Missed adding this documentation in the original PR. Fixes UDENG-2191
ubuntu · Feb 21, 2024 · d0547f2 · d0547f2
2 parents 498df8f + 3ae54c1
commit d0547f2
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt
@@ -17,6 +17,7 @@ JSON
 Juju
 Kubernetes
 Kubeflow
+libkrb
 Makefile
 MyST
 namespace

diff --git a/docs/how-to/set-up-adsys.md b/docs/how-to/set-up-adsys.md
@@ -34,3 +34,16 @@ sudo pam-auth-update --enable mkhomedir
 ```
 
 Options such as the home directory path template, shell and others can be tweaked in `/etc/samba/smb.conf` and are documented in the [`smb.conf(5)`](https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html) man page.
+
+## Kerberos
+
+ADSys relies on the configured AD backend (e.g. SSSD) to export the `KRB5CCNAME` environment variable pointing to a valid Kerberos ticket cache when a domain user performs authentication.
+
+If for any reason the backend doesn't export the variable but _does_ initialize a ticket cache in the [default path](https://web.mit.edu/kerberos/krb5-1.12/doc/basic/ccache_def.html#default-ccache-name), ADSys can be configured to infer the path to the ticket cache (via the libkrb5 API) and export it as the `KRB5CCNAME` variable during both authentication and runs of `adsysctl update` for the current domain user.
+
+To opt into this functionality, the following must be added to `/etc/adsys.yaml`:
+```yaml
+detect_cached_ticket: true
+```
+
+With this setting active, ADSys attempts to determine and export the path to the ticket cache. To avoid unexpected behaviors like rejecting authentication for non-domain users, no action is taken if the path returned by the libkrb5 API does not exist on disk.