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

+323
View File
@@ -0,0 +1,323 @@
/**
* Authentik: reading what its API says (outposts and their health, certificates, tokens, events), what is stored, what is wrong and how close to running out is a warning
* or critical, the health pass, the alerts, the page's route and /metrics.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-authentik-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, authentikState } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const adapter = await import("../src/integrations/authentik/adapter.js");
const ak = await import("../src/services/authentikSync.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { authentikRouter } = await import("../src/routes/authentik.js");
const { buildMetrics } = await import("../src/services/metrics.js");
const { setInternalFlag } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const MIN = 60_000;
const DAY = 86_400_000;
const NOW = new Date("2026-10-20T12:00:00Z");
const inDays = (d: number, from: Date = NOW) => new Date(from.getTime() + d * DAY).toISOString();
type Read = import("../src/integrations/authentik/adapter.js").AuthentikRead;
const read = (extra: Partial<Read> = {}): Read => ({ version: "2025.8.1", latestVersion: "2025.8.1", outdated: false, workers: 1, outposts: [], certificates: [], tokens: [], failedLogins24h: 0, configErrors24h: 0, lastConfigError: null, ...extra });
const outpost = (extra: Partial<import("../src/integrations/authentik/adapter.js").AuthentikOutpost> = {}) => ({ name: "Proxy", type: "proxy", providers: 2, healthy: 1, instances: 1, outdated: false, lastSeen: NOW.toISOString(), ...extra });
describe("what Authentik's API says", () => {
test("the version, and whether a newer one is out", () => {
assert.deepEqual(adapter.parseVersion({ version_current: "2025.8.1", version_latest: "2025.10.0", outdated: true }), { version: "2025.8.1", latestVersion: "2025.10.0", outdated: true });
assert.deepEqual(adapter.parseVersion(null), { version: null, latestVersion: null, outdated: false });
});
test("workers are counted; an answer that is not a list is not 'none'", () => {
assert.equal(adapter.parseWorkers([{ worker_id: "a" }, { worker_id: "b" }]), 2);
assert.equal(adapter.parseWorkers([]), 0);
assert.equal(adapter.parseWorkers({ detail: "nope" }), null);
});
test("an outpost is healthy when an instance reported within five minutes; its version and what it serves are read", () => {
const o = adapter.parseOutpost(
{ name: "Proxy", type: "proxy", providers: [1, 2, 3] },
[{ last_seen: new Date(NOW.getTime() - 2 * MIN).toISOString(), version_outdated: false }, { last_seen: new Date(NOW.getTime() - 60 * MIN).toISOString(), version_outdated: true }],
NOW,
)!;
assert.deepEqual([o.name, o.providers, o.healthy, o.instances, o.outdated], ["Proxy", 3, 1, 2, true]);
const silent = adapter.parseOutpost({ name: "LDAP", type: "ldap", providers: [1] }, [{ last_seen: new Date(NOW.getTime() - 60 * MIN).toISOString() }], NOW)!;
assert.deepEqual([silent.healthy, silent.instances], [0, 1]);
assert.equal(adapter.parseOutpost({ name: "Idle", providers: [] }, [], NOW)!.providers, 0);
assert.equal(adapter.parseOutpost({}, [], NOW), null);
});
test("certificates Authentik renews itself (managed) are left out", () => {
const c = adapter.parseCertificates({ results: [{ name: "mine", cert_expiry: "2026-12-01T00:00:00Z", managed: null }, { name: "theirs", cert_expiry: "2026-12-01T00:00:00Z", managed: "goauthentik.io/x" }, { name: "no date" }] });
assert.deepEqual(c, [{ name: "mine", expires: "2026-12-01T00:00:00.000Z" }]);
});
test("only API tokens and app passwords that expire are tokens worth watching", () => {
const t = adapter.parseTokens({
results: [
{ identifier: "monitoring", intent: "api", expiring: true, expires: "2026-11-01T00:00:00Z", user_obj: { username: "svc" } },
{ identifier: "forever", intent: "api", expiring: false, expires: "2099-01-01T00:00:00Z" },
{ identifier: "login", intent: "verification", expiring: true, expires: "2026-10-20T12:30:00Z" },
{ identifier: "mail", intent: "app_password", expiring: true, expires: "2026-11-05T00:00:00Z" },
],
});
assert.deepEqual(t.map((x) => [x.identifier, x.intent, x.user]), [["monitoring", "api", "svc"], ["mail", "app_password", null]]);
});
test("events in the last day are counted, with the newest one's words", () => {
const raw = { results: [{ created: new Date(NOW.getTime() - MIN).toISOString(), context: { message: "stage failed" } }, { created: new Date(NOW.getTime() - 2 * DAY).toISOString(), context: { message: "old" } }] };
assert.deepEqual(adapter.countRecentEvents(raw, NOW), { count: 1, latest: "stage failed" });
assert.deepEqual(adapter.countRecentEvents({ detail: "x" }, NOW), { count: null, latest: null });
});
describe("the adapter against an Authentik that answers", () => {
let server: Server;
let url = "";
const seen: string[] = [];
before(async () => {
server = createHttpServer((req, res) => {
const full = req.url ?? "";
seen.push(`${req.headers.authorization} ${full}`);
const send = (code: number, body: unknown) => {
res.writeHead(code, { "content-type": "application/json" });
res.end(JSON.stringify(body));
};
if (req.headers.authorization !== "Bearer tok") return send(403, { detail: "no" });
const now = Date.now();
const path = full.split("?")[0];
if (path === "/api/v3/admin/version/") return send(200, { version_current: "2025.8.1", version_latest: "2025.8.1", outdated: false });
if (path === "/api/v3/admin/workers/") return send(200, []);
if (path === "/api/v3/outposts/instances/") return send(200, { pagination: {}, results: [{ pk: "o1", name: "Proxy", type: "proxy", providers: [1, 2] }, { pk: "o2", name: "LDAP", type: "ldap", providers: [3] }, { pk: "o3", name: "Idle", type: "radius", providers: [] }] });
if (path === "/api/v3/outposts/instances/o1/health/") return send(200, [{ last_seen: new Date(now - MIN).toISOString(), version_outdated: false }]);
if (path === "/api/v3/outposts/instances/o2/health/") return send(200, [{ last_seen: new Date(now - 90 * MIN).toISOString() }]);
if (path === "/api/v3/outposts/instances/o3/health/") return send(200, []);
if (path === "/api/v3/crypto/certificatekeypairs/") return send(200, { results: [{ name: "web", cert_expiry: new Date(now + 5 * DAY).toISOString(), managed: null }, { name: "built-in", cert_expiry: new Date(now + 400 * DAY).toISOString(), managed: "goauthentik.io/x" }] });
if (path === "/api/v3/core/tokens/") return send(500, {}); // the rest is worth having, not worth failing for
if (path === "/api/v3/events/events/") {
const fresh = new Date(now - MIN).toISOString();
if (full.includes("action=login_failed")) return send(200, { results: Array.from({ length: 25 }, () => ({ created: fresh })) });
return send(200, { results: [{ created: fresh, context: { message: "email stage could not send" } }] });
}
send(404, {});
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
after(() => server.close());
test("it reads everything, sends the token, and a part that cannot be read does not fail the whole", async () => {
const r = await adapter.createAuthentikAdapter({ url: `${url}/`, token: "tok" }).read(new Date());
assert.equal(r.version, "2025.8.1");
assert.equal(r.workers, 0);
assert.deepEqual(r.outposts.map((o) => [o.name, o.healthy, o.providers]), [["Proxy", 1, 2], ["LDAP", 0, 1], ["Idle", 0, 0]]);
assert.deepEqual(r.certificates.map((c) => c.name), ["web"], "the managed one is left out");
assert.deepEqual(r.tokens, [], "the tokens could not be read");
assert.deepEqual([r.failedLogins24h, r.configErrors24h, r.lastConfigError], [25, 1, "email stage could not send"]);
assert.ok(seen.every((s) => s.startsWith("Bearer tok ")));
});
test("a refused token and a dead address are said plainly", async () => {
const bad = await adapter.createAuthentikAdapter({ url, token: "nope" }).ping();
assert.equal(bad.ok, false);
assert.match(bad.error ?? "", /did not accept the token/);
assert.equal((await adapter.createAuthentikAdapter({ url, token: "tok" }).ping()).ok, true);
assert.equal((await adapter.createAuthentikAdapter({ url: "http://127.0.0.1:1", token: "tok" }).ping()).ok, false);
});
});
});
describe("what is stored", () => {
let id = 0;
before(async () => {
id = (await db.insert(integrations).values({ type: "authentik", name: "SSO", baseUrl: "http://10.9.9.7:9000", config: JSON.stringify({ url: "http://10.9.9.7:9000", token: "tok" }) }).returning({ id: integrations.id }))[0].id;
});
test("the state is replaced at each read", async () => {
await ak.storeRead(id, read({ workers: 2, outposts: [outpost()] }), NOW);
await ak.storeRead(id, read({ workers: 1, outposts: [outpost({ name: "LDAP", type: "ldap" })], failedLogins24h: 3 }), NOW);
const [s] = await db.select().from(authentikState).where(eq(authentikState.integrationId, id));
assert.deepEqual([s.workers, ak.outpostsOf(s).map((o) => o.name), s.failedLogins24h], [1, ["LDAP"], 3]);
});
test("a read that failed is said, and what was stored is left alone", async () => {
const ok = await ak.syncAuthentik(id, new Date(), async () => read({ version: "2025.10.0" }));
assert.equal(ok.ok, true);
const failed = await ak.syncAuthentik(id, new Date(), async () => {
throw new Error("connection refused");
});
assert.deepEqual([failed.ok, failed.error], [false, "connection refused"]);
assert.equal(failed.at, ok.at, "the time of the last good read is kept");
const [s] = await db.select().from(authentikState).where(eq(authentikState.integrationId, id));
assert.equal(s.version, "2025.10.0");
assert.equal(ak.isAuthentikFresh((await ak.authentikSyncStatuses())[id], Date.now()), false, "a failed read is not believed");
});
test("only a good read recent enough is fresh", () => {
const now = Date.now();
assert.equal(ak.isAuthentikFresh({ at: new Date(now - 6 * MIN).toISOString(), ok: true, error: null }, now), true);
assert.equal(ak.isAuthentikFresh({ at: new Date(now - 21 * MIN).toISOString(), ok: true, error: null }, now), false);
assert.equal(ak.isAuthentikFresh(undefined, now), false);
});
});
describe("what is wrong, and how close is close", () => {
const row = (extra: Partial<Parameters<typeof ak.authentikProblems>[2]> = {}) => ({ workers: 1, outposts: "[]", certificates: "[]", tokens: "[]", failedLogins24h: 0, configErrors24h: 0, lastConfigError: null, ...extra });
const keys = (r: ReturnType<typeof row>) => ak.authentikProblems(1, "SSO", r, NOW).map((p) => `${p.key}=${p.severity}`);
test("nothing wrong says nothing", () => {
assert.deepEqual(keys(row()), []);
assert.deepEqual(keys(row({ workers: null, failedLogins24h: null, configErrors24h: null })), [], "what could not be asked is not a problem");
});
test("an outpost that serves something and has gone quiet is critical; one that serves nothing is left alone; another version is a warning", () => {
const outposts = JSON.stringify([outpost({ name: "Proxy", healthy: 0, lastSeen: null }), outpost({ name: "Idle", providers: 0, healthy: 0 }), outpost({ name: "LDAP", type: "ldap", outdated: true })]);
assert.deepEqual(keys(row({ outposts })), ["authentik-outpost:1:Proxy=critical", "authentik-outpost-version:1:LDAP=warning"]);
assert.match(ak.authentikProblems(1, "SSO", row({ outposts }), NOW)[0].message, /never has/);
});
test("a certificate: a warning within 14 days, critical within 3 and after", () => {
const certs = (d: number) => JSON.stringify([{ name: "web", expires: inDays(d) }]);
assert.deepEqual(keys(row({ certificates: certs(30) })), []);
assert.deepEqual(keys(row({ certificates: certs(14) })), ["authentik-cert:1:web=warning"]);
assert.deepEqual(keys(row({ certificates: certs(3) })), ["authentik-cert:1:web=critical"]);
assert.deepEqual(keys(row({ certificates: certs(-2) })), ["authentik-cert:1:web=critical"]);
assert.match(ak.authentikProblems(1, "SSO", row({ certificates: certs(5) }), NOW)[0].message, /runs out in 5 days/);
assert.match(ak.authentikProblems(1, "SSO", row({ certificates: certs(-2) }), NOW)[0].message, /ran out 2 days ago/);
});
test("a token: a warning within 7 days, critical within 2", () => {
const tokens = (d: number) => JSON.stringify([{ identifier: "monitoring", intent: "api", user: "svc", expires: inDays(d) }]);
assert.deepEqual(keys(row({ tokens: tokens(8) })), []);
assert.deepEqual(keys(row({ tokens: tokens(7) })), ["authentik-token:1:monitoring=warning"]);
assert.deepEqual(keys(row({ tokens: tokens(1) })), ["authentik-token:1:monitoring=critical"]);
assert.match(ak.authentikProblems(1, "SSO", row({ tokens: tokens(4) }), NOW)[0].message, /API token “monitoring” \(svc\) runs out in 4 days/);
});
test("no worker, a burst of failed sign-ins and a run of configuration errors are warnings", () => {
assert.deepEqual(keys(row({ workers: 0 })), ["authentik-worker:1=warning"]);
assert.deepEqual(keys(row({ failedLogins24h: ak.FAILED_LOGINS_WARN - 1 })), []);
assert.deepEqual(keys(row({ failedLogins24h: ak.FAILED_LOGINS_WARN })), ["authentik-logins:1=warning"]);
assert.match(ak.authentikProblems(1, "SSO", row({ failedLogins24h: 100 }), NOW)[0].message, /100 or more/);
const e = ak.authentikProblems(1, "SSO", row({ configErrors24h: ak.CONFIG_ERRORS_WARN, lastConfigError: "email stage could not send" }), NOW);
assert.deepEqual(e.map((p) => p.key), ["authentik-errors:1"]);
assert.match(e[0].message, /the latest: email stage could not send/);
assert.deepEqual(keys(row({ configErrors24h: ak.CONFIG_ERRORS_WARN - 1 })), []);
});
});
describe("the health pass, the page and /metrics", () => {
let akId = 0;
let app: Server;
let base = "";
const fresh = () => setInternalFlag("authentikSync", JSON.stringify({ [akId]: { at: new Date().toISOString(), ok: true, error: null } }));
const stale = () => setInternalFlag("authentikSync", JSON.stringify({ [akId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null } }));
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]);
akId = (await db.insert(integrations).values({ type: "authentik", name: "Front door", baseUrl: "http://10.9.9.6:9000", config: JSON.stringify({ url: "http://10.9.9.6:9000", token: "tok" }) }).returning({ id: integrations.id }))[0].id;
const nowD = new Date();
await ak.storeRead(
akId,
read({ workers: 0, outposts: [outpost({ name: "Proxy", healthy: 0, lastSeen: null }), outpost({ name: "LDAP", type: "ldap", providers: 1, healthy: 1 })], certificates: [{ name: "web", expires: inDays(5, nowD) }, { name: "far", expires: inDays(300, nowD) }], tokens: [{ identifier: "monitoring", intent: "api", user: "svc", expires: inDays(1, nowD) }], failedLogins24h: 30 }),
nowD,
);
await fresh();
const a = express();
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "viewer" } };
next();
});
a.use("/api/authentik", authentikRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/authentik`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("the health pass judges it from what is stored, and holds it when the last read is old", async () => {
let { snapshot, held } = await collectSnapshot();
assert.deepEqual(snapshot.authentik?.map((a) => a.integrationId), [akId]);
assert.equal(held.has(`authentik:${akId}`), false);
const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true });
const c = list.find((x) => x.key === `authentik-outpost:${akId}:Proxy`)!;
assert.deepEqual([c.severity, c.source], ["critical", `authentik:${akId}`]);
assert.equal(subjectOfConditionKey(c.key), `integration:${akId}`, "maintenance on it silences its alerts");
for (const k of ["authentik-cert", "authentik-token", "authentik-worker", "authentik-logins", "authentik-errors", "authentik-outpost-version"]) assert.equal(subjectOfConditionKey(`${k}:${akId}`), `integration:${akId}`);
await stale();
({ snapshot, held } = await collectSnapshot());
assert.deepEqual([snapshot.authentik ?? [], held.has(`authentik:${akId}`)], [[], true]);
await fresh();
});
test("the Alerts page shows each, in the kind it belongs to, with where to look", async () => {
invalidateAlertsCache();
const report = await getAlerts(true);
const find = (key: string) => report.alerts.find((x) => x.id.endsWith(`${key}`))!;
const outposts = find(`authentik-outpost:${akId}:Proxy`);
assert.deepEqual([outposts.severity, outposts.category, outposts.source, outposts.link, outposts.target?.type, outposts.target?.id], ["critical", "services", "Authentik", "/authentik", "integration", akId]);
assert.equal(find(`authentik-cert:${akId}:web`).category, "expiry");
assert.equal(find(`authentik-token:${akId}:monitoring`).severity, "critical");
assert.equal(find(`authentik-logins:${akId}`).category, "monitoring");
assert.equal(find(`authentik-worker:${akId}`).category, "services");
assert.equal(report.alerts.some((x) => x.id.endsWith(`authentik-cert:${akId}:far`)), false, "a certificate with time left is not an alert");
});
test("anyone signed in sees each Authentik, what runs out soonest first, and what is wrong", async () => {
const res = await fetch(base);
assert.equal(res.status, 200);
const body = (await res.json()) as { authentiks: { id: number; fresh: boolean; state: { certificates: { name: string; days: number }[]; tokens: { identifier: string; days: number }[]; outposts: unknown[] } | null; problems: { key: string }[] }[] };
const a = body.authentiks.find((x) => x.id === akId)!;
assert.equal(a.fresh, true);
assert.deepEqual(a.state?.certificates.map((c) => c.name), ["web", "far"], "the soonest first");
assert.deepEqual(a.state?.tokens.map((t) => t.identifier), ["monitoring"]);
assert.ok((a.state?.tokens[0].days ?? 9) <= 1, "about a day left");
assert.equal(a.state?.outposts.length, 2);
assert.ok(a.problems.some((p) => p.key === `authentik-outpost:${akId}:Proxy`));
await stale();
const old = (await (await fetch(base)).json()) as typeof body;
assert.deepEqual(old.authentiks.find((x) => x.id === akId)!.problems, [], "an old reading says nothing is wrong, it does not guess");
await fresh();
});
test("/metrics has each outpost, the workers, the failed sign-ins and the days left of each certificate — only while the reading is recent", async () => {
let text = await buildMetrics(new Date());
assert.match(text, /homelab_authentik_outpost_up\{name="Front door",outpost="Proxy"\} 0/);
assert.match(text, /homelab_authentik_outpost_up\{name="Front door",outpost="LDAP"\} 1/);
assert.match(text, /homelab_authentik_workers\{name="Front door"\} 0/);
assert.match(text, /homelab_authentik_failed_logins_24h\{name="Front door"\} 30/);
assert.match(text, /homelab_authentik_certificate_expiry_days\{name="Front door",certificate="web"\} [45]/);
await stale();
text = await buildMetrics(new Date());
assert.doesNotMatch(text, /homelab_authentik/);
});
});