Zugriffstoken für die Front API

Die Konto-Endpunkte der Front API (/fapi/v1/me…, /fapi/v1/verifications… und /fapi/v1/organizations…) akzeptieren zwei Arten der Authentifizierung:

das Cookie __Host-idp_session des Benutzers auf dem Anmelde-Host der Umgebung (die gehosteten Konto-Seiten verwenden dieses);
ein Zugriffstoken für die Front API, für eine First-Party-Anwendung, die auf einem anderen Origin läuft (eine Single-Page-App oder eine native App).

Token abrufen

Fordern Sie das Token beim Token-Endpunkt für die Front API als Ressource an (RFC 8707), bei einem Austausch des Autorisierungscodes oder bei einer Aktualisierung:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
DPoP: <proof>

grant_type=refresh_token&refresh_token=<refresh token>&client_id=app_01j9...&resource=https%3A%2F%2Facme.keenauth.app%2Ffapi

Der Wert ist der Issuer der Umgebung, gefolgt von /fapi. Die Anfrage wird nur akzeptiert, wenn:

die Anwendung eine aktive First-Party-Anwendung ist (andernfalls invalid_target);
die Anfrage einen DPoP-Proof enthält (andernfalls invalid_dpop_proof);
die Grant zu einer Anmeldesitzung gehört und bei einer Aktualisierung das Refresh-Token an DPoP gebunden ist (andernfalls invalid_target).

Nur das Zugriffstoken ändert sich. Seine Audience ist <issuer>/fapi, es enthält nur die OpenID-Scopes der Grant (openid, profile, email, phone, offline_access), es hat dieselbe Lebensdauer wie ein Userinfo-Token und ist an den Schlüssel des Proofs gebunden. Die Grant selbst, ihr Refresh-Token und ihre Scopes bleiben unverändert; eine Aktualisierung rotiert das Refresh-Token wie üblich.

Konto-Endpunkte aufrufen

Senden Sie das Token mit dem Schema DPoP und einem neuen Proof für jede Anfrage (RFC 9449):

GET /fapi/v1/me/sessions
Idp-Client: <SDK identifier>
Authorization: DPoP <access token>
DPoP: <proof with htm, htu, iat, jti, ath>

htu ist https://<sign-in host> plus der Pfad, ohne die Abfrage. ath ist der Base64url-kodierte SHA-256-Hash des Zugriffstokens.
Das Cookie wird nicht gelesen. Die Anfrage wirkt auf die Sitzung, für die das Token ausgestellt wurde; endet diese Sitzung, funktioniert das Token nicht mehr.
Eine browserseitige Anfrage von einem anderen Origin muss von einem der erlaubten Web-Origins der Anwendung stammen. Cross-Origin-Anfragen übermitteln nie Anmeldedaten.
Eine sensible Änderung erfordert weiterhin eine aktuelle Anmeldung. Die Antwort 401 step_up_required enthält dann WWW-Authenticate: DPoP error="insufficient_user_authentication", …, max_age=300.

Fehler

Status	Code	Wann
400	`malformed_request`	Mehr als ein Header `Authorization` oder einer, der nicht `DPoP <token>` lautet.
401	`unauthenticated`	Das Token ist ungültig, abgelaufen oder widerrufen, hat eine andere Audience, ist nicht an DPoP gebunden, oder seine Sitzung oder Anwendung ist nicht mehr aktiv.
401	`invalid_dpop_proof`	Der Proof ist ungültig oder wurde mit einem anderen Schlüssel signiert.
401	`use_dpop_nonce`	Senden Sie einen neuen Proof mit dem Nonce aus dem Header `DPoP-Nonce`.
403	`origin_not_allowed`	Der Origin der Seite ist nicht einer der erlaubten Web-Origins der Anwendung.

Jede Antwort 401 enthält eine Challenge WWW-Authenticate: DPoP ….