Passkey-Registrierung starten

POST /fapi/v1/me/passkeys/registration-options · wird vom Sign-in-Host der Umgebung aufgerufen

Startet eine WebAuthn-Registrierung für den angemeldeten Benutzer aus dem Konto-Portal und gibt die Optionen zurück, die an navigator.credentials.create übergeben werden. Schließen Sie die Registrierung mit POST /fapi/v1/me/passkeys ab. Die Registrierung ist 5 Minuten gültig, kann nur einmal abgeschlossen werden und nur von der Sitzung, die sie gestartet hat. Erforderlich ist das Cookie __Host-idp_session des angemeldeten Benutzers. Fehlt das Cookie, ist es abgelaufen oder widerrufen, gibt der Endpunkt 401 unauthenticated zurück. Eine First-Party-Anwendung auf einem anderen Origin kann stattdessen ihr Front-API-Zugriffstoken senden (Authorization: DPoP <token> mit einem DPoP-Proof; siehe Front-API-Zugriffstoken).

Die Sitzung muss für einen Passkey in den letzten 10 Minuten verifiziert worden sein, für einen Sicherheitsschlüssel in den letzten 5 Minuten. Hat der Benutzer bereits einen zweiten Faktor, muss die Sitzung außerdem mit einem zweiten Faktor (urn:idp:acr:mfa) geöffnet worden sein: Ein neuer Passkey kann die Vertrauensstufe der Sitzung, die ihn hinzufügt, nicht erhöhen.

Anfrage

Header:

Header Erforderlich Beschreibung
Idp-Client ja SDK-Kennung.
Origin ja Muss exakt https://<sign-in host> sein.
Content-Type ja application/json.

Body:

Feld Typ Erforderlich Beschreibung
role string ja passkey: Anmeldedaten, die eigenständig anmelden (erfordert, dass die Passkey-Anmeldung in der Umgebung aktiviert ist). security_key: Anmeldedaten, die nur als zweiter Faktor verwendet werden (erfordert, dass der zweite Faktor Sicherheitsschlüssel aktiviert ist).

Antwort

200 OK:

{
  "ceremony_id": "CQAAAAAAAAAAAAAAAAAAAA",
  "options": {"publicKey": {"challenge": "…", "rp": {"id": "example.keenauth.app", "name": "Example"}, "user": {"id": "…", "name": "ada@example.org", "displayName": "ada@example.org"}, "pubKeyCredParams": [], "timeout": 300000, "excludeCredentials": [], "authenticatorSelection": {}, "attestation": "none", "extensions": {"credProps": true}}}
}

Übergeben Sie options.publicKey an PublicKeyCredential.parseCreationOptionsFromJSON und das Ergebnis an navigator.credentials.create. excludeCredentials listet die Anmeldedaten des Benutzers für diese vertrauende Partei auf, damit derselbe Authenticator nicht zweimal registriert wird.

Fehler

Status Code Wann
400 malformed_request Der Body ist kein gültiges JSON.
400 unknown_field Der Body enthält ein anderes Feld als role.
401 unauthenticated Kein gültiges Sitzungs-Cookie.
401 step_up_required Die Sitzung ist zu alt oder ein zweiter Faktor ist erforderlich; verifizieren Sie erneut mit max_age (und gegebenenfalls acr_values) aus dem Header WWW-Authenticate.
403 origin_not_allowed Origin fehlt oder ist falsch.
403 no_allowed_method Die Umgebung erlaubt diese role nicht.
409 credential_limit_reached Der Benutzer hat bereits die maximale Anzahl an Passkeys und Sicherheitsschlüsseln.
413 payload_too_large Der Body ist zu groß.
415 unsupported_media_type Content-Type ist nicht application/json.
422 validation_failed role fehlt oder ist weder passkey noch security_key.
422 aaguid_not_allowed Die Authenticator-Allowlist der Umgebung ist ungültig; die Registrierung ist blockiert, bis sie korrigiert wird.

Beispiel

curl -X POST https://example.keenauth.app/fapi/v1/me/passkeys/registration-options \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"role": "passkey"}'

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Anmeldedaten. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Senden Sie keine besonderen Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung) in einem Feld.