From a4dcab9cf83411023bc578674a834b321136c491 Mon Sep 17 00:00:00 2001 From: Slawomir Koszewski Date: Sat, 16 May 2026 18:56:21 +0200 Subject: [PATCH] refactor: improve formatting and clarity in README sections for kadmin commands and SSH configuration --- README.md | 120 ++++++++++++++++-------------------------------------- 1 file changed, 35 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 31b53a2..4130d98 100644 --- a/README.md +++ b/README.md @@ -71,11 +71,11 @@ The `kerberos_data` volume (`/var/lib/krb5kdc`) holds the realm database, config ## Ports -| Port | Protocol | Service | -|---|---|---| -| 88 | TCP/UDP | KDC (ticket granting) | -| 464 | TCP/UDP | kpasswd (password changes) | -| 749 | TCP | kadmin (remote administration) | +| Port | Protocol | Service | +|-----:|----------|--------------------------------| +| 88 | TCP/UDP | KDC (ticket granting) | +| 464 | TCP/UDP | kpasswd (password changes) | +| 749 | TCP | kadmin (remote administration) | ## Client configuration @@ -110,7 +110,7 @@ Create `/etc/krb5.conf`: ``` ```bash -kinit user@EXAMPLE.ORG # obtain a ticket +kinit user@EXAMPLE.ORG # obtain a ticket klist # verify kdestroy # release ``` @@ -184,76 +184,39 @@ kadmin -p admin@REALM -k -t /path/to/admin.keytab All commands below work identically in `kadmin` — replace `kadmin.local` with `kadmin -p admin@REALM`. -### Local (kadmin.local) +### Local -Exec into the running container — no authentication required, bypasses `kadmind` entirely: - -```bash -container exec -it kerberos bash -``` +Exec into the running container — no authentication required, bypasses `kadmind` entirely ### Principals -```bash -# List all principals (supports glob: "user*") -kadmin.local -q "listprincs" +Run `kadmin.local` inside the container to launch the **kadmin** administration shell. Type `?` for help. You can also run one-off commands directly from the shell using `kadmin.local -q "command"`. -# Inspect a principal -kadmin.local -q "getprinc user@REALM" +Useful commands: -# Add a user principal -kadmin.local -q "addprinc user@REALM" - -# Add a service principal (random key, no password) -kadmin.local -q "addprinc -randkey service/host.example.org@REALM" - -# Change password -kadmin.local -q "cpw -pw newpassword user@REALM" - -# Randomise key (invalidates existing tickets and keytabs) -kadmin.local -q "cpw -randkey service/host.example.org@REALM" - -# Set expiry -kadmin.local -q "modprinc -expire '2027-01-01' user@REALM" - -# Unlock after failed authentication lockout -kadmin.local -q "modprinc -unlock user@REALM" - -# Delete a principal -kadmin.local -q "delprinc user@REALM" -``` +- `listprincs` - List all principals (supports glob: "user*") +- `getprinc user@REALM` - Inspect a principal +- `addprinc user@REALM` - Add a user principal +- `addprinc -randkey service/host.example.org@REALM` - Add a service principal (random key, no password) +- `cpw -pw newpassword user@REALM` - Change password +- `cpw -randkey service/host.example.org@REALM` - Randomise key (invalidates existing tickets and keytabs) +- `modprinc -expire '2027-01-01' user@REALM` - Set expiry +- `modprinc -unlock user@REALM` - Unlock after failed authentication lockout +- `delprinc user@REALM` - Delete a principal ### Keytabs -```bash -# Extract keytab (randomises the principal's key) -kadmin.local -q "ktadd -k /tmp/service.keytab service/host.example.org@REALM" - -# Extract without randomising key (-norandkey, preserves existing tickets) -kadmin.local -q "ktadd -k /tmp/service.keytab -norandkey service/host.example.org@REALM" - -# Remove keytab entries for a principal -kadmin.local -q "ktremove -k /tmp/service.keytab service/host.example.org@REALM all" -``` +- `ktadd -k /tmp/service.keytab service/host.example.org@REALM` - Extract keytab (randomises the principal's key) +- `ktadd -k /tmp/service.keytab -norandkey service/host.example.org@REALM` - Extract without randomising key (preserves existing tickets) +- `ktremove -k /tmp/service.keytab service/host.example.org@REALM all` - Remove keytab entries for a principal ### Password policies -```bash -# Create a policy -kadmin.local -q "addpol -minlength 12 -minclasses 3 -maxlife '90 days' -maxfailure 5 default" - -# Assign policy to a principal -kadmin.local -q "modprinc -policy default user@REALM" - -# Inspect a policy -kadmin.local -q "getpol default" - -# List policies -kadmin.local -q "listpols" - -# Delete a policy (fails if any principal uses it) -kadmin.local -q "delpol default" -``` +- `addpol -minlength 12 -minclasses 3 -maxlife '90 days' -maxfailure 5 default` - Create a policy +- `modprinc -policy default user@REALM` - Assign policy to a principal +- `getpol default` - Inspect a policy +- `listpols` - List policies +- `delpol default` - Delete a policy (fails if any principal uses it) ## SSH server configuration @@ -263,12 +226,12 @@ SSH uses the `host/` service principal. The FQDN must match the result of forwar Create the host principal and extract the keytab to the default location (run as `root` on the SSH server — the keytab is written to `/etc/krb5.keytab`, mode `0600`): -```bash -sudo kadmin -p admin@REALM -q "addprinc -randkey host/ssh-server.example.org@REALM" -sudo kadmin -p admin@REALM -q "ktadd host/ssh-server.example.org@REALM" -``` +Authenticate as Kerberos admin principal and run the following **kadmin** commands: -Add to `/etc/ssh/sshd_config` (requires `root`): +- `addprinc -randkey host/ssh-server.example.org@REALM` - creates the principal with a random key (no password) +- `ktadd -k /tmp/krb5.keytab host/ssh-server.example.org@REALM` - extracts the keytab + +Add to `/etc/ssh/sshd_config`: ``` GSSAPIAuthentication yes @@ -276,20 +239,7 @@ GSSAPICleanupCredentials yes GSSAPIStrictAcceptorCheck yes ``` -`GSSAPIStrictAcceptorCheck` verifies the server's identity against the keytab — keep it enabled. Reload sshd (requires `root`): - -```bash -sudo systemctl reload sshd -``` - -**Login authorisation** — by default a principal is granted access if its realm matches `default_realm` and its name matches the local account. To grant additional principals access to an account, list them in `~/.k5login` (one principal per line): - -``` -alice@EXAMPLE.ORG -alice/admin@EXAMPLE.ORG -``` - -If `.k5login` is present it is authoritative — unlisted principals are denied even if the name matches. To make it additive rather than restrictive, set in `krb5.conf`: +`GSSAPIStrictAcceptorCheck` verifies the server's identity against the keytab — keep it enabled. Reload sshd: ```ini [libdefaults] @@ -301,7 +251,7 @@ If `.k5login` is present it is authoritative — unlisted principals are denied SSH will prefer public key authentication by default even when GSSAPI is available. To enforce Kerberos: ```bash -ssh -o GSSAPIAuthentication=yes -o PreferredAuthentications=gssapi-with-mic user@ssh-server.example.org +ssh -o GSSAPIAuthentication=yes -o GSSAPIDelegateCredentials=yes user@ssh-server.example.org ``` To make this permanent for a host in `~/.ssh/config`: @@ -309,7 +259,7 @@ To make this permanent for a host in `~/.ssh/config`: ``` Host ssh-server.example.org GSSAPIAuthentication yes - PreferredAuthentications gssapi-with-mic + GSSAPIDelegateCredentials yes ``` On Windows (KfW) and macOS the same `ssh` flags apply. macOS additionally accepts `-K` as a shorthand for `GSSAPIAuthentication=yes`.