API-Authentifizierung

octoja verwendet Token-basierte Authentifizierung für API-Clients und ein HTTP-Session-Cookie für browserbasierte Abläufe.

Nach einem erfolgreichen Login oder Refresh enthält der Response-Body ein accessToken und ein refreshToken, zusammen mit tokenType und expiresIn (Lebensdauer des Access-Tokens in Sekunden). Beide sind opake Zeichenketten, die octoja ausstellt — speichere sie genau so, wie du sie erhältst, und schicke sie unverändert zurück. Jede erfolgreiche Anmeldung, auch über die API, setzt zusätzlich das Session-Cookie octo_session, das die octoja-Weboberfläche verwendet.

Login

POST /api/auth/login

Request Body

Beispiel-Request

{ "mailAddress": "alex@example.com", "password": "example-password", "TOTP": "123456" }

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

Refresh

POST /api/auth/refresh

Ein gültiges Refresh-Token gegen ein neues Token-Paar eintauschen.

Request Body

Beispiel-Request

{ "refreshToken": "<refresh_token>" }

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

Logout

POST /api/auth/logout

Meldet die aktuelle Browser-Sitzung ab und löscht das octo_session-Cookie.

Access-Token verwenden

Schicke das Access-Token im Authorization-Header bei authentifizierten API-Anfragen mit:

Authorization: Bearer <access_token>
Content-Type: application/json

Um die API interaktiv zu erkunden, öffne die OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html, klicke auf Authorize und füge dein Access-Token ein. Swagger sendet dann den Authorization-Header für dich, sodass du authentifizierte Anfragen ohne eigenen Code ausprobieren kannst.

OIDC / SSO Login

octoja unterstützt Single Sign-On über OIDC-Anbieter wie Microsoft — sowohl aus dem Browser als auch aus einer nativen App.

Verfügbare Anbieter ermitteln

GET /api/auth/oidc/providers

Gibt die Liste der für deine Organisation konfigurierten OIDC-Anbieter zurück. Damit kannst du vor dem Starten eines Logins prüfen, welche Anbieternamen gültig sind.

Browser-Login starten

1. Rufe GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-frontend-url> auf.
2. Der Endpoint gibt ein JSON-Objekt mit der Login-URL des Anbieters zurück.
3. Leite den Benutzer zu dieser URL weiter.
4. Nach Abschluss des Anbieter-Logins wird der Browser an /api/auth/oidc/callback weitergeleitet.
5. Wenn für den angemeldeten Benutzer keine Zwei-Faktor-Authentifizierung aktiviert ist, setzt das Backend die Sitzung und leitet den Browser zurück zur ursprünglichen returnUrl. Ist TOTP für den Benutzer aktiviert, wird noch keine Sitzung ausgestellt: Der Browser wird an die Frontend-Route /login mit einem oidcTotpPending-Code und der returnUrl weitergeleitet, und die Sitzung wird erst nach Bestätigung des zweiten Faktors ausgestellt.

Welche Anbieter verfügbar sind, hängt von der Konfiguration deiner Organisation ab. Microsoft ist standardmäßig aktiviert; Google steht zur Verfügung und lässt sich in derselben Konfiguration einschalten.

Login aus einer nativen App

Eine native App durchläuft denselben Ablauf mit PKCE, sodass das einmalige Ergebnis an die App selbst geht und nicht an den System-Browser. Dieser Ablauf steht zur Verfügung, sobald die Callback-URI deiner App mit eigenem Schema — zum Beispiel octoja://oidc-callback — unter Oidc:AllowedMobileRedirectUris in der Konfiguration deiner Instanz eingetragen ist.

1. Rufe GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-callback-uri>&codeChallenge=<pkce_code_challenge> auf. Die returnUrl muss exakt einer der konfigurierten Callback-URIs entsprechen.
2. Öffne die zurückgegebene URL im System-Browser, damit sich der Benutzer beim Anbieter anmelden kann.
3. Der Callback leitet den Browser an deine Callback-URI weiter, mit einem einmaligen handoff-Code im Query-String.
4. Löse diesen Code aus der App heraus mit POST /api/auth/oidc/handoff ein und übergib dabei den PKCE-Verifier, der zur Challenge aus Schritt 1 passt: { "handoff": "<handoff_code>", "codeVerifier": "<pkce_code_verifier>" }. Die Antwort enthält dasselbe Token-Paar wie ein Passwort-Login.
5. Ist für den Benutzer die Zwei-Faktor-Authentifizierung aktiviert, antwortet der Handoff-Aufruf mit 403 Forbidden und der Code bleibt gültig — wiederhole dieselbe Anfrage und ergänze den Einmalcode des Benutzers.

Authentifizierungsfehler