home-ops: Skill for Claude Code

Authentik SSO and the terraform/authentik OpenTofu stack

Relocated verbatim from AGENTS.md on 2026-09-01 so it loads only when this subsystem is in play. The text below is unchanged; only line breaks were inserted. AGENTS.md keeps a one-sentence pointer. Add new findings here or to the owning document, not back into AGENTS.md - see its "Maintaining this file" section for the rule.

• terraform/authentik/ HAS been applied and now holds live state (first apply 2026-08-27: 9 imported, 4 added, 4 changed, 0 destroyed; second apply 2026-08-28 landed litellm_role, the LiteLLM-only invalidation flow, and the provider wiring; third apply the same day set grant_types = ["authorization_code"] on the created LiteLLM provider after post-merge SSO verification found Authentik rejecting authorize). It owns the remaining adopted apps/providers (coder, pg-admin, echo ExtAuth) plus the full LiteLLM SSO surface. open-webui was intentionally deleted from Authentik and removed from the stack (tofu state rm). A fresh tofu plan is empty (-detailed-exitcode 0) on the READ-ONLY token, and scopes_supported includes litellm_role so SSO users land as proxy_admin. Two credentials exist, both least-privilege service accounts minted through ak shell: tofu-readonly (plan) and tofu-writer (apply; fourteen add/change permissions including model-level change_flow, no delete on anything, proven by create-then-delete 201/403 and a scope-mapping POST 201). AUTHENTIK_APPLY_TOKEN is deliberately ABSENT from 1Password so a stray tofu apply fails closed. The state backend is NOT reachable through the gateway: OpenTofu's aws-sdk-go-v2 signs accept-encoding/amz-sdk-*, Envoy rewrites one of them, and RGW returns SignatureDoesNotMatch - boto3 and minio-go sign none of those and keep working, so VolSync never noticed. Endpoint is env-supplied via AWS_ENDPOINT_URL_S3 (backend.tofu omits endpoints so the env var wins): local secrets.vals.yaml uses http://127.0.0.1:18081 after kubectl -n rook-ceph port-forward svc/rook-ceph-rgw-ceph-objectstore 18081:80; CI secrets-ci.vals.yaml uses the in-cluster Service DNS because the ARC runner cannot port-forward. Runbook: docs/authentik/terraform.md.

• Four OpenTofu/Authentik traps, none of which tofu validate can catch.

(0) grant_types is optional+computed, so omitting it is right for an IMPORTED provider (the read adopts the live set) and wrong for a CREATED one: it writes grant_types = {} and Authentik rejects every authorize with invalid_request / Invalid grant_type for provider. Same shape as client_secret, opposite answer, and a clean plan plus -detailed-exitcode 0 both hold while login is impossible.

(1) authentik_flow's terraform id is the slug, not the UUID, so a provider's invalidation_flow set from .id fails with 400 "<slug>" is not a valid UUID - use .uuid (same for authentik_flow_stage_binding.target).

(2) The S3 backend fails open to real AWS: backend.tofu omits endpoints so AWS_ENDPOINT_URL_S3 can point at the RGW port-forward, and if that variable is unset the SDK silently talks to genuine AWS S3 rather than erroring.

(3) The write role now holds model-level change_flow, which reaches every flow including default-authentication-flow, so verify each apply against a before/after snapshot of all flows and their stage bindings taken from the database, not against terraform's own summary. Evidence and commands: docs/authentik/terraform.md.

• terraform/ is not Flux-reconciled and nothing applies it automatically. It holds OpenTofu stacks for configuration that lives inside an application's own API, where a chart cannot reach. Today that is terraform/authentik/ only. .github/workflows/validate.yaml's terraform job (scripts/ci/tofu-validate.sh) stays a pure schema check: tofu fmt -check plus tofu validate with -backend=false, no credentials. .github/workflows/terraform-diff.yaml is separate and does carry credentials: on every same-repo PR touching terraform/** it runs a real tofu init/tofu plan -lock=false against a stack's live state backend (and, for authentik, the live read-only Authentik API) and posts the plan as a PR comment, whenever that stack provides its own secrets-ci.vals.yaml (a ref+onepasswordconnect://-scheme mirror of its secrets.vals.yaml, resolved via the in-cluster 1Password Connect since CI has no interactive op session) - a stack without one gets schema-only checks. This is a deliberate, captain-approved design (2026-08-27) that consciously reverses an earlier "CI can never reach the live instance" boundary; it never touches tofu apply, which against the Authentik stack changes the cluster's live SSO, including the ExtAuth that kubernetes/apps/base/network/echo/app/securitypolicy.yaml and kubernetes/apps/base/ai/agentgateway/app/policies/authentik-policy.yaml route every request on their listeners through, and remains an explicitly approved operator action, never a follow-on to a green PR. Runbook, inventory, the CI credential and its vault-wide read scope, and the apply approval gate: docs/authentik/terraform.md (see section 9 for CI). Conventions: terraform/tofu.md.