# Anmeldung über Authentik (OIDC) Diese Anleitung richtet die Anmeldung am QR-Code-Generator über **Authentik** ein. Sie funktioniert genauso mit anderen OpenID-Connect-Anbietern — Keycloak, Zitadel, Entra ID —, weil die Anwendung alles Nötige aus dem Discovery-Dokument des Anbieters liest. Die Beispiele nennen Authentik, weil die Feldnamen dort so heißen. **Zeitbedarf:** etwa 15 Minuten. --- ## Vorher klären | Frage | Antwort für diese Anleitung | | --- | --- | | Adresse der Anwendung | `https://qr.example.com` | | Adresse von Authentik | `https://auth.example.com` | | Läuft die Anwendung über HTTPS? | Ja — siehe Hinweis unten | > **HTTPS ist Pflicht, sobald es über den eigenen Rechner hinausgeht.** Beim > Anmelden gehen Token über die Leitung, und der Sitzungs-Cookie wird nur bei > `https://` in der `BASE_URL` als `Secure` gesetzt. Für einen Versuch im LAN > geht auch HTTP; produktiv gehört ein Reverse Proxy davor (siehe README, > Abschnitt „Hinter einem Reverse Proxy“). Die Anwendung muss Authentik erreichen können und umgekehrt der Browser beide. Laufen beide in Docker auf demselben Host, genügt es meist, sie ins selbe Netz zu hängen — der Browser braucht aber in jedem Fall öffentlich auflösbare Adressen. --- ## Schritt 1 — In Authentik einen Provider anlegen **Applications → Providers → Create → OAuth2/OpenID Provider** | Feld | Wert | | --- | --- | | Name | `QR-Code-Generator` | | Authorization flow | `default-provider-authorization-explicit-consent` (oder implicit, wenn niemand zustimmen soll) | | Client type | **Confidential** | | Client ID | notieren — kommt gleich in die `.env` | | Client Secret | notieren — ebenfalls | | Redirect URIs | **deine** `BASE_URL` + `/api/auth/oidc/callback` — siehe unten | | Signing Key | ein vorhandenes Zertifikat auswählen | | Subject mode | `Based on the User's hashed ID` (Voreinstellung) | Zu den **Scopes**: `openid`, `email` und `profile` müssen ausgewählt sein. Ohne `email` liefert Authentik keine Adresse, und die Anwendung lehnt die Anmeldung mit einer entsprechenden Meldung ab. ### Die Redirect URI Das ist der häufigste Stolperstein. Der Wert ist **kein Beispiel zum Abschreiben**, sondern ergibt sich aus deiner `BASE_URL`: ``` {BASE_URL}/api/auth/oidc/callback ``` Was dein Container als `BASE_URL` kennt, zeigt: ```bash docker compose exec app env | grep BASE_URL ``` Ein paar Beispiele: | `BASE_URL` | Redirect URI | | --- | --- | | `https://qr.example.com` | `https://qr.example.com/api/auth/oidc/callback` | | `http://10.10.10.150:3005` | `http://10.10.10.150:3005/api/auth/oidc/callback` | | `http://192.168.1.50:3000` | `http://192.168.1.50:3000/api/auth/oidc/callback` | Zu beachten: - **Kein Schrägstrich am Ende.** - **Schema und Port gehören dazu** — `http` ist nicht `https`, und `:3005` darf nicht fehlen. - Neben dem Feld steht in neueren Authentik-Fassungen eine Auswahl **Strict** oder **Regex**. Für eine feste Adresse muss dort **Strict** stehen. Bei `Regex` wäre jeder Punkt einer IP-Adresse ein Platzhalter und müsste maskiert werden. - Bleibt das Feld leer, lässt Authentik **gar nichts** durch. > **Wenn es trotzdem klemmt:** Authentik zeigt den Fehler „Redirect URI Error“ > noch auf seiner eigenen Seite an — die Anwendung bekommt davon nichts mit. > Welche Adresse tatsächlich ankam, steht zum Vergleich > 1. in der Adresszeile des Browsers, im Parameter `redirect_uri`, und > 2. in Authentik unter **Events → Logs** im Eintrag `redirect_uri_error`. > > Weicht die ankommende Adresse von deiner `BASE_URL` ab, ist nicht Authentik > falsch eingestellt, sondern die `BASE_URL` — und die gehört korrigiert, > bevor der erste dynamische Code entsteht: Sie steckt in jedem davon. ### `BASE_URL` und die Adresse im Browser müssen dieselbe sein Nicht nur „irgendeine erreichbare Adresse“ — **dieselbe**, über die ihr die Anwendung tatsächlich aufruft. Der Grund liegt im Ablauf: Beim Klick auf den Anmeldeknopf legt die Anwendung einen Cookie mit dem laufenden Vorgang ab — auf dem Host, über den der Browser gerade da ist. Die Rückkehradresse für Authentik kommt dagegen aus `BASE_URL`. Zeigen die beiden auf verschiedene Hosts, schickt Authentik den Browser auf den anderen Host, der Cookie bleibt beim ersten zurück, und die Anmeldung endet mit **„Der Anmeldevorgang ist abgelaufen“**. Erkennbar ist es daran, dass in der Adresszeile plötzlich eine andere Adresse steht als die, mit der man begonnen hat. Seit Version vom 17.08.2026 fängt die Anwendung das ab und nennt beide Adressen, statt den Vorgang bis zum Ende laufen zu lassen. Ein häufiges Muster: Die Anwendung läuft hinter einem Reverse Proxy unter `https://qr.example.com`, in der `.env` steht aber noch die interne Adresse `http://10.0.0.5:3005` aus der Einrichtung. Dann gehören **drei** Werte in Übereinstimmung gebracht: | | | | --- | --- | | Aufruf im Browser | `https://qr.example.com` | | `BASE_URL` in der `.env` | `https://qr.example.com` | | Redirect URI in Authentik | `https://qr.example.com/api/auth/oidc/callback` | --- ## Schritt 2 — Eine Application anlegen **Applications → Applications → Create** | Feld | Wert | | --- | --- | | Name | `QR-Code-Generator` | | Slug | `qrcode-generator` | | Provider | der eben angelegte Provider | | Launch URL | `https://qr.example.com` | Der **Slug** steckt gleich in der Issuer-Adresse — merken. Wer den Zugang einschränken will, hängt hier unter **Policy / Group / User Bindings** eine Gruppe ein. Das ist der empfohlene Weg: Wer sich bei Authentik anmelden darf, kommt sonst auch in den QR-Code-Generator. --- ## Schritt 3 — Die Issuer-Adresse herausfinden Authentik zeigt sie beim Provider unter **Provider Info** als *OpenID Configuration Issuer*. Sie sieht so aus: ``` https://auth.example.com/application/o/qrcode-generator/ ``` Prüfen lässt sich das direkt: ```bash curl https://auth.example.com/application/o/qrcode-generator/.well-known/openid-configuration ``` Kommt ein JSON-Dokument mit `authorization_endpoint`, `token_endpoint` und `jwks_uri` zurück, stimmt die Adresse. --- ## Schritt 4 — Die `.env` ergänzen ```bash AUTH_ENABLED=true OIDC_ENABLED=true OIDC_ISSUER=https://auth.example.com/application/o/qrcode-generator/ OIDC_CLIENT_ID= OIDC_CLIENT_SECRET= OIDC_BUTTON_LABEL=Mit Authentik anmelden OIDC_SCOPES=openid email profile OIDC_DEFAULT_ROLE=EDITOR OIDC_ADMIN_GROUP=qr-admins OIDC_GROUPS_CLAIM=groups OIDC_ONLY=false ``` Danach neu starten: ```bash docker compose up -d ``` > `OIDC_ENABLED` allein genügt nicht — **`AUTH_ENABLED` muss ebenfalls `true` > sein**. Ohne Anmeldung gibt es keine Benutzer, denen eine Anmeldung > zugeordnet werden könnte. --- ## Schritt 5 — Ausprobieren `https://qr.example.com/anmelden` aufrufen. Über dem Passwortfeld steht jetzt **„Mit Authentik anmelden“**. Ein Klick führt zu Authentik, nach der Anmeldung geht es zurück in die Anwendung. Alle Anmeldenden bekommen die Rolle aus `OIDC_DEFAULT_ROLE` in der Standardgruppe. Wer die **Verwaltung** öffnen darf, hängt davon ab, ob `OIDC_ADMIN_GROUP` gesetzt ist: - **Leer:** Der erste Mensch, der sich anmeldet, wird Administrator dieser Installation — genau wie bei der Ersteinrichtung mit Passwort. Danach vergibt man das Recht unter Verwaltung → Benutzer. - **Gesetzt:** Dann entscheidet allein die Gruppe, und zwar bei **jeder** Anmeldung neu — auch beim allerersten Benutzer. > **Achtung beim ersten Mal:** Wenn du `OIDC_ADMIN_GROUP` setzt, vergewissere > dich, dass dein eigenes Konto in dieser Gruppe ist. Sonst hat niemand Zugang > zur Verwaltung. Der Weg zurück ist einfach: die Variable leeren, > `docker compose up -d`, neu anmelden — dann greift wieder die Regel „der > erste wird Administrator“, sofern es noch gar keinen gibt. --- ## Was die Anwendung aus Authentik übernimmt — und was nicht | Übernommen | Bleibt in der Anwendung | | --- | --- | | Wer jemand ist (`sub`) | Mitgliedschaft in Gruppen | | E-Mail-Adresse | Rolle je Gruppe (Admin/Bearbeiter/Betrachter) | | Anzeigename | Zuteilung von Domains | | Instanz-Administration, falls `OIDC_ADMIN_GROUP` gesetzt ist | alles Übrige | Das ist eine bewusste Entscheidung. Die Gruppen in Authentik und die Gruppen hier bedeuten nicht dasselbe: dort geht es um Organisation und Zugang, hier um die Frage, wer welche QR-Codes sehen und ändern darf. Eine automatische Übersetzung wäre eine Quelle stiller Überraschungen — deshalb pflegt man Gruppen und Rollen weiterhin unter **Verwaltung → Gruppen**. Wiedererkannt wird jemand an der **Kennung von Authentik** (`sub`), nicht an der E-Mail-Adresse. Ändert sich die Adresse, bleibt es dasselbe Konto. ### Die Admin-Gruppe Steht in `OIDC_ADMIN_GROUP` ein Gruppenname, entscheidet Authentik bei **jeder Anmeldung** neu, wer die Verwaltung öffnen darf: Mitglieder der Gruppe bekommen das Recht, alle anderen verlieren es. Bleibt die Variable leer, rührt die Anmeldung das Recht nicht an — dann pflegt man es hier. --- ## Bestehende Konten übernehmen Gibt es hier schon Konten mit Passwort, werden sie beim ersten Anmelden über Authentik **anhand der E-Mail-Adresse verknüpft**. Aus dem lokalen Administrator wird also kein zweites Konto; Gruppen, Rollen und die angelegten Codes bleiben. Verknüpft wird nur, wenn Authentik die Adresse als **bestätigt** meldet. Sonst könnte sich beim Anbieter jemand eine fremde Adresse eintragen und damit ein hiesiges Konto übernehmen. Meldet Authentik sie als unbestätigt, bricht die Anmeldung mit einer Erklärung ab. Ist ein Konto einmal verknüpft, gibt es dafür kein Passwort mehr: Der Bereich **Konto** zeigt dann statt der Passwortänderung einen Hinweis auf den Anbieter. --- ## Nur noch über Authentik anmelden ```bash OIDC_ONLY=true ``` Danach verschwindet das Passwortfeld von der Anmeldeseite. > **Vorher an den Notausgang denken.** Fällt Authentik aus oder ist der > Provider falsch konfiguriert, kommt niemand mehr hinein. Der Weg zurück: > `OIDC_ONLY=false` in der `.env`, `docker compose up -d` — dann geht die > Anmeldung mit Passwort wieder. Lege dir dafür ein lokales Administratorkonto > an, **bevor** du umstellst. --- ## Wenn etwas nicht klappt | Symptom | Ursache und Abhilfe | | --- | --- | | Der Knopf erscheint nicht | `AUTH_ENABLED` oder `OIDC_ENABLED` steht nicht auf `true`. Prüfen mit `docker compose exec app env \| grep OIDC`. Steht dort nichts, fehlt die Variable im `environment:`-Block der `docker-compose.yml` — die `.env` allein reicht nicht. | | „Die Anmeldung über den externen Anbieter ist unvollständig eingerichtet“ | Es fehlt `OIDC_ISSUER`, `OIDC_CLIENT_ID` oder `OIDC_CLIENT_SECRET`. Die Meldung nennt, welche. | | „Der Anmelde-Anbieter ist nicht erreichbar“ | Der Container kommt nicht an Authentik. Testen mit `docker compose exec app wget -qO- /.well-known/openid-configuration`. Häufig: interner DNS-Name statt öffentlicher Adresse. | | Authentik zeigt „Redirect URI Error“ | Die Redirect URI im Provider stimmt nicht exakt mit `{BASE_URL}/api/auth/oidc/callback` überein — siehe [Die Redirect URI](#die-redirect-uri). Auf Schema, Port, Schrägstrich am Ende und die Auswahl Strict/Regex achten. | | „Der Anbieter hat keine E-Mail-Adresse geliefert“ | Der Scope `email` fehlt im Provider, oder der Benutzer hat in Authentik keine Adresse hinterlegt. | | „Der Anbieter hat die Anmeldung abgelehnt“ | Der Benutzer ist der Application in Authentik nicht zugeordnet — Policy/Group Binding prüfen. | | „Der Anmeldevorgang ist abgelaufen“ | Der Cookie mit dem laufenden Vorgang kam nicht zurück. Entweder sind mehr als 10 Minuten vergangen — oder, weit häufiger, `BASE_URL` zeigt auf einen anderen Host als den, über den der Browser kommt. Erkennbar daran, dass in der Adresszeile eine andere Adresse steht als beim Start. Siehe [BASE_URL und die Adresse im Browser](#base_url-und-die-adresse-im-browser-müssen-dieselbe-sein). | | „Du rufst die Anwendung über … auf, BASE_URL zeigt aber auf …“ | Genau der Fall von oben, nur früh erkannt. Die Meldung nennt beide Adressen; `BASE_URL` in der `.env` auf die erste setzen und `docker compose up -d` ausführen. | | „Das Anmelde-Token des Anbieters ist ungültig“ | Uhrzeit-Abweichung zwischen den Servern oder ein gewechselter Signaturschlüssel. Beides zeigt `docker compose logs app` genauer. | | Nach der Anmeldung fehlt die Verwaltung | `OIDC_ADMIN_GROUP` ist gesetzt, der Benutzer aber nicht in dieser Gruppe. Entweder die Gruppe in Authentik ergänzen oder die Variable leeren und das Recht hier vergeben. | Ausführlichere Meldungen stehen im Protokoll: ```bash docker compose logs -f app ``` --- ## Was technisch passiert 1. Klick auf den Knopf → `/api/auth/oidc/start`. Die Anwendung holt das Discovery-Dokument, würfelt `state`, `nonce` und ein PKCE-Geheimnis und legt sie in einen kurzlebigen, `httpOnly`-Cookie. 2. Weiterleitung zu Authentik mit `code_challenge` (S256). 3. Nach der Anmeldung kommt Authentik mit `code` und `state` zurück auf `/api/auth/oidc/callback`. Stimmt der `state` nicht, endet es hier. 4. Die Anwendung tauscht den Code gegen Token — mit Client-Geheimnis **und** PKCE-Verifier. Ein abgefangener Code allein nützt also niemandem. 5. Das ID-Token wird gegen den JWKS von Authentik geprüft: Signatur, Aussteller, Empfänger, Ablauf und `nonce`. 6. Konto suchen (über `sub`, ersatzweise über die bestätigte Adresse), anlegen oder verknüpfen — und die Sitzung wie bei der Passwort-Anmeldung setzen. Die Sitzung selbst ist danach dieselbe wie sonst: ein Zufallstoken im Cookie, in der Datenbank nur dessen SHA-256. Abmelden beendet sie hier; bei Authentik bleibt man angemeldet.