Authentik: know when the front door is about to shut

New Authentik integration (read-only, every 5 minutes): version, workers,
outposts and their health, certificates and API tokens that expire, failed
sign-ins and configuration errors. Monitoring -> Authentik page.

Alerts: an outpost that serves apps has gone quiet (critical), certificate or
token about to run out (critical close to it), no worker, failed sign-ins,
configuration errors. Held by maintenance, held when unreadable, in /metrics.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-24 22:09:38 +02:00
1 parent 0146eb8bca
commit aebe98bf15
33 files changed
+8050 -7

No files matched your search

+5 -2
View File
@@ -76,6 +76,7 @@ const SOURCES: Record<string, { label: string; link: string }> = {
slo: { label: "Service level", link: "/service-levels" },
duplicati: { label: "Duplicati", link: "/duplicati" },
jellyfin: { label: "Jellyfin", link: "/jellyfin" },
authentik: { label: "Authentik", link: "/authentik" },
secrets: { label: "Secrets", link: "/secrets" },
domains: { label: "Domains", link: "/dns?view=domains" },
endpoint: { label: "Endpoint", link: "/endpoints" },
@@ -114,6 +115,8 @@ function originOfConditionKey(key: string): { type: string; id: number | null; c
if (m) return { type: "dockhand", id: Number(m[1]), category: "services" };
m = /^duplicati-(?:failed|stale):(\d+)/.exec(key);
if (m) return { type: "duplicati", id: Number(m[1]), category: "backup" };
m = /^authentik-(?:outpost|outpost-version|cert|token|worker|logins|errors):(\d+)/.exec(key);
if (m) return { type: "authentik", id: Number(m[1]), category: /^authentik-(?:cert|token):/.test(key) ? "expiry" : /^authentik-(?:outpost|worker)/.test(key) ? "services" : "monitoring" };
m = /^jellyfin-(?:restart|task|logins):(\d+)/.exec(key);
if (m) return { type: "jellyfin", id: Number(m[1]), category: key.startsWith("jellyfin-task") ? "automation" : "monitoring" };
return { type: "server", id: null, category: "disk" };
@@ -238,7 +241,7 @@ export async function collectAlerts(): Promise<AlertsReport> {
type: origin.type,
message: c.message,
key: c.key,
link: origin.type === "server" && origin.id !== null ? `/servers/${origin.id}${/^(failed-units|smart|zfs):/.test(c.key) ? "?view=health" : c.key.startsWith("new-port:") ? "?view=network" : c.key.startsWith("rule:") || c.key.startsWith("baseline:") ? "?view=history" : ""}` : origin.type === "unifi" ? "/network/devices" : origin.type === "ups" ? "/ups" : origin.type === "slo" ? "/service-levels" : origin.type === "dockhand" ? "/docker" : origin.type === "duplicati" ? "/duplicati" : origin.type === "jellyfin" ? "/jellyfin" : undefined,
link: origin.type === "server" && origin.id !== null ? `/servers/${origin.id}${/^(failed-units|smart|zfs):/.test(c.key) ? "?view=health" : c.key.startsWith("new-port:") ? "?view=network" : c.key.startsWith("rule:") || c.key.startsWith("baseline:") ? "?view=history" : ""}` : origin.type === "unifi" ? "/network/devices" : origin.type === "ups" ? "/ups" : origin.type === "slo" ? "/service-levels" : origin.type === "dockhand" ? "/docker" : origin.type === "duplicati" ? "/duplicati" : origin.type === "jellyfin" ? "/jellyfin" : origin.type === "authentik" ? "/authentik" : undefined,
silenced: subject !== null && subjects.has(subject), target: targetOfSubject(subject),
});
}
@@ -248,7 +251,7 @@ export async function collectAlerts(): Promise<AlertsReport> {
if (held.has("slo")) cannotCheck("Service-level targets", "couldn't be judged — see the server log", "Server and storage health");
if (held.has("server:baseline")) cannotCheck("What is usual for the time", "couldn't be judged — see the server log", "Server and storage health");
for (const h of held) {
const m = /^(proxmox|synology|unifi|ups|dockhand|jellyfin):(\d+)(?::(.+))?$/.exec(h);
const m = /^(proxmox|synology|unifi|ups|dockhand|jellyfin|authentik):(\d+)(?::(.+))?$/.exec(h);
if (!m || (m[3] && held.has(`${m[1]}:${m[2]}`))) continue;
const row = intById.get(Number(m[2]));
cannotCheck(`${SOURCES[m[1]].label} “${row?.name ?? `#${m[2]}`}”${m[3] ? ` (node ${m[3]})` : ""}`, "couldn't be read — see the Diagnostic Log", "Server and storage health");
+189
View File
@@ -0,0 +1,189 @@
/**
* Keeps what Authentik says up to date: every five minutes each Authentik integration is read (its version, whether a worker is connected, how each outpost is, which certificates
* and tokens run out, how many sign-ins and flows failed) and the state is stored. Pages and alerts are built from what is stored, so none of them talks to Authentik.
*
* Authentik is the front door to everything else, so what is worth knowing early is what would shut it: a proxy outpost that stopped reporting (the apps behind it stop letting
* anyone in), a certificate or an API token that is about to run out, no worker (mail and outpost changes stop), and somebody guessing passwords.
*/
import { and, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { authentikState, integrations } from "../db/schema.js";
import { createAuthentikAdapter, type AuthentikCertificate, type AuthentikOutpost, type AuthentikRead, type AuthentikToken } from "../integrations/authentik/adapter.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
export const SYNC_INTERVAL_MS = 5 * 60_000;
/** After this long without a good read, what is stored is no longer believed. */
export const STALE_AFTER_MS = 20 * 60_000;
/** This many failed sign-ins in a day is a warning. */
export const FAILED_LOGINS_WARN = 20;
/** This many configuration errors (a flow or stage that is set up wrongly) in a day is a warning. */
export const CONFIG_ERRORS_WARN = 3;
/** A certificate or a token this close to running out is a warning; closer still, critical. */
export const CERT_WARN_DAYS = 14;
export const CERT_CRITICAL_DAYS = 3;
export const TOKEN_WARN_DAYS = 7;
export const TOKEN_CRITICAL_DAYS = 2;
const STATUS_FLAG = "authentikSync";
const DAY_MS = 86_400_000;
export interface AuthentikSyncStatus {
/** The last read that worked (kept when a later one failed). */
at: string;
ok: boolean;
error: string | null;
}
async function readStatuses(): Promise<Record<string, AuthentikSyncStatus>> {
try {
const raw = await getInternalFlag(STATUS_FLAG);
return raw ? (JSON.parse(raw) as Record<string, AuthentikSyncStatus>) : {};
} catch {
return {};
}
}
export async function authentikSyncStatuses(): Promise<Record<number, AuthentikSyncStatus>> {
return Object.fromEntries(Object.entries(await readStatuses()).map(([k, v]) => [Number(k), v]));
}
export const isAuthentikFresh = (status: AuthentikSyncStatus | undefined, nowMs: number) => !!status && status.ok && nowMs - Date.parse(status.at) <= STALE_AFTER_MS;
export type StateRow = typeof authentikState.$inferSelect;
const parse = <T>(text: string): T[] => {
try {
const v = JSON.parse(text);
return Array.isArray(v) ? (v as T[]) : [];
} catch {
return [];
}
};
export const outpostsOf = (row: Pick<StateRow, "outposts">) => parse<AuthentikOutpost>(row.outposts);
export const certificatesOf = (row: Pick<StateRow, "certificates">) => parse<AuthentikCertificate>(row.certificates);
export const tokensOf = (row: Pick<StateRow, "tokens">) => parse<AuthentikToken>(row.tokens);
/** Writes down one read, replacing the last. */
export async function storeRead(integrationId: number, r: AuthentikRead, now: Date = new Date()): Promise<void> {
const values = {
version: r.version,
latestVersion: r.latestVersion,
outdated: r.outdated,
workers: r.workers,
outposts: JSON.stringify(r.outposts),
certificates: JSON.stringify(r.certificates),
tokens: JSON.stringify(r.tokens),
failedLogins24h: r.failedLogins24h,
configErrors24h: r.configErrors24h,
lastConfigError: r.lastConfigError,
updatedAt: now.toISOString(),
};
await db.insert(authentikState).values({ integrationId, ...values }).onConflictDoUpdate({ target: authentikState.integrationId, set: values });
}
/** Reads one Authentik and stores it. Never throws: how it went is the answer, and what was stored is left alone when it failed. */
export async function syncAuthentik(integrationId: number, now: Date = new Date(), read?: (config: Record<string, unknown>) => Promise<AuthentikRead>): Promise<AuthentikSyncStatus> {
let status: AuthentikSyncStatus;
try {
const loaded = await loadIntegrationConfig(integrationId);
if (!loaded || loaded.integration.type !== "authentik") throw new Error("not an Authentik integration");
const result = await (read ? read(loaded.config) : createAuthentikAdapter(loaded.config as never).read(now));
await storeRead(integrationId, result, now);
status = { at: now.toISOString(), ok: true, error: null };
} catch (err) {
const previous = (await readStatuses())[String(integrationId)];
status = { at: previous?.at ?? now.toISOString(), ok: false, error: err instanceof Error ? err.message : String(err) };
console.error(`[authentik] couldn't read integration ${integrationId}:`, status.error);
}
try {
const all = await readStatuses();
all[String(integrationId)] = status;
await setInternalFlag(STATUS_FLAG, JSON.stringify(all));
} catch (err) {
console.error("[authentik] couldn't record the result:", err);
}
return status;
}
export async function syncAllAuthentik(now: Date = new Date()): Promise<Record<number, AuthentikSyncStatus>> {
const rows = await db.select({ id: integrations.id }).from(integrations).where(and(eq(integrations.type, "authentik"), eq(integrations.enabled, true)));
const out: Record<number, AuthentikSyncStatus> = {};
for (const r of rows) out[r.id] = await syncAuthentik(r.id, now);
return out;
}
export async function forgetAuthentik(integrationId: number): Promise<void> {
const all = await readStatuses();
if (String(integrationId) in all) {
delete all[String(integrationId)];
await setInternalFlag(STATUS_FLAG, JSON.stringify(all));
}
}
// ─── What is wrong ──────────────────────────────────────────────────────────
export interface AuthentikProblem {
key: string;
message: string;
severity: "warning" | "critical";
}
/** Whole days from now to then, rounded down; negative once it has passed. */
export const daysUntil = (iso: string, now: Date) => Math.floor((Date.parse(iso) - now.getTime()) / DAY_MS);
const when = (days: number) => (days < 0 ? `ran out ${-days} day${days === -1 ? "" : "s"} ago` : days === 0 ? "runs out today" : `runs out in ${days} day${days === 1 ? "" : "s"}`);
/** "12 min ago", "3 h ago", "2 days ago". */
const ago = (iso: string, now: Date) => {
const min = Math.max(0, Math.round((now.getTime() - Date.parse(iso)) / 60_000));
return min < 90 ? `${min} min ago` : min < 2 * 1440 ? `${Math.round(min / 60)} h ago` : `${Math.round(min / 1440)} days ago`;
};
/** Pure: what is wrong with one Authentik, from what is stored for it. */
export function authentikProblems(id: number, name: string, s: Pick<StateRow, "workers" | "outposts" | "certificates" | "tokens" | "failedLogins24h" | "configErrors24h" | "lastConfigError">, now: Date = new Date()): AuthentikProblem[] {
const out: AuthentikProblem[] = [];
for (const o of outpostsOf(s)) {
if (o.providers === 0) continue; // serves nothing, so nothing is lost when it is quiet
if (o.healthy === 0) {
out.push({
key: `authentik-outpost:${id}:${o.name}`,
severity: "critical",
message: `${name}: the ${o.type} outpost “${o.name}” has not reported in for a while${o.lastSeen ? ` (last heard ${ago(o.lastSeen, now)})` : " (it never has)"} — what it guards is not letting anyone in`,
});
} else if (o.outdated) {
out.push({ key: `authentik-outpost-version:${id}:${o.name}`, severity: "warning", message: `${name}: the ${o.type} outpost “${o.name}” runs a different version from Authentik` });
}
}
for (const c of certificatesOf(s)) {
const days = daysUntil(c.expires, now);
if (days > CERT_WARN_DAYS) continue;
out.push({ key: `authentik-cert:${id}:${c.name}`, severity: days <= CERT_CRITICAL_DAYS ? "critical" : "warning", message: `${name}: the certificate “${c.name}” ${when(days)}` });
}
for (const t of tokensOf(s)) {
const days = daysUntil(t.expires, now);
if (days > TOKEN_WARN_DAYS) continue;
out.push({
key: `authentik-token:${id}:${t.identifier}`,
severity: days <= TOKEN_CRITICAL_DAYS ? "critical" : "warning",
message: `${name}: the ${t.intent === "app_password" ? "app password" : "API token"} “${t.identifier}”${t.user ? ` (${t.user})` : ""} ${when(days)}`,
});
}
if (s.workers === 0) out.push({ key: `authentik-worker:${id}`, severity: "warning", message: `${name}: no worker is connected — mail, outpost changes and scheduled tasks are not being done` });
if (s.failedLogins24h !== null && s.failedLogins24h >= FAILED_LOGINS_WARN) {
out.push({ key: `authentik-logins:${id}`, severity: "warning", message: `${name}: ${s.failedLogins24h >= 100 ? "100 or more" : s.failedLogins24h} sign-ins failed in the last day` });
}
if (s.configErrors24h !== null && s.configErrors24h >= CONFIG_ERRORS_WARN) {
out.push({ key: `authentik-errors:${id}`, severity: "warning", message: `${name}: ${s.configErrors24h} configuration errors in the last day${s.lastConfigError ? ` — the latest: ${s.lastConfigError}` : ""}` });
}
return out;
}
let timer: ReturnType<typeof setInterval> | null = null;
export function initAuthentikSync(): void {
if (timer) return;
const pass = () => void syncAllAuthentik().catch((err) => console.error("[authentik] pass failed:", err));
timer = setInterval(pass, SYNC_INTERVAL_MS);
setTimeout(pass, 13_000);
console.log(`[authentik] reading Authentik every ${SYNC_INTERVAL_MS / 60000} minutes`);
}
+25 -1
View File
@@ -1,6 +1,6 @@
import { and, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { integrations, jellyfinState, networkDevices, serverPorts, servers, upsState } from "../db/schema.js";
import { authentikState, integrations, jellyfinState, networkDevices, serverPorts, servers, upsState } from "../db/schema.js";
import { loadIntegrationConfig } from "../integrations/loadIntegration.js";
import { createProxmoxAdapter, type ProxmoxNodeStats } from "../integrations/proxmox/adapter.js";
import { createSynologyAdapter, type SynologyStorageInfo } from "../integrations/synology/adapter.js";
@@ -21,6 +21,7 @@ import { levelFindings, levelKey, type LevelFinding } from "./serviceLevels.js";
import { createDockhandAdapter } from "../integrations/dockhand/adapter.js";
import { currentProblems as duplicatiProblemsNow, type DuplicatiProblem } from "./duplicati.js";
import { isJellyfinFresh, jellyfinProblems, jellyfinSyncStatuses, type JellyfinProblem } from "./jellyfinSync.js";
import { authentikProblems, authentikSyncStatuses, isAuthentikFresh, type AuthentikProblem } from "./authentikSync.js";
import { evaluateContainers, loadContainerMemory, saveContainerMemory, type ContainerMemory, type DockerSnapshot } from "./containerHealth.js";
import { recordStorageSamples } from "./storageHistory.js";
import { isUpsFresh, upsProblems, upsSyncStatuses, type UpsStateRow } from "./upsSync.js";
@@ -88,6 +89,8 @@ export interface HealthSnapshot {
baselines?: BaselineFinding[];
/** Service-level targets whose error budget for the month is mostly or wholly used (services/serviceLevels.ts). */
levels?: LevelFinding[];
/** What is wrong with each Authentik, from what was stored, only while that reading is recent (services/authentikSync.ts). */
authentik?: { integrationId: number; problems: AuthentikProblem[] }[];
/** What is wrong with each Jellyfin, from what was stored, only while that reading is recent (services/jellyfinSync.ts). */
jellyfin?: { integrationId: number; problems: JellyfinProblem[] }[];
/** Duplicati backups that failed or have not succeeded in time (services/duplicati.ts). */
@@ -201,6 +204,9 @@ export function evaluateHealth(snapshot: HealthSnapshot, thresholds: Thresholds,
}
}
// An Authentik outpost that went quiet, a certificate or token about to run out, no worker, failed sign-ins.
for (const a of snapshot.authentik ?? []) for (const p of a.problems) out.push({ key: p.key, source: `authentik:${a.integrationId}`, message: p.message, severity: p.severity });
// A Jellyfin that wants a restart, a scheduled task that failed, a burst of failed sign-ins.
for (const j of snapshot.jellyfin ?? []) for (const p of j.problems) out.push({ key: p.key, source: `jellyfin:${j.integrationId}`, message: p.message, severity: p.severity });
@@ -434,6 +440,24 @@ export async function collectSnapshot(): Promise<{ snapshot: HealthSnapshot; hel
}
}
// Authentik: read by its own pass every few minutes; what is judged is what that pass stored, and only while it is recent.
try {
const rowsA = await db.select({ id: integrations.id, name: integrations.name }).from(integrations).where(and(eq(integrations.type, "authentik"), eq(integrations.enabled, true)));
if (rowsA.length > 0) {
const statuses = await authentikSyncStatuses();
for (const r of rowsA) {
const [state] = await db.select().from(authentikState).where(eq(authentikState.integrationId, r.id)).limit(1);
if (!state || !isAuthentikFresh(statuses[r.id], Date.now())) {
held.add(`authentik:${r.id}`);
continue;
}
(snapshot.authentik ??= []).push({ integrationId: r.id, problems: authentikProblems(r.id, r.name, state) });
}
}
} catch (err) {
console.error("[health] couldn't judge Authentik:", err instanceof Error ? err.message : err);
}
// Jellyfin: read by its own pass every couple of minutes; what is judged is what that pass stored, and only while it is recent.
try {
const rowsJ = await db.select({ id: integrations.id, name: integrations.name }).from(integrations).where(and(eq(integrations.type, "jellyfin"), eq(integrations.enabled, true)));
+2
View File
@@ -33,6 +33,8 @@ export function subjectOfConditionKey(key: string): string | null {
if (m) return `integration:${m[1]}`;
m = /^jellyfin-(?:restart|task|logins):(\d+)/.exec(key);
if (m) return `integration:${m[1]}`;
m = /^authentik-(?:outpost|outpost-version|cert|token|worker|logins|errors):(\d+)/.exec(key);
if (m) return `integration:${m[1]}`;
m = /^duplicati-(?:failed|stale):\d+:server:(\d+)$/.exec(key);
if (m) return `server:${m[1]}`;
m = /^(?:endpoint(?:-cert)?|heartbeat(?:-fail)?):\d+:server:(\d+)$/.exec(key);
+17 -1
View File
@@ -5,11 +5,12 @@
*/
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { assets, endpointChecks, heartbeats, integrations, maintenanceWindows, secrets, servers, upsState, jellyfinState } from "../db/schema.js";
import { assets, endpointChecks, heartbeats, integrations, maintenanceWindows, secrets, servers, upsState, jellyfinState, authentikState } from "../db/schema.js";
import { isUpsFresh, upsSyncStatuses } from "./upsSync.js";
import { levelStatuses } from "./serviceLevels.js";
import { backupState, listAll as listDuplicati } from "./duplicati.js";
import { isJellyfinFresh, jellyfinSyncStatuses, streamsOf } from "./jellyfinSync.js";
import { authentikSyncStatuses, certificatesOf, daysUntil, isAuthentikFresh, outpostsOf } from "./authentikSync.js";
import { latestTests } from "./restoreTests.js";
import { heartbeatState, parseStamp } from "./heartbeats.js";
import { env } from "../env.js";
@@ -61,6 +62,20 @@ class Exposition {
}
}
/** Each Authentik, for /metrics: whether each outpost that serves something is reporting, how many workers there are, the failed sign-ins and the days left of each certificate. Only while the reading is recent. */
async function addAuthentikMetrics(out: Exposition, now: Date) {
const statuses = await authentikSyncStatuses();
const names = new Map((await db.select({ id: integrations.id, name: integrations.name, enabled: integrations.enabled }).from(integrations).where(eq(integrations.type, "authentik"))).map((r) => [r.id, r]));
for (const s of await db.select().from(authentikState)) {
const row = names.get(s.integrationId);
if (!row || !row.enabled || !isAuthentikFresh(statuses[s.integrationId], now.getTime())) continue;
for (const o of outpostsOf(s)) out.add("homelab_authentik_outpost_up", "gauge", "1 if the Authentik outpost has reported in lately, else 0.", o.healthy > 0 ? 1 : 0, { name: row.name, outpost: o.name });
if (s.workers !== null) out.add("homelab_authentik_workers", "gauge", "How many Authentik workers are connected.", s.workers, { name: row.name });
if (s.failedLogins24h !== null) out.add("homelab_authentik_failed_logins_24h", "gauge", "Sign-ins that failed in the last day (100 means at least that many).", s.failedLogins24h, { name: row.name });
for (const c of certificatesOf(s)) out.add("homelab_authentik_certificate_expiry_days", "gauge", "Whole days until the certificate runs out; negative once it has.", daysUntil(c.expires, now), { name: row.name, certificate: c.name });
}
}
/** Each Jellyfin, for /metrics: how many are streaming, how many of those are transcoded, and whether it wants a restart. Only while the reading is recent. */
async function addJellyfinMetrics(out: Exposition, now: Date) {
const statuses = await jellyfinSyncStatuses();
@@ -284,6 +299,7 @@ export async function buildMetrics(now: Date = new Date()): Promise<string> {
await addServiceLevelMetrics(out, now);
await addDuplicatiMetrics(out, now);
await addJellyfinMetrics(out, now);
await addAuthentikMetrics(out, now);
await addHeartbeatMetrics(out, now);
return out.toString();
}