# 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: ```http POST /oauth2/token Content-Type: application/x-www-form-urlencoded DPoP: grant_type=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 `/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): ```http GET /fapi/v1/me/sessions Idp-Client: Authorization: DPoP DPoP: ``` - `htu` ist `https://` 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 ` 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 …`.