OAuth 2.0- und OpenID-Connect-Endpunkte

Status: planned. Diese Seite beschreibt die Protokolloberfläche jeder KeenAuth-Umgebung, wie sie im Plan (§13) festgelegt ist. Die Endpunkte werden in Phase 2 entwickelt und sind in einer gehosteten Umgebung noch nicht verfügbar. Details können sich vor der allgemeinen Verfügbarkeit noch ändern.

Jede Umgebung ist ein eigener OAuth-2.0-Autorisierungsserver und OpenID-Connect-Provider. Die Endpunkte gehören nicht zur Management-API: Sie liegen auf dem Umgebungs-Host https://<environment-slug>.<region>.keenauth.app oder auf Ihrer verifizierten eigenen Domain. In der Tabelle ist <issuer> der Issuer der Umgebung, also der Wert von issuer im Discovery-Dokument.

Endpunkte

<login host> ist jede Anmelde-Domain der Umgebung: der Standard-Host oder eine hinzugefügte eigene Domain. Das Discovery-Dokument wird nur auf dem Issuer-Host ausgeliefert. Auf einem anderen Anmelde-Host liefert /.well-known/openid-configuration den Status 404 mit der Issuer-URL im Body.

Grant-Typen

Implicit Flows (response_type=token und alles, was id_token enthält), der Resource-Owner-Password-Credentials-Grant und Hybrid-Response-Typen werden nicht unterstützt, weder jetzt noch später. RFC 9700 untersagt die ersten beiden.

Geräteautorisierung

Ein Gerät ohne Browser startet den Ablauf mit POST <issuer>/oauth2/device_authorization. Nur Anwendungen vom Typ device oder native, die den Device-Grant ausdrücklich aufführen, können ihn verwenden. Die Antwort enthält einen device_code, einen user_code und eine Verifizierungsadresse. Die Person öffnet die Adresse auf einem anderen Gerät, meldet sich an und genehmigt die Anfrage. Währenddessen fragt das Gerät den Token-Endpunkt mit grant_type=urn:ietf:params:oauth:grant-type:device_code ab. Der user_code hat 8 Zeichen und wird als XXXX-XXXX angezeigt. Ein Gerätecode ist 10 Minuten gültig und funktioniert nur einmal. Das Gerät fragt höchstens alle 5 Sekunden ab; schnellere Abfragen werden mit slow_down beantwortet, was das Intervall um 5 Sekunden verlängert. Die verification_uri lautet https://<login host>/u/device. Vor der Genehmigung werden der Person die Anwendung, die angefragten Scopes und das Land des Geräts angezeigt, das die Anfrage gestartet hat.

Sicherheitsregeln

Die Umgebung folgt ohne Ausnahme dem OAuth 2.0 Security Best Current Practice (RFC 9700):

• Die Redirect-URI muss einer registrierten URI Byte für Byte entsprechen. Platzhalter gibt es nicht.
• PKCE akzeptiert nur S256; plain wird immer abgelehnt. PKCE ist für öffentliche Clients erforderlich und für jede Anwendung standardmäßig aktiviert. Eine vertrauliche web-Anwendung kann PKCE in ihren Einstellungen deaktivieren, aber nur, wenn die Umgebung in diesem Fall weiterhin nonce verlangt.
• Die offiziellen SDKs senden einen 128-Bit-state und einen nonce und prüfen beide bei der Rückkehr.
• Ein Autorisierungscode ist 60 Sekunden gültig und funktioniert nur einmal. Die Vorlage eines bereits verwendeten Codes liefert invalid_grant und widerruft die Refresh-Tokens sowie das Access-Token, das die erste Verwendung erzeugt hat.
• Pushed Authorization Requests halten die Anfrageparameter aus der Adressleiste des Browsers heraus. Sie sind in jedem Tarif verfügbar; die Einstellung require_par macht sie für eine Anwendung oder die gesamte Umgebung verpflichtend.
• Refresh-Tokens werden bei jeder Verwendung rotiert, und die Erkennung von Wiederverwendung widerruft die Familie.
• DPoP (RFC 9449) bindet ein Access-Token an einen Schlüssel, den der Client hält. Informationen zur Prüfung gebundener Token in Ihrer API finden Sie unter Token in Ihrer API prüfen.

Sitzungen und Abmeldung

Nach einer erfolgreichen Anmeldung hält die Umgebung eine einzige Single-Sign-On-Sitzung in einem HttpOnly-Cookie auf dem Anmelde-Host vor. Anwendungen derselben Umgebung nutzen diese Sitzung wieder, sodass eine zweite Anwendung kein Passwort erneut abfragt, außer ihre Richtlinie verlangt eine stärkere oder neuere Authentifizierung. Ihr Code sieht das Cookie nie; er sieht nur die Autorisierungsantwort.

Der Endpunkt für das Sitzungsende (OpenID Connect RP-Initiated Logout 1.0) beendet diese Sitzung, widerruft die zugehörigen Refresh-Tokens und benachrichtigt die Anwendungen, die eine Back-Channel-Logout-Adresse registriert haben. Um die Sitzungen einer Person aus Ihrem Backend aufzulisten oder zu widerrufen, verwenden Sie die Sitzungs-Endpunkte der Management-API.

Hat sich die Person über eine Unternehmensverbindung angemeldet, fügen Sie der Anfrage zum Sitzungsende federated=true hinzu, damit sie auch beim Identitätsanbieter abgemeldet wird. Die Sitzung hier endet zuerst; danach wechselt der Browser zur Abmeldung beim Identitätsanbieter (SAML Single Logout oder der End-Session-Endpunkt des OpenID-Providers) und kehrt zur post_logout_redirect_uri zurück. Das geschieht nur, wenn für die Verbindung die Abmeldung beim Identitätsanbieter aktiviert ist und der Provider eine Logout-Adresse veröffentlicht. Andernfalls, oder wenn der Provider nicht erreichbar ist, funktioniert die Anfrage so, als wäre der Parameter nicht angegeben. Die Abmeldung beim Identitätsanbieter kann auch die anderen Anwendungen der Person beenden, die diesen Identitätsanbieter nutzen.