prole/docs/plans/prole-auth-samba-ad-cross-realm.md

prole.org auth — Samba AD cross-realm trust & keytab provisioning

Status: Infrastructure coded; operational steps pending. Owner: chrisfu

Closes Path B: Samba AD users on myrddin.prole.org → Kerberos SPNEGO → knoe-auth session.

---

Architecture recap

The in-cluster KDC runs the KNOE.LOCAL realm. myrddin.prole.org (10.0.0.3) runs Samba AD with realm PROLE.ORG. A bidirectional cross-realm trust lets a PROLE.ORG ticket-holder authenticate to any kerberized in-cluster service (HTTP/api.prole.org@KNOE.LOCAL etc.) without needing a second Kerberos account.

AD user on myrddin   →   TGT from PROLE.ORG KDC (myrddin:88)
                     →   cross-realm referral → KNOE.LOCAL KDC (in-cluster)
                     →   service ticket for HTTP/api.prole.org@KNOE.LOCAL
                     →   SPNEGO negotiation with knoe-auth
                     →   knoe_session cookie issued

The in-cluster ExternalName service prole-kerberos-ad-dc.knoe-system.svc.cluster.local:88 routes to myrddin.prole.org so the KDC container can find the PROLE.ORG KDC.

---

Step 1 — Create the inter-realm keys on the in-cluster KDC

init_kdc.sh provisions the MIT KDC side when PROLE_KDC_TRUST_REALM is set. Run this from within the cluster (or via kubectl exec into the KDC container):

# The shared trust password is in knoe-kdc-secrets/trust_shared_password
TRUST_SHARED_PW=$(kubectl -n knoe-system get secret knoe-kdc-secrets \
  -o jsonpath='{.data.trust_shared_password}' | base64 -d)

kubectl exec -n knoe-system deploy/knoe-auth -c kdc -- kadmin.local -q \
  "addprinc -pw ${TRUST_SHARED_PW} krbtgt/PROLE.ORG@KNOE.LOCAL"

kubectl exec -n knoe-system deploy/knoe-auth -c kdc -- kadmin.local -q \
  "addprinc -pw ${TRUST_SHARED_PW} krbtgt/KNOE.LOCAL@PROLE.ORG"

Both directions must exist. The KNOE.LOCAL → PROLE.ORG key is used when a PROLE.ORG principal requests a service ticket in KNOE.LOCAL (referral chain).

---

Step 2 — Create the reciprocal trust account on myrddin (Samba side)

SSH to myrddin.prole.org as Administrator and run:

# Create the outbound trust principal that KNOE.LOCAL will use
sudo samba-tool user create krbtgt_KNOEDOTLOCAL --random-password

# Set the inter-realm key to the SAME shared password used in Step 1
sudo samba-tool user setpassword krbtgt_KNOEDOTLOCAL --newpassword="${TRUST_SHARED_PW}"

# Disable password expiry for the trust account
sudo samba-tool user setexpiry krbtgt_KNOEDOTLOCAL --noexpiry

# Create the one-way trust entry (PROLE.ORG trusts KNOE.LOCAL)
sudo samba-tool domain trust create KNOE.LOCAL \
  --type=external \
  --direction=incoming \
  --password="${TRUST_SHARED_PW}"

Note: KNOE.LOCAL must be resolvable from myrddin. Either add a DNS forwarder for the KNOE.LOCAL domain pointing at the in-cluster KDC service IP, or add a hosts entry.

---

Step 3 — Extract the HTTP service keytab

The knoe-auth pod needs HTTP/api.prole.org@PROLE.ORG to accept SPNEGO from PROLE.ORG browsers.

# Option A — generate keytab on myrddin (if the principal lives in PROLE.ORG)
ssh myrddin.prole.org "sudo samba-tool user create HTTP-api-prole-org --random-password && \
  sudo samba-tool spn add HTTP/api.prole.org HTTP-api-prole-org && \
  sudo samba-tool domain exportkeytab /tmp/http-api.keytab --principal=HTTP/api.prole.org"
scp myrddin.prole.org:/tmp/http-api.keytab ./http.keytab

# Option B — generate on the in-cluster KDC (principal in KNOE.LOCAL)
kubectl exec -n knoe-system deploy/knoe-auth -c kdc -- kadmin.local -q \
  "addprinc -randkey HTTP/api.prole.org@KNOE.LOCAL"
kubectl exec -n knoe-system deploy/knoe-auth -c kdc -- kadmin.local -q \
  "ktadd -k /tmp/http.keytab HTTP/api.prole.org@KNOE.LOCAL"
kubectl cp knoe-system/$(kubectl get pod -n knoe-system -l app=knoe-auth -o name | head -1 | cut -d/ -f2):/tmp/http.keytab ./http.keytab

Choose Option A if clients authenticate as user@PROLE.ORG — the service principal must match the realm clients target. Use Option B if you want KNOE.LOCAL to be authoritative.

Store the keytab in the k8s secret:

kubectl create secret generic knoe-auth-http-keytab \
  --namespace knoe-system \
  --from-file=http.keytab=./http.keytab \
  --dry-run=client -o yaml | kubectl apply -f -

The deployment mounts this at /etc/knoe-auth/http.keytab (already wired in knoe-auth-deployment.yaml).

---

Step 4 — Verify trust end-to-end

From a domain-joined Windows or Linux machine in PROLE.ORG:

# Linux (kinit from PROLE.ORG)
kinit user@PROLE.ORG
kvno HTTP/api.prole.org@KNOE.LOCAL   # should succeed via cross-realm referral

# Test SPNEGO login
curl -v --negotiate -u : https://api.prole.org/auth/spnego
# Expect: 302 redirect with knoe_session cookie

---

Step 5 — AD group sync (future work)

AD group membership → knoe.access_grant rows is not yet implemented. Current behavior:

• Samba AD users get a baseline knoe_session with no extra groups.
• Admin rights are granted only to usernames listed in PROLE_AUTH_ADMIN_PRINCIPALS.

To grant admin access to an AD user before group sync is built:

kubectl -n knoe-system set env deploy/knoe-auth \
  PROLE_AUTH_ADMIN_PRINCIPALS="admin,<samba-username>"

---

Related files

File	Purpose
deploy/opentofu/k3s/manifests/knoe/prole-kerberos-ad-dc-svc.yaml	ExternalName service → myrddin.prole.org:88
deploy/opentofu/k3s/manifests/knoe/knoe-kdc-secrets.example.yaml	trust_shared_password lives here
etc/init_kdc.sh	Automates Step 1 when PROLE_KDC_TRUST_* env vars are set
deploy/opentofu/k3s/manifests/knoe/knoe-auth-http-keytab-secret.example.yaml	HTTP service keytab secret template