From 0f5476b5422e3c88a5a891bc18666507b32dfc49 Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Tue, 17 Nov 2026 21:01:21 +0100 Subject: [PATCH] Authentik: a tick box to switch off the certificate alerts For an Authentik that is not in use at the moment: "Do not alert about certificates" on the integration stops the certificate alerts (and clears the ones raised) while the page still lists the certificates and /metrics still carries their expiry. Outposts, tokens, failed sign-ins and configuration errors are unaffected. Same pattern as Fragnet's mute boxes. Tests and docs added. Co-Authored-By: Claude Sonnet 5.5 --- INTEGRATIONS.md | 2 +- README.md | 2 +- docs/MONITORING.md | 2 +- server/src/integrations/fieldSchemas.ts | 1 + server/src/routes/authentik.ts | 12 ++++++++++-- server/src/services/authentikSync.ts | 16 ++++++++++++++-- server/src/services/healthMonitor.ts | 5 +++-- server/test/authentik.test.ts | 19 +++++++++++++++++++ 8 files changed, 50 insertions(+), 9 deletions(-) diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index b3f9ada..a9741e5 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -587,7 +587,7 @@ osTicket's API cannot close a ticket, so this is the one place in the app that * ### Authentik -- **Config fields:** the **address** of Authentik (`https://auth.example.lan`), an **API token** (Authentik → Directory → Tokens and App passwords → *Create*, intent **API Token**, for a user who may read; stored encrypted), optionally a **token for making and managing users** (below) and, for an https address with a certificate you made yourself, *insecure*. +- **Config fields:** the **address** of Authentik (`https://auth.example.lan`), an **API token** (Authentik → Directory → Tokens and App passwords → *Create*, intent **API Token**, for a user who may read; stored encrypted), optionally a **token for making and managing users** (below), for an https address with a certificate you made yourself, *insecure*, and a tick box, **do not alert about certificates**, for an Authentik you are not using at the moment: the certificate alerts stop (and any that were raised clear), while the page still lists the certificates and `/metrics` still has `homelab_authentik_certificate_expiry_days`. The other alerts (outposts, tokens, failed sign-ins, configuration errors) are not affected. - **Required access:** read only. This app only ever sends GET requests: the version, the workers, the outposts and their health, the certificates, the tokens and the events log. **Nothing is ever changed.** Give the token a user with just enough to read these (an administrator, or a user in a role that may view them); if one of the lists is refused, that part is left out and the rest still works. - **Making and managing users (optional, administrators only):** all of it is on its own tab, **Apps → Authentik → Users and groups**, which only an administrator sees; **Status** (the default) stays what it was. with a second, separate token in *Token for making and managing users* — an API token of an account that may add, change and delete users, which is close to an administrator of Authentik, so give it only if you want this — **Apps → Authentik → Users and groups → New user** makes a user diff --git a/README.md b/README.md index bba0f72..3f3361e 100644 --- a/README.md +++ b/README.md @@ -602,7 +602,7 @@ quietly never made. The page shows the photo and video counts, what the library (critical when labelled so). The page shows targets by job and what is down or firing. Alerts managed by Grafana itself are not seen. See INTEGRATIONS.md and docs/MONITORING.md. **Authentik** (Apps → Authentik). Add an Authentik integration (its address and an API token) and the app watches the sign-in in front of everything else: it raises a **critical** alert when an **outpost** that guards applications stops reporting, and warns when a **certificate** or an **API token** is -about to run out (the token it reads Authentik with included), when **no worker** is connected, and when **sign-ins are failing** or flows are misconfigured. The page lists the outposts, what runs out soonest and the failed sign-ins of the last day. See INTEGRATIONS.md and docs/MONITORING.md. +about to run out (the token it reads Authentik with included), when **no worker** is connected, and when **sign-ins are failing** or flows are misconfigured. The page lists the outposts, what runs out soonest and the failed sign-ins of the last day. An Authentik you are not using for the moment can have its **certificate alerts switched off** (a tick box on the integration; the page still lists them). See INTEGRATIONS.md and docs/MONITORING.md. An administrator also has a second tab there, **Users and groups**, and can **make a user** on it — with a second, optional token for it — and gets a **one-time recovery link** to send them, so they choose their own password; no password is ever set or seen here, and the link is shown once and not kept. The same page lists the users and lets an administrator **edit** one (name, email, groups), **switch one off** (and on again) or **delete** one (the user name has to be typed); service accounts, the account the token belongs to and the last active administrator are refused. **Groups** can be made (empty, and never as a group that makes administrators), renamed, deleted (the name has to be typed; never one that makes administrators) and have users put in and taken out (whether a group makes administrators is not changed here); a group that decides roles in this app is marked and asks first. **Jellyfin** (Apps → Jellyfin). Add a Jellyfin integration (its address and an API key) and the app shows whether it is up, **who is streaming what** and whether it is being transcoded, the scheduled tasks that failed, and a chart of how many watched at once; it warns when Jellyfin **wants a restart**, a diff --git a/docs/MONITORING.md b/docs/MONITORING.md index 5eef245..a3ff0a2 100644 --- a/docs/MONITORING.md +++ b/docs/MONITORING.md @@ -483,7 +483,7 @@ Grafana manages itself are not in Prometheus's list; to see one here, write it a ## Authentik -An integration of type *Authentik* ([INTEGRATIONS.md](../INTEGRATIONS.md#authentik)) is read every five minutes, and **Apps → Authentik** shows its version, workers, each outpost (and whether it is reporting), the certificates and API tokens that run out — soonest first — and the failed sign-ins of the last day. +An integration of type *Authentik* ([INTEGRATIONS.md](../INTEGRATIONS.md#authentik)) is read every five minutes, and **Apps → Authentik** shows its version, workers, each outpost (and whether it is reporting), the certificates and API tokens that run out — soonest first — and the failed sign-ins of the last day. The certificate alerts can be switched off for one Authentik (the tick box **Do not alert about certificates** on the integration) — useful for one that is not in use at the moment; the certificates are still listed and in `/metrics`, and the other alerts are unchanged. Authentik is the front door to everything behind it, so what is raised early is what would shut it: | Alert | When | Severity | diff --git a/server/src/integrations/fieldSchemas.ts b/server/src/integrations/fieldSchemas.ts index 9424aa7..9b4a861 100644 --- a/server/src/integrations/fieldSchemas.ts +++ b/server/src/integrations/fieldSchemas.ts @@ -216,6 +216,7 @@ export const INTEGRATION_FIELDS: Partial { const byId = new Map(states.map((s) => [s.integrationId, s])); const writable = new Map(await Promise.all(rows.map(async (r) => [r.id, await canCreateUsers(r.id)] as const))); const now = new Date(); + const options = new Map>(); + for (const r of rows) { + try { + options.set(r.id, optionsOf((await loadIntegrationConfig(r.id))?.config)); + } catch { + // a config that cannot be read costs only the settings it holds + } + } res.json({ authentiks: rows.map((r) => { const state = byId.get(r.id) ?? null; @@ -128,7 +136,7 @@ authentikRouter.get("/", asyncHandler(async (_req, res) => { updatedAt: state.updatedAt, } : null, - problems: state && fresh ? authentikProblems(r.id, r.name, state, now) : [], + problems: state && fresh ? authentikProblems(r.id, r.name, state, now, options.get(r.id)) : [], }; }), }); diff --git a/server/src/services/authentikSync.ts b/server/src/services/authentikSync.ts index aff21de..bb25adc 100644 --- a/server/src/services/authentikSync.ts +++ b/server/src/services/authentikSync.ts @@ -139,8 +139,20 @@ const ago = (iso: string, now: Date) => { return min < 90 ? `${min} min ago` : min < 2 * 1440 ? `${Math.round(min / 60)} h ago` : `${Math.round(min / 1440)} days ago`; }; +/** Which kinds of alert are on for one Authentik. Everything is on until the person switches a kind off on the integration. */ +export interface AuthentikOptions { + alerts: { certificates: boolean }; +} + +const ticked = (v: unknown): boolean => v === true || v === "true"; + +/** Pure: the options in an integration's saved settings (none, or settings that cannot be read, leave everything on). */ +export function optionsOf(config: Record | null | undefined): AuthentikOptions { + return { alerts: { certificates: !ticked(config?.muteCertificates) } }; +} + /** Pure: what is wrong with one Authentik, from what is stored for it. */ -export function authentikProblems(id: number, name: string, s: Pick, now: Date = new Date()): AuthentikProblem[] { +export function authentikProblems(id: number, name: string, s: Pick, now: Date = new Date(), options: AuthentikOptions = optionsOf(null)): 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 @@ -154,7 +166,7 @@ export function authentikProblems(id: number, name: string, s: Pick 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)}` }); diff --git a/server/src/services/healthMonitor.ts b/server/src/services/healthMonitor.ts index 72b1037..ea8b530 100644 --- a/server/src/services/healthMonitor.ts +++ b/server/src/services/healthMonitor.ts @@ -23,7 +23,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 { authentikProblems, authentikSyncStatuses, isAuthentikFresh, optionsOf as authentikOptions, type AuthentikProblem } from "./authentikSync.js"; import { isPrometheusFresh, prometheusProblems, prometheusSyncStatuses, type PrometheusProblem } from "./prometheusSync.js"; import { immichProblems, immichSyncStatuses, isImmichFresh, type ImmichProblem } from "./immichSync.js"; import { isPaperlessFresh, paperlessProblems, paperlessSyncStatuses, type PaperlessProblem } from "./paperlessSync.js"; @@ -873,7 +873,8 @@ export async function collectSnapshot(): Promise<{ snapshot: HealthSnapshot; hel held.add(`authentik:${r.id}`); continue; } - (snapshot.authentik ??= []).push({ integrationId: r.id, problems: authentikProblems(r.id, r.name, state) }); + const loaded = await loadIntegrationConfig(r.id).catch(() => null); + (snapshot.authentik ??= []).push({ integrationId: r.id, problems: authentikProblems(r.id, r.name, state, new Date(), authentikOptions(loaded?.config)) }); } } } catch (err) { diff --git a/server/test/authentik.test.ts b/server/test/authentik.test.ts index bce796b..5c19d02 100644 --- a/server/test/authentik.test.ts +++ b/server/test/authentik.test.ts @@ -206,6 +206,25 @@ describe("what is wrong, and how close is close", () => { assert.match(ak.authentikProblems(1, "SSO", row({ certificates: certs(-2) }), NOW)[0].message, /ran out 2 days ago/); }); + test("certificate alerts can be switched off for one Authentik, and only they", () => { + const certs = JSON.stringify([{ name: "web", expires: inDays(-5) }]); + const tokens = JSON.stringify([{ identifier: "monitoring", intent: "api", user: null, expires: inDays(1) }]); + const judge = (config: Record | null) => ak.authentikProblems(1, "SSO", row({ certificates: certs, tokens, failedLogins24h: 50 }), NOW, ak.optionsOf(config)).map((p) => p.key); + assert.deepEqual(judge(null), ["authentik-cert:1:web", "authentik-token:1:monitoring", "authentik-logins:1"], "everything is on until it is switched off"); + assert.deepEqual(judge({ muteCertificates: false }), ["authentik-cert:1:web", "authentik-token:1:monitoring", "authentik-logins:1"]); + for (const on of [true, "true"]) assert.deepEqual(judge({ muteCertificates: on }), ["authentik-token:1:monitoring", "authentik-logins:1"], String(on)); + assert.deepEqual(judge({ muteCertificates: "false" }), ["authentik-cert:1:web", "authentik-token:1:monitoring", "authentik-logins:1"]); + assert.deepEqual(ak.optionsOf(undefined).alerts, { certificates: true }); + }); + + test("the setting is a tick box on the Authentik integration, and the page and /metrics still carry the certificates", async () => { + const { INTEGRATION_FIELDS } = await import("../src/integrations/fieldSchemas.js"); + const field = INTEGRATION_FIELDS.authentik?.find((f) => f.key === "muteCertificates"); + assert.deepEqual([field?.type, field?.optional, field?.secret], ["checkbox", true, false]); + const { readFileSync } = await import("node:fs"); + assert.match(readFileSync(new URL("../src/services/metrics.ts", import.meta.url), "utf8"), /homelab_authentik_certificate_expiry_days/); + }); + 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) })), []);