koszewscy/kerberos
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: improve formatting and clarity in README sections for kadmin commands and SSH configuration

Browse Source
This commit is contained in:
Sławek Koszewski
2026-05-16 18:56:21 +02:00
parent 946f37af52
commit a4dcab9cf8
1 changed files with 35 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+35 -85
View File
@@ -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`.