Erweitertes OAuth 2.0 API

Auris unterstützt mehrere erweiterte OAuth 2.0- und OpenID Connect-Erweiterungen über den Standard-Autorisierungscode-Flow mit PKCE hinaus. Diese Funktionen sind für Enterprise- und spezielle Authentifizierungsszenarien konzipiert:

• Device Authorization (RFC 8628) — für eingabebeschränkte Geräte wie CLIs, Smart-TVs und IoT
• Token Exchange (RFC 8693) — für Impersonierung und Delegation zwischen Diensten
• DPoP (RFC 9449) — für Sender-gebundene Tokens, die resistent gegen Token-Diebstahl sind
• CIBA (Client-Initiated Backchannel Authentication) — für Authentifizierung, die von einem Backend-Dienst ohne Browser-Interaktion eingeleitet wird
• Adaptives MFA / Risikobewertung — für dynamische Step-up-Authentifizierung basierend auf Risikobewertung

Alle erweiterten OAuth-Funktionen müssen pro Anwendung in der Auris-Konsole unter Anwendungen > [App] > Erweitertes OAuth aktiviert werden.

Device Authorization (RFC 8628)

Der Device Authorization Grant ermöglicht Geräten, die keinen Browser anzeigen können (CLIs, Smart-TVs, IoT-Geräte, Kioske), Benutzer zu authentifizieren. Das Gerät zeigt einen kurzen Benutzercode und eine Verifizierungs-URL an; der Benutzer besucht die URL auf einem separaten Gerät (Telefon, Laptop) und gibt den Code zur Genehmigung ein.

Anfrage-Body

{
  "client_id": "cli-app-client-id",
  "scope": "openid profile email"
}

Erfolgsantwort

{
  "ok": true,
  "data": {
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.altovar.net/hosted/device",
    "verification_uri_complete": "https://api.altovar.net/hosted/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
  }
}

Fehlercodes

Token-Abfrage

Nach der Anzeige des Benutzercodes fragt das Gerät den Token-Endpunkt im angegebenen Intervall ab:

Anfrage-Body

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "cli-app-client-id"
}

Ausstehende Antwort (Benutzer hat noch nicht genehmigt)

{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "The user has not yet approved the request. Continue polling."
  }
}

Verlangsamungsantwort (zu häufige Abfrage)

{
  "ok": false,
  "error": {
    "code": "SLOW_DOWN",
    "message": "Polling too frequently. Increase interval by 5 seconds."
  }
}

Erfolgsantwort (Benutzer genehmigt)

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Fehlercodes während der Abfrage

Benutzerverifizierungsseite

Auris stellt eine gehostete Verifizierungsseite unter /hosted/device bereit, auf der der Benutzer:

1. Den 8-stelligen Benutzercode eingibt (oder über verification_uri_complete mit vorausgefülltem Code ankommt)
2. Sich mit einer beliebigen konfigurierten Methode authentifiziert (Passwort, SSO, Magic Link, 2FA)
3. Die Gerät-Autorisierungsanfrage genehmigt
4. Einen Bestätigungsbildschirm sieht und den Tab schließen kann

Token Exchange (RFC 8693)

Token Exchange ermöglicht es einem Dienst, ein Token gegen ein anderes auszutauschen — entweder zur Impersonierung eines Benutzers (als dieser handeln) oder zur Delegation des Zugriffs (im Namen von ihm handeln, während der ursprüngliche Betreff erhalten bleibt). Dies ist für Microservice-Architekturen unerlässlich, bei denen ein API-Gateway nachgelagerte Dienste mit unterschiedlichen Token-Scopes aufrufen muss.

Anfrage-Body — Impersonierung

Bei der Impersonierung wird das Subject vollständig ersetzt. Das resultierende Token hat den Zielbenutzer als sub-Claim. Verwende dies, wenn ein Administrator zum Debugging als Benutzer agieren muss.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "impersonation",
  "target_user_id": "usr_target123"
}

Anfrage-Body — Delegation

Bei der Delegation bleibt das ursprüngliche Subject erhalten und ein act-(Actor-)Claim wird dem resultierenden Token hinzugefügt. Der nachgelagerte Dienst kann sowohl sehen, für wen das Token ist, als auch wer in seinem Namen agiert.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "delegation"
}

Erfolgsantwort — Impersonierung

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

Die JWT-Payload des impersonierten Tokens hat "sub": "usr_target123", wobei die ursprüngliche Identität des impersonierenden Benutzers in den Audit-Protokollen erfasst wird.

Erfolgsantwort — Delegation

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

Die JWT-Payload des delegierten Tokens enthält einen act-Claim:

{
  "sub": "usr_original_user",
  "act": {
    "sub": "usr_acting_service"
  },
  "scope": "read:users"
}

Fehlercodes

DPoP — Sender-gebundene Tokens (RFC 9449)

Demonstration of Proof-of-Possession (DPoP) bindet Tokens an einen bestimmten Client, indem bei jeder Anfrage ein kryptografischer Nachweis erforderlich ist. Selbst wenn ein DPoP-gebundenes Token gestohlen wird, kann es ohne den entsprechenden privaten Schlüssel nicht verwendet werden.

Funktionsweise von DPoP

1. Der Client generiert ein Schlüsselpaar (typischerweise EC P-256 oder RSA) und bewahrt den privaten Schlüssel sicher auf.
2. Bei jeder Anfrage erstellt der Client ein signiertes DPoP-Proof-JWT, das die HTTP-Methode, URL und eine eindeutige jti enthält.
3. Der Server validiert den Nachweis, extrahiert den JWK-Thumbprint und bindet das ausgestellte Token an diesen Schlüssel.
4. Nachfolgende API-Aufrufe müssen sowohl das DPoP-Token als auch einen frischen DPoP-Nachweis enthalten, der mit demselben Schlüssel signiert ist.

DPoP-gebundene Tokens anfordern

Füge einen DPoP-Header bei jeder Token-Anfrage ein (Login, Aktualisierung, Autorisierungscode-Austausch):

POST /api/auth/token HTTP/1.1
Content-Type: application/json
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly95b3VyLWF1cmlzLWRvbWFpbi5jb20vYXBpL2F1dGgvdG9rZW4iLCJpYXQiOjE3MDg1MjEyMDAsImp0aSI6InVuaXF1ZS1pZC0xMjMifQ.signature

DPoP-Proof-JWT-Struktur

Header:

{
  "alg": "ES256",
  "typ": "dpop+jwt",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "..."
  }
}

Payload:

{
  "htm": "POST",
  "htu": "https://api.altovar.net/api/auth/token",
  "iat": 1708521200,
  "jti": "unique-id-123",
  "nonce": "server-provided-nonce"
}

Token-Antwort mit DPoP

Wenn ein DPoP-Nachweis enthalten ist, ist das Antwort-Token DPoP-gebunden:

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "tokenType": "DPoP",
    "expiresIn": 900
  }
}

Beachte, dass tokenType "DPoP" statt "Bearer" ist. Die JWT des Zugriffstokens enthält einen cnf-(Confirmation-)Claim mit dem JWK-Thumbprint:

{
  "sub": "usr_abc123",
  "cnf": {
    "jkt": "JWK_THUMBPRINT_BASE64URL"
  }
}

Nonce-Verwaltung

Der Server kann eine Nonce für Replay-Schutz erfordern. Wenn er dies tut, enthält die Antwort:

DPoP-Nonce: eyJhbGciOiJIUzI1NiJ9...

Füge diese Nonce in nachfolgende DPoP-Nachweise ein. Wenn eine Anfrage ohne erforderliche Nonce eingeht, gibt der Server 400 mit einem use_dpop_nonce-Fehler und einer frischen Nonce im Header zurück.

Fehlercodes

CIBA — Client-Initiated Backchannel Authentication

CIBA ermöglicht es einem Backend-Dienst, die Authentifizierung für einen Benutzer zu initiieren, ohne dass der Benutzer mit einer Browser-Weiterleitung interagieren muss. Stattdessen erhält der Benutzer eine Benachrichtigung (Push, SMS oder E-Mail) und genehmigt die Anfrage auf seinem Gerät.

Dies ist nützlich für Szenarien wie Call-Center-Authentifizierung (“Ich rufe von Ihrer Bank an, bitte genehmigen Sie die Anmeldung auf Ihrem Telefon”) oder Point-of-Sale-Transaktionen.

Anfrage-Body

{
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret",
  "scope": "openid profile",
  "login_hint": "[email protected]",
  "binding_message": "Approve login for Order #12345",
  "requested_expiry": 300
}

Erfolgsantwort

{
  "ok": true,
  "data": {
    "auth_req_id": "ciba_req_abc123def456",
    "expires_in": 300,
    "interval": 5
  }
}

Benachrichtigungsmodi

CIBA unterstützt drei Benachrichtigungszustellungsmodi, die pro Anwendung konfiguriert werden:

CIBA-Token-Abfrage

Im poll-Modus fragt der Dienst den Token-Endpunkt ab:

{
  "grant_type": "urn:openid:params:grant-type:ciba",
  "auth_req_id": "ciba_req_abc123def456",
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret"
}

Die Abfrageantworten folgen demselben Muster wie beim Device Authorization:

• AUTHORIZATION_PENDING während des Wartens auf Benutzergenehmigung
• SLOW_DOWN bei zu häufiger Abfrage
• EXPIRED_TOKEN bei Ablauf der Anfrage
• ACCESS_DENIED wenn der Benutzer die Anfrage abgelehnt hat
• Vollständige Token-Antwort bei Genehmigung

Fehlercodes

Risikobewertung und adaptives MFA

Auris führt bei jedem Authentifizierungsversuch eine automatische Risikobewertung durch. Der Risikoscore wird aus fünf gewichteten Faktoren berechnet und bestimmt, ob zusätzliche Authentifizierungsschritte (Step-up-MFA) erforderlich sind.

Risikobewertungsfaktoren

Risikoniveaus: LOW (0-30), MEDIUM (31-60), HIGH (61-80), CRITICAL (81-100).

Wenn der Risikoscore konfigurierte Schwellenwerte überschreitet, fordert Auris den Benutzer automatisch mit Step-up-MFA auf, bevor Tokens ausgestellt werden. Die acr-(Authentication Context Class Reference) und amr-(Authentication Methods References-)Claims in der JWT spiegeln das tatsächlich erreichte Authentifizierungsniveau wider.

Abfrageparameter

Erfolgsantwort

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "risk_abc123",
        "userId": "usr_def456",
        "score": 72,
        "level": "HIGH",
        "factors": {
          "ipReputation": { "score": 85, "isVpn": true, "isProxy": false },
          "deviceTrust": { "score": 50, "isNewDevice": true },
          "geoAnomaly": { "score": 90, "distance": 5200, "timeSinceLastLogin": 1800 },
          "behavior": { "score": 60, "unusualTime": true },
          "actionSensitivity": { "score": 75 }
        },
        "actionTaken": "step_up_mfa",
        "ipAddress": "203.0.113.42",
        "country": "CN",
        "city": "Beijing",
        "createdAt": "2025-02-18T03:45:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 156, "totalPages": 8 }
  }
}

Erfolgsantwort

{
  "ok": true,
  "data": [
    {
      "id": "rule_abc123",
      "name": "Block known VPN ranges",
      "condition": {
        "field": "ipReputation.isVpn",
        "operator": "equals",
        "value": true
      },
      "action": "block",
      "scoreModifier": 40,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Anfrage-Body

{
  "name": "Require MFA for new countries",
  "condition": {
    "field": "geoAnomaly.isNewCountry",
    "operator": "equals",
    "value": true
  },
  "action": "step_up_mfa",
  "scoreModifier": 30,
  "isActive": true
}

Verfügbare Bedingungsfelder: ipReputation.isVpn, ipReputation.isProxy, ipReputation.isDatacenter, deviceTrust.isNewDevice, geoAnomaly.isNewCountry, geoAnomaly.distance, behavior.unusualTime, behavior.failedAttempts.

Verfügbare Operatoren: equals, not_equals, greater_than, less_than, contains, in.

Erfolgsantwort

{
  "ok": true,
  "data": {
    "id": "rule_def456",
    "name": "Require MFA for new countries",
    "condition": {
      "field": "geoAnomaly.isNewCountry",
      "operator": "equals",
      "value": true
    },
    "action": "step_up_mfa",
    "scoreModifier": 30,
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Anfrage-Body

{
  "name": "Require MFA for new countries (aktualisiert)",
  "scoreModifier": 50,
  "isActive": true
}

Erfolgsantwort

{
  "ok": true,
  "data": { "deleted": true }
}

ACR und AMR in Tokens

Wenn adaptives MFA eine Step-up-Authentifizierung auslöst, enthält die ausgestellte JWT acr- und amr-Claims, die nachgelagerte Dienste zur Überprüfung der Authentifizierungsstärke verwenden können:

{
  "sub": "usr_abc123",
  "acr": "urn:auris:acr:mfa",
  "amr": ["pwd", "otp"],
  "iat": 1708521200,
  "exp": 1708522100
}

Ressourcenserver können für sensible Operationen ein Mindest-acr-Niveau erfordern, indem sie die JWT-Claims vor der Anfrageverarbeitung prüfen.

Berechtigungsreferenz

Verwandte Themen

• DPoP (Proof of Possession) — Funktionsweise der DPoP-Proof-Validierung
• Device Authorization Flow — Details zum Device-Flow-Protokoll
• CIBA (Backchannel Auth) — CIBA-Protokollarchitektur
• Token Exchange (RFC 8693) — Token-Exchange-Protokolldetails
• DPoP implementieren — Schritt-für-Schritt-DPoP-Integration
• Device Authorization Flow — Device-Flow-Integrationshandbuch
• CIBA-Leitfaden — CIBA-Integrationsanleitung
• Token Exchange — Leitfaden für Impersonierung und Delegation
• Erweitertes OAuth2 — Erweiterte OAuth2-Funktionen über die Konsole konfigurieren