Skip to Content

OAuth 2.0 & OpenID Connect

Das Verständnis von OAuth 2.0 und OpenID Connect ist die Grundlage für eine korrekte Integration mit Auris. Diese Seite erklärt die Protokolle, ihre Unterschiede, die von Auris unterstützten Grant-Typen und wie Auris sie intern implementiert.

Was ist OAuth 2.0?

OAuth 2.0 (RFC 6749) ist ein Autorisierungs-Framework. Es bietet eine standardisierte Methode, mit der ein Benutzer einer Drittanbieter-Anwendung begrenzten Zugriff auf seine Ressourcen bei einem anderen Dienst gewähren kann, ohne dabei seine Anmeldedaten an die Drittanbieter-Anwendung weiterzugeben.

Die grundlegende Erkenntnis ist, dass es bei OAuth 2.0 um die Delegation von Zugriff geht — nicht um die Verifizierung von Identität. Wenn du dich mit “Mit Google anmelden” bei einer Drittanbieter-App anmeldest, nutzt Google OAuth 2.0, um der App Zugriff auf deine Profildaten zu gewähren — nicht um zu beweisen, dass du die Person bist, für die du dich ausgibst. Das ist eine separate Schicht.

Kernrollen in OAuth 2.0

RolleBeschreibung
Resource OwnerDer Benutzer, dem die Daten gehören und der Zugriff gewährt
ClientDie Anwendung, die auf die Daten zugreifen möchte
Authorization ServerDer Server, der Tokens ausstellt (Auris)
Resource ServerDie API, die die Daten schützt

In Auris sind Authorization Server und Resource Server Teil derselben Plattform — deiner Auris-Instanz. Der Client ist deine Anwendung, und der Resource Owner ist dein Benutzer.

Was OAuth 2.0 nicht ist

OAuth 2.0 definiert nicht:

  • Wie ein Benutzer seine Identität nachweist (kein Login-Protokoll)
  • Was in einem Zugriffstoken enthalten ist
  • Wie Tokens von Ressourcenservern validiert werden

Diese Lücken führten zur Entstehung von OpenID Connect.

Was ist OpenID Connect?

OpenID Connect (OIDC) ist eine Authentifizierungsschicht, die auf OAuth 2.0 aufbaut. Es beantwortet die Frage, die OAuth 2.0 offen lässt: “Wer ist dieser Benutzer?”

OIDC erweitert den OAuth 2.0-Autorisierungscode-Flow durch:

  1. Das ID-Token — ein signiertes JWT mit der Identität des Benutzers (Benutzer-ID, E-Mail, Name usw.)
  2. Den UserInfo-Endpunkt — wo der Client zusätzliche Benutzer-Claims abrufen kann
  3. Standardisierte Claims — ein definierter Satz von Claim-Namen (sub, email, name, picture usw.)
  4. Discovery-Dokument — eine bekannte URL, die die Endpunkte des Providers beschreibt

Bei der Verwendung von OIDC forderst du neben anderen Scopes den openid-Scope an. Das Vorhandensein von openid im Scope teilt dem Authorization Server mit, zusätzlich zum Zugriffstoken ein ID-Token auszustellen.

Der Unterschied in der Praxis

OAuth 2.0OpenID Connect
ZweckAutorisierung (Zugriffsdelegation)Authentifizierung (Identitätsverifizierung)
Ausgestelltes TokenZugriffstoken (opak oder JWT)Zugriffstoken + ID-Token
Benutzerinfo im TokenNicht standardisiertStandardisiert (sub, email, name usw.)
Wer der Benutzer istUnbekanntDurch ID-Token etabliert
Anwendungsfall”Kann diese App meinen Kalender lesen?""Wer ist dieser Benutzer?”

In Auris ist jeder gehostete Login-Flow OIDC — der openid-Scope ist standardmäßig enthalten, und die Token-Antwort enthält immer ein ID-Token zusätzlich zu Zugriffs- und Refresh-Tokens.

Von Auris unterstützte Grant-Typen

OAuth 2.0 definiert mehrere “Grant-Typen” — Flows zum Abrufen von Tokens je nach Art des Clients und Anwendungsfall.

1. Autorisierungscode + PKCE (empfohlen)

Der Standard-Flow für benutzerseitige Anwendungen (Web-Apps, mobile Apps, SPAs, CLIs mit Browser-Weiterleitung). PKCE (Proof Key for Code Exchange, RFC 7636) wird hinzugefügt, um gegen Code-Abfangangriffe zu schützen.

Wann zu verwenden: Jede Anwendung, bei der sich ein echter Benutzer interaktiv anmeldet.

Flow-Zusammenfassung:

  1. App generiert einen Code-Verifier und Code-Challenge
  2. Browser wird zur gehosteten Auris-Login-Seite mit dem Code-Challenge weitergeleitet
  3. Benutzer authentifiziert sich
  4. Auris leitet mit einem Autorisierungscode zurück zur App weiter
  5. App tauscht Code + Code-Verifier gegen Tokens aus

Siehe die Seite PKCE-Flow für eine vollständige Schritt-für-Schritt-Anleitung.

2. Client Credentials (M2M)

Für die Machine-to-Machine-Kommunikation, bei der kein Benutzer beteiligt ist. Ein Dienst authentifiziert sich mit seiner client_id und client_secret, um ein Zugriffstoken mit server-definierten Scopes zu erhalten.

Wann zu verwenden: Backend-Dienste, geplante Jobs, CI/CD-Pipelines, interne Microservices.

Flow-Zusammenfassung:

  1. Dienst sendet client_id und client_secret an den Token-Endpunkt
  2. Auris validiert die Anmeldedaten und stellt ein Zugriffstoken mit den erlaubten Scopes aus
  3. Dienst verwendet das Token, um geschützte APIs aufzurufen
curl -X POST https://api.altovar.net/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "m2m-service-id",
    "client_secret": "m2m-service-secret",
    "scope": "read:users manage:roles"
  }'

Das resultierende Zugriffstoken hat "type": "m2m" in seiner Payload und trägt nur die deklarierten Scopes — keine Benutzeridentität.

3. Device Authorization Grant (RFC 8628)

Für Geräte, die keinen Browser direkt öffnen können: Smart-TVs, CLI-Tools, IoT-Geräte, Spielkonsolen.

Wann zu verwenden: Eingabebeschränkte Geräte oder CLI-Tools, die den Browser des Benutzers nicht weiterleiten können.

Flow-Zusammenfassung:

  1. Gerät fordert einen Device-Code und User-Code von Auris an
  2. Auris gibt einen device_code, user_code und verification_url zurück
  3. Gerät zeigt den user_code an und bittet den Benutzer, die verification_url auf einem anderen Gerät aufzurufen
  4. Benutzer authentifiziert sich auf seinem Telefon oder Computer und genehmigt das Gerät
  5. Gerät fragt den Token-Endpunkt ab, bis der Benutzer genehmigt
  6. Token-Endpunkt gibt Tokens zurück, sobald genehmigt

4. Token Exchange (RFC 8693)

Ermöglicht den Austausch eines Tokens gegen ein anderes — wird für Impersonierungs- und Delegationsszenarien in komplexen Multi-Service-Architekturen verwendet.

Wann zu verwenden: Backend-Dienste, die im Namen eines Benutzers agieren müssen, oder Admin-Tools, die einen Benutzer zum Debugging impersonieren müssen.

Token Exchange produziert ein Zugriffstoken mit einem act-Claim, der den Akteur (den Dienst, der den Austausch durchführt) und das sub des ursprünglichen Benutzers identifiziert. Erfordert die Berechtigung impersonate:users oder delegate:tokens.

5. CIBA (Client-Initiated Backchannel Authentication)

Eine OpenID Connect-Erweiterung (CIBA, ausgesprochen “see-bah”), die es einem Client ermöglicht, die Authentifizierung für einen Benutzer ohne Browser-Weiterleitung einzuleiten. Stattdessen erhält der Benutzer eine Push-Benachrichtigung oder Out-of-Band-Nachricht und genehmigt oder lehnt die Authentifizierungsanfrage ab.

Wann zu verwenden: Call-Center-Authentifizierung, IoT-Genehmigungen, hochsichere Flows, bei denen der Benutzer auf einem separaten vertrauenswürdigen Gerät authentifiziert werden soll.

Auris unterstützt CIBA in den Modi Poll, Ping und Push.

OAuth 2.0-Endpunkte in Auris

EndpunktPfadBeschreibung
Autorisierung/api/oauth/authorizeStartet den Autorisierungscode-Flow; leitet Benutzer zum Login weiter
Token/api/auth/tokenTauscht Codes oder Anmeldedaten gegen Tokens aus
UserInfo/api/auth/validateGibt Claims für den authentifizierten Benutzer zurück
JWKS/.well-known/jwks.jsonÖffentliche Signaturschlüssel für JWT-Verifizierung
OIDC Discovery/.well-known/openid-configurationStandard-OIDC-Metadatendokument
Device Authorization/api/oauth/device-authorizeStellt Device-Code und User-Code aus

Scopes in Auris

OAuth 2.0-Scopes sind leerzeichen-getrennte Strings, die definieren, welchen Zugriff ein Token gewährt. Auris unterstützt sowohl Standard-OIDC-Scopes als auch benutzerdefinierte M2M-Scopes.

Standard-OIDC-Scopes

ScopeEnthaltene Claims
openidsub (für OIDC erforderlich)
profilename, firstName, lastName, username
emailemail, emailVerified

M2M-Scopes

M2M-Tokens verwenden benutzerdefinierte Scopes, die pro Anwendung in der Konsole definiert werden. Beispiele:

  • read:users — Lesezugriff auf Benutzerdaten
  • manage:roles — vollständiges CRUD für Rollen
  • read:audit-logs — Zugriff auf die Audit-Protokoll-API

Scopes werden am Token-Endpunkt validiert: Wenn ein Client einen Scope anfordert, der nicht in seiner Konfiguration der erlaubten Scopes aufgeführt ist, wird die Anfrage abgelehnt.

Wie Auris OAuth 2.0 implementiert

Auris basiert auf Keycloak als zugrundeliegender Identitäts-Engine, wobei Auris die Funktionalität von Keycloak erweitert und umhüllt. Die Integration funktioniert auf zwei Ebenen:

Keycloak als Basis-Engine

Keycloak übernimmt:

  • Speicherung und Verifizierung von Benutzeranmeldedaten
  • Sitzungsverwaltung und Token-Ausstellung
  • SAML- und OIDC-Federation
  • Protokollbrücken für Social-Login

Auris-Erweiterungen darüber

Auris fügt auf Keycloak auf:

  • Gehostete Login-Seiten: Vollständig gebrandete, eigene-Domain-Login-UI (Keycloaks Standard-UI wird ersetzt)
  • Actions-Engine: Benutzerdefinierte serverseitige Code-Hooks, die während Login, Registrierung und Token-Ausstellung ausgeführt werden
  • Benutzerdefinierte JWT-Claims: Pro-Anwendung konfigurierbare Claim-Injektion zur Token-Ausstellungszeit
  • PKCE-Durchsetzung: Auf der Auris-Schicht durchgesetzt (nicht optional)
  • Adaptives MFA: Risikobewertung und Step-up-Authentifizierung basierend auf IP, Gerät und Verhalten
  • FGA-Integration: Feingranulare Autorisierungsprüfungen auf Ressourcenebene, die über das rollenbasierte Modell von Keycloak hinausgehen

Wenn das Auris SDK loginWithRedirect() aufruft, konstruiert es die Autorisierungs-URL und leitet den Browser zur gehosteten Auris-Login-Seite weiter, die mit Keycloak für die eigentliche Anmeldedaten-Verifizierung koordiniert und dann Tokens über den Auris-Token-Endpunkt ausstellt.

Wenn du mit einer Standard-OIDC-Bibliothek integrierst (ohne Auris SDK), verweise die Bibliothek auf das OIDC-Discovery-Dokument unter /.well-known/openid-configuration. Standard-Bibliotheken (auth0-spa-js, oidc-client-ts, passport-openidconnect usw.) können sich automatisch aus diesem Dokument konfigurieren.

Verwandte Konzepte

Architektur