Skip to content
fzymgc-house Cluster Docs

Authenticate Miniflux with native Authentik OIDC, not forward-auth

Date: 2026-06-12 Status: Accepted Decision: hl-27xf Deciders: Sean Brandt

Context

Section titled “Context”

Miniflux must be authenticated before exposure at miniflux.fzymgc.house. The cluster already runs Authentik and supports both a forward-auth outpost pattern and native per-application OIDC. The choice affects the Authentik IaC surface in tf/authentik/, the outpost runtime dependency, and break-glass access during an Authentik outage.

Decision

Section titled “Decision”

Use Miniflux’s native OAUTH2_PROVIDER=oidc against an Authentik OIDC provider provisioned in tf/authentik/. Retain a local admin account as break-glass, independent of OIDC availability.

Rationale

Section titled “Rationale”
  • Consistent with the existing Authentik IaC pattern already used by other applications in tf/authentik/ (e.g. karakeep.tf).
  • Eliminates the outpost as a runtime dependency — Miniflux stays reachable for break-glass admin during Authentik degradation.
  • OAUTH2_USER_CREATION=1 removes manual account provisioning; first OIDC login is self-service.
  • The OIDC client secret is handled by ExternalSecret + Vault, the same rotation path as every other app secret.

Alternatives Considered

Section titled “Alternatives Considered”

Miniflux native OIDC (chosen) — Strengths: matches the established tf/authentik IaC pattern; no outpost dependency; auto-provisions accounts; local admin break-glass survives an OIDC outage. Weaknesses: requires an Authentik provider+application resource and a Vault-backed OIDC client secret via ExternalSecret.

Authentik forward-auth outpost (rejected) — Strengths: uniform auth at the ingress; no per-app OIDC config. Weaknesses: the outpost becomes a hard runtime dependency (outpost down = no access, even break-glass); adds an ingress annotation surface to maintain.

Consequences

Section titled “Consequences”

Positive: No outpost deployment/upgrade lifecycle for this app; break-glass local admin is independent of Authentik/OIDC availability; Terraform follows the established pattern.

Negative: One more secret (the OIDC client secret) in Vault + ExternalSecret; Authentik’s discovery endpoint needs a trailing slash (slug base path) — a subtle misconfiguration risk.

Neutral: Migration to forward-auth remains possible later without data loss if the operational model changes.