Anmeldung ueber Authentik und andere OIDC-Anbieter

Anmeldefluss mit PKCE (S256), State und Nonce. Das ID-Token wird gegen den JWKS des Anbieters geprueft — Signatur, Aussteller, Empfaenger, Ablauf und Nonce; alles Noetige kommt aus dem Discovery-Dokument, damit die Anbindung nicht auf Authentik festgelegt ist. Wiedererkannt wird jemand an der Kennung des Anbieters (sub), nicht an der E-Mail-Adresse — Adressen aendern sich. Ein bestehendes Konto mit derselben Adresse wird verknuepft statt verdoppelt, aber nur bei bestaetigter Adresse: sonst koennte sich beim Anbieter jemand eine fremde Adresse eintragen und damit ein hiesiges Konto uebernehmen. Uebernommen wird bewusst nur, wer jemand ist — plus die Instanz-Administration, wenn OIDC_ADMIN_GROUP gesetzt ist. Gruppen und Rollen bleiben Sache dieser Anwendung: die Gruppen im Verzeichnis bedeuten etwas anderes als die hier. Konten aus dem Verzeichnis haben kein Passwort mehr (passwordHash ist jetzt optional); Konto-Bereich und Passwort-Anmeldung sagen das statt an einer leeren Pruefung zu scheitern. Anleitung mit allen Feldern in Authentik: docs/authentik.md
2026-08-15 00:12:21 +02:00
parent e296b1e6c2
commit c8d60d8006
14 changed files with 1039 additions and 11 deletions
@@ -0,0 +1,281 @@
+import "server-only";
+
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+
+import { getBaseUrl } from "@/lib/env";
+import { QrRequestError } from "@/lib/qr/type-module";
+
+/**
+ * Anmeldung über einen externen Anbieter (OpenID Connect) — gedacht und
+ * getestet für Authentik, aber nicht darauf festgelegt: Alles Nötige kommt
+ * aus dem Discovery-Dokument des Anbieters.
+ *
+ * Bewusst begrenzt auf die Frage „wer bist du?“. Wer in welcher Gruppe welche
+ * Rolle hat, bleibt Sache der Verwaltung dieser Anwendung — die Rollen hier
+ * bedeuten etwas anderes als die Gruppen im Verzeichnis, und eine automatische
+ * Übersetzung wäre eine Quelle stiller Überraschungen. Einzige Ausnahme ist
+ * die Instanz-Administration, die sich über `OIDC_ADMIN_GROUP` an eine Gruppe
+ * beim Anbieter hängen lässt.
+ */
+
+export type OidcConfig = {
+  issuer: string;
+  clientId: string;
+  clientSecret: string;
+  scopes: string;
+  /** Anzeigename des Knopfs auf der Anmeldeseite. */
+  buttonLabel: string;
+  /** Gruppe beim Anbieter, die zur Instanz-Administration berechtigt. */
+  adminGroup: string | null;
+  /** Name des Anspruchs, in dem die Gruppen stehen. */
+  groupsClaim: string;
+  /** Rolle, die neu angelegte Benutzer in der Standardgruppe bekommen. */
+  defaultRole: "ADMIN" | "EDITOR" | "VIEWER";
+  /** Ist die Anmeldung mit Passwort daneben noch erlaubt? */
+  allowLocalLogin: boolean;
+};
+
+function env(name: string): string {
+  return process.env[name]?.trim() ?? "";
+}
+
+/**
+ * Cookie, der State, Nonce und PKCE-Geheimnis über die Weiterleitung zum
+ * Anbieter trägt. Lebt nur für die Dauer des Anmeldevorgangs.
+ */
+export const OIDC_FLOW_COOKIE = "qrgen_oidc_flow";
+export const OIDC_FLOW_MINUTES = 10;
+
+export function isOidcEnabled(): boolean {
+  return env("OIDC_ENABLED").toLowerCase() === "true";
+}
+
+/**
+ * Liest die Konfiguration. Wirft mit einer Meldung, die sagt, was fehlt —
+ * eine halb eingerichtete Anmeldung soll nicht als „irgendwas ging schief“
+ * enden.
+ */
+export function getOidcConfig(): OidcConfig {
+  const issuer = env("OIDC_ISSUER").replace(/\/+$/, "");
+  const clientId = env("OIDC_CLIENT_ID");
+  const clientSecret = env("OIDC_CLIENT_SECRET");
+
+  const fehlend = [
+    !issuer && "OIDC_ISSUER",
+    !clientId && "OIDC_CLIENT_ID",
+    !clientSecret && "OIDC_CLIENT_SECRET",
+  ].filter(Boolean);
+
+  if (fehlend.length > 0) {
+    throw new QrRequestError(
+      `Die Anmeldung über den externen Anbieter ist unvollständig eingerichtet. Es fehlt: ${fehlend.join(", ")}.`,
+      500,
+    );
+  }
+
+  const rolle = env("OIDC_DEFAULT_ROLE").toUpperCase();
+
+  return {
+    issuer,
+    clientId,
+    clientSecret,
+    scopes: env("OIDC_SCOPES") || "openid email profile",
+    buttonLabel: env("OIDC_BUTTON_LABEL") || "Mit Authentik anmelden",
+    adminGroup: env("OIDC_ADMIN_GROUP") || null,
+    groupsClaim: env("OIDC_GROUPS_CLAIM") || "groups",
+    defaultRole:
+      rolle === "ADMIN" || rolle === "EDITOR" || rolle === "VIEWER"
+        ? rolle
+        : "VIEWER",
+    allowLocalLogin: env("OIDC_ONLY").toLowerCase() !== "true",
+  };
+}
+
+/** Adresse, an die der Anbieter nach der Anmeldung zurückschickt. */
+export function redirectUri(): string {
+  return `${getBaseUrl()}/api/auth/oidc/callback`;
+}
+
+type Discovery = {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  userinfo_endpoint?: string;
+  end_session_endpoint?: string;
+};
+
+/**
+ * Das Discovery-Dokument ändert sich praktisch nie, der Abruf kostet aber bei
+ * jeder Anmeldung eine Runde. Deshalb im Speicher halten — eine Stunde ist
+ * kurz genug, um einen Schlüsselwechsel mitzubekommen.
+ */
+const DISCOVERY_TTL_MS = 60 * 60 * 1000;
+let discoveryCache: { url: string; bis: number; wert: Discovery } | null = null;
+
+export async function discover(issuer: string): Promise<Discovery> {
+  const url = `${issuer}/.well-known/openid-configuration`;
+  const jetzt = Date.now();
+
+  if (discoveryCache && discoveryCache.url === url && discoveryCache.bis > jetzt) {
+    return discoveryCache.wert;
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url, { headers: { Accept: "application/json" } });
+  } catch {
+    throw new QrRequestError(
+      `Der Anmelde-Anbieter ist nicht erreichbar (${issuer}). Läuft er, und stimmt OIDC_ISSUER?`,
+      502,
+    );
+  }
+
+  if (!response.ok) {
+    throw new QrRequestError(
+      `Der Anmelde-Anbieter liefert unter ${url} den Status ${response.status}. Stimmt OIDC_ISSUER?`,
+      502,
+    );
+  }
+
+  const wert = (await response.json()) as Discovery;
+  if (!wert.authorization_endpoint || !wert.token_endpoint || !wert.jwks_uri) {
+    throw new QrRequestError(
+      "Der Anmelde-Anbieter liefert ein unvollständiges Discovery-Dokument.",
+      502,
+    );
+  }
+
+  discoveryCache = { url, bis: jetzt + DISCOVERY_TTL_MS, wert };
+  return wert;
+}
+
+/** JWKS je Adresse zwischenspeichern — `jose` erneuert bei Bedarf selbst. */
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+function jwks(uri: string) {
+  const vorhanden = jwksCache.get(uri);
+  if (vorhanden) return vorhanden;
+  const neu = createRemoteJWKSet(new URL(uri));
+  jwksCache.set(uri, neu);
+  return neu;
+}
+
+export type OidcIdentity = {
+  subject: string;
+  email: string;
+  emailVerified: boolean;
+  name: string | null;
+  groups: string[];
+};
+
+function readGroups(payload: JWTPayload, claim: string): string[] {
+  const wert = payload[claim];
+  if (Array.isArray(wert)) {
+    return wert.filter((eintrag): eintrag is string => typeof eintrag === "string");
+  }
+  // Manche Anbieter liefern eine durch Leerzeichen getrennte Liste.
+  if (typeof wert === "string") return wert.split(/\s+/).filter(Boolean);
+  return [];
+}
+
+/**
+ * Tauscht den Code gegen Token und prüft das ID-Token.
+ *
+ * Geprüft wird die Signatur gegen den JWKS des Anbieters sowie Aussteller,
+ * Empfänger und die Nonce. Letztere schließt aus, dass ein anderswo
+ * erbeutetes Token hier eingereicht wird.
+ */
+export async function exchangeCode(options: {
+  config: OidcConfig;
+  code: string;
+  codeVerifier: string;
+  nonce: string;
+}): Promise<OidcIdentity> {
+  const { config, code, codeVerifier, nonce } = options;
+  const meta = await discover(config.issuer);
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri(),
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    code_verifier: codeVerifier,
+  });
+
+  const response = await fetch(meta.token_endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body,
+  });
+
+  if (!response.ok) {
+    // Der Text des Anbieters ist für Betreiber oft hilfreich, gehört aber
+    // nicht ungefiltert in den Browser.
+    const text = await response.text().catch(() => "");
+    console.error("OIDC: Token-Tausch fehlgeschlagen:", response.status, text);
+    throw new QrRequestError(
+      "Die Anmeldung beim Anbieter ist fehlgeschlagen. Stimmen Client-ID und Geheimnis?",
+      502,
+    );
+  }
+
+  const token = (await response.json()) as { id_token?: string };
+  if (!token.id_token) {
+    throw new QrRequestError(
+      "Der Anbieter hat kein ID-Token geliefert. Ist der Scope „openid“ erlaubt?",
+      502,
+    );
+  }
+
+  let payload: JWTPayload;
+  try {
+    ({ payload } = await jwtVerify(token.id_token, jwks(meta.jwks_uri), {
+      issuer: meta.issuer || config.issuer,
+      audience: config.clientId,
+    }));
+  } catch (error) {
+    console.error("OIDC: ID-Token nicht gültig:", error);
+    throw new QrRequestError("Das Anmelde-Token des Anbieters ist ungültig.", 502);
+  }
+
+  if (payload.nonce !== nonce) {
+    throw new QrRequestError(
+      "Die Anmeldung passt nicht zu dieser Sitzung. Bitte versuche es erneut.",
+      400,
+    );
+  }
+
+  const subject = typeof payload.sub === "string" ? payload.sub : "";
+  const email =
+    typeof payload.email === "string" ? payload.email.trim().toLowerCase() : "";
+
+  if (!subject) {
+    throw new QrRequestError("Der Anbieter hat keine Kennung geliefert.", 502);
+  }
+  if (!email) {
+    throw new QrRequestError(
+      "Der Anbieter hat keine E-Mail-Adresse geliefert. Bitte den Scope „email“ freigeben und das Attribut mitgeben.",
+      502,
+    );
+  }
+
+  const name =
+    typeof payload.name === "string" && payload.name.trim().length > 0
+      ? payload.name.trim()
+      : typeof payload.preferred_username === "string"
+        ? payload.preferred_username.trim()
+        : null;
+
+  return {
+    subject,
+    email,
+    emailVerified: payload.email_verified !== false,
+    name,
+    groups: readGroups(payload, config.groupsClaim),
+  };
+}