Entwicklerleitfaden für die Federated Credential Management API

Hier erfahren Sie, wie Sie FedCM für eine datenschutzfreundliche Identitätsföderation verwenden.

FedCM (Federated Credential Management) ist ein datenschutzfreundlicher Ansatz für föderierte Identitätsdienste (z. B. „Anmelden mit...“), bei dem sich Nutzer auf Websites anmelden können, ohne ihre personenbezogenen Daten an den Identitätsdienst oder die Website weiterzugeben.

Weitere Informationen zu FedCM-Anwendungsfällen, zum Nutzerfluss und zur API-Roadmap finden Sie in der Einführung in die FedCM API.

FedCM-Entwicklungsumgebung

Sie benötigen sowohl auf dem IdP als auch auf dem RP in Chrome einen sicheren Kontext (HTTPS oder localhost), um FedCM verwenden zu können.

Code in Chrome unter Android debuggen

Richte einen Server ein und führe ihn lokal aus, um Fehler in deinem FedCM-Code zu beheben. Über ein Android-Gerät, das über ein USB-Kabel mit Portweiterleitung verbunden ist, können Sie in Chrome auf diesen Server zugreifen.

Sie können die Entwicklertools für den Desktop zur Fehlerbehebung in Chrome unter Android verwenden. Folgen Sie dazu der Anleitung unter Remote-Debugging für Android-Geräte.

Drittanbieter-Cookies in Chrome blockieren

Sie können in Chrome testen, wie FedCM ohne Drittanbieter-Cookies funktioniert, bevor die Richtlinie erzwungen wird.

Wenn Sie Drittanbieter-Cookies blockieren möchten, verwenden Sie den Inkognitomodus oder wählen Sie in den Einstellungen auf dem Computer unter chrome://settings/cookies oder auf Mobilgeräten unter Einstellungen > Website-Einstellungen > Cookies die Option „Drittanbieter-Cookies blockieren“ aus.

FedCM API verwenden

Für die Einbindung in FedCM erstellen Sie eine bekannte Datei, Konfigurationsdatei und Endpunkte für die Kontenliste, die Assertion-Ausgabe und optional Client-Metadaten.

Von dort aus stellt FedCM JavaScript APIs zur Verfügung, mit denen RPs sich beim IdP anmelden können.

Bekannte Datei erstellen

Damit Tracker die API nicht missbrauchen, muss über /.well-known/web-identity von eTLD+1 des IdP eine bekannte Datei bereitgestellt werden.

Wenn die IdP-Endpunkte beispielsweise unter https://accounts.idp.example/ bereitgestellt werden, müssen sie eine bekannte Datei unter https://idp.example/.well-known/web-identity sowie eine IdP-Konfigurationsdatei bereitstellen. Hier ein Beispiel für einen bekannten Dateiinhalt:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

Die JSON-Datei muss das Attribut provider_urls mit einem Array von URLs für die IdP-Konfigurationsdatei enthalten, die als Pfadteil von configURL in navigator.credentials.get durch RPs angegeben werden können. Die Anzahl der URL-Strings im Array ist auf einen String beschränkt. Dies kann sich jedoch mit deinem Feedback in Zukunft ändern.

IdP-Konfigurationsdatei und Endpunkte erstellen

Die IdP-Konfigurationsdatei enthält eine Liste der erforderlichen Endpunkte für den Browser. IdPs hosten diese Konfigurationsdatei und die erforderlichen Endpunkte und URLs. Alle JSON-Antworten müssen mit dem Inhaltstyp application/json bereitgestellt werden.

Die URL der Konfigurationsdatei wird durch die Werte bestimmt, die für den navigator.credentials.get-Aufruf, der in einem RP ausgeführt wird, angegeben werden.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Geben Sie eine vollständige URL des Speicherorts der IdP-Konfigurationsdatei als configURL an. Wenn im RP navigator.credentials.get() aufgerufen wird, ruft der Browser die Konfigurationsdatei mit einer GET-Anfrage ohne den Header Origin oder Referer ab. Die Anfrage enthält keine Cookies und folgt keinen Weiterleitungen. Dadurch wird verhindert, dass der IdP weiß, wer die Anfrage gestellt hat und welches RP versucht, eine Verbindung herzustellen. Beispiel:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

Der Browser erwartet eine JSON-Antwort vom IdP mit den folgenden Attributen:

Property	Beschreibung
accounts_endpoint (erforderlich)	URL für den Kontoendpunkt.
client_metadata_endpoint (optional)	URL für den Client-Metadatenendpunkt.
id_assertion_endpoint (erforderlich)	URL für den Endpunkt für ID-Assertion.
disconnect (optional)	URL für den Endpunkt zum Trennen der Verbindung.
login_url (erforderlich)	Die URL der Anmeldeseite für den Nutzer, um sich beim IdP anzumelden.
branding (optional)	Objekt, das verschiedene Branding-Optionen enthält.
branding.background_color (optional)	Branding-Option, über die die Hintergrundfarbe der Schaltfläche "Weiter als..." festgelegt wird Verwenden Sie die entsprechende CSS-Syntax, also hex-color, hsl(), rgb() oder named-color.
branding.color (optional)	Branding-Option, die die Textfarbe der Schaltfläche „Weiter als...“ festlegt. Verwenden Sie die entsprechende CSS-Syntax, also hex-color, hsl(), rgb() oder named-color.
branding.icons (optional)	Brandingoption, mit der das Symbolobjekt festgelegt wird, das im Anmeldedialogfeld angezeigt wird. Das Symbolobjekt ist ein Array mit zwei Parametern: url (erforderlich): URL des Symbolbilds. SVG-Bilder werden nicht unterstützt. size (optional): Die Abmessungen des Symbols werden von der Anwendung als quadratisch und einfache Auflösung angenommen. Diese Zahl muss größer oder gleich 25 sein.

RP könnte den String in der FedCM-Dialogoberfläche über den identity.context-Wert für navigator.credentials.get() ändern, um vordefinierte Authentifizierungskontexte zu berücksichtigen. Ein optionales Attribut kann "signin" (Standardeinstellung), "signup", "use" oder "continue" sein.

Hier ist ein Beispiel für einen Antworttext vom IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Sobald der Browser die Konfigurationsdatei abgerufen hat, sendet er nachfolgende Anfragen an die IdP-Endpunkte:

Kontoendpunkt

Der Kontenendpunkt des IdP gibt eine Liste der Konten zurück, mit denen der Nutzer derzeit beim IdP angemeldet ist. Wenn der IdP mehrere Konten unterstützt, gibt dieser Endpunkt alle angemeldeten Konten zurück.

Der Browser sendet eine GET-Anfrage mit Cookies mit SameSite=None, aber ohne den client_id-Parameter, den Origin- oder den Referer-Header. Dies verhindert effektiv, dass der IdP weiß, bei welchem RP der Nutzer versucht, sich anzumelden. Beispiel:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

Nach dem Empfang der Anfrage sollte der Server Folgendes tun:

1. Prüfen Sie, ob die Anfrage einen Sec-Fetch-Dest: webidentity-HTTP-Header enthält.
2. Gleichen Sie die Sitzungs-Cookies mit den IDs der Konten ab, in denen Sie sich bereits angemeldet haben.
3. Antworten Sie mit der Liste der Konten.

Der Browser erwartet eine JSON-Antwort, die ein accounts-Attribut mit einem Array von Kontoinformationen mit folgenden Attributen enthält:

Property	Beschreibung
id (erforderlich)	Eindeutige ID des Nutzers.
name (erforderlich)	Vor- und Familienname des Nutzers.
email (erforderlich)	E-Mail-Adresse des Nutzers
given_name (optional)	Vorname des Nutzers
picture (optional)	URL des Avatarbilds des Nutzers.
approved_clients (optional)	Ein Array von RP-Client-IDs, mit denen sich der Nutzer registriert hat.
login_hints (optional)	Ein Array aller möglichen Filtertypen, die der IdP unterstützt, um ein Konto anzugeben. Das RP kann navigator.credentials.get() mit der Property loginHint aufrufen, um das angegebene Konto selektiv anzuzeigen.
domain_hints (optional)	Ein Array aller Domains, mit denen das Konto verknüpft ist. Der RP kann navigator.credentials.get() mit einer domainHint-Property aufrufen, um die Konten zu filtern.

Beispiel für Antworttext:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

Wenn der Nutzer nicht angemeldet ist, antworten Sie mit HTTP 401 (Nicht autorisiert).

Die zurückgegebene Kontenliste wird vom Browser verarbeitet und ist für den RP nicht verfügbar.

Endpunkt für Clientmetadaten

Der Client-Metadatenendpunkt des IdP gibt die Metadaten der vertrauenden Partei wie die Datenschutzerklärung und die Nutzungsbedingungen des RP zurück. RPs sollten dem IdP im Voraus Links zu ihrer Datenschutzerklärung und ihren Nutzungsbedingungen zur Verfügung stellen. Diese Links werden im Anmeldedialogfeld angezeigt, wenn sich der Nutzer noch nicht im RP beim IdP registriert hat.

Der Browser sendet eine GET-Anfrage mit dem client_id-navigator.credentials.get ohne Cookies. Beispiel:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

Nach dem Empfang der Anfrage sollte der Server Folgendes tun:

1. Bestimmen Sie den RP für client_id.
2. Antworten Sie mit den Client-Metadaten.

Zu den Attributen für den Clientmetadatenendpunkt gehören:

Property	Beschreibung
privacy_policy_url (optional)	URL der RP-Datenschutzerklärung.
terms_of_service_url (optional)	URL für RP-Nutzungsbedingungen.

Der Browser erwartet eine JSON-Antwort vom Endpunkt:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

Die zurückgegebenen Clientmetadaten werden vom Browser verarbeitet und stehen dem RP nicht zur Verfügung.

ID-Assertion-Endpunkt

Der ID-Assertion-Endpunkt des IdP gibt eine Assertion für den angemeldeten Nutzer zurück. Wenn sich der Nutzer mit einem navigator.credentials.get()-Aufruf auf einer RP-Website anmeldet, sendet der Browser eine POST-Anfrage mit Cookies mit SameSite=None und dem Inhaltstyp application/x-www-form-urlencoded an diesen Endpunkt mit den folgenden Informationen:

Property	Beschreibung
client_id (erforderlich)	Die Client-ID des RP.
account_id (erforderlich)	Die eindeutige ID des angemeldeten Nutzers.
nonce (optional)	Die Anfrage-Nonce, die von der RP bereitgestellt wird.
disclosure_text_shown	Führt zu einem String von "true" oder "false" (anstatt einem booleschen Wert). Das Ergebnis ist "false", wenn der Offenlegungstext nicht angezeigt wurde. Das ist der Fall, wenn die Client-ID des RP in der Property-Liste approved_clients der Antwort vom Kontoendpunkt enthalten war oder wenn der Browser in der Vergangenheit einen Anmeldemoment ohne approved_clients festgestellt hat.
is_auto_selected	Wenn im RP die automatische erneute Authentifizierung durchgeführt wird, gibt is_auto_selected den Wert "true" an. Andernfalls "false". Das ist hilfreich, um weitere sicherheitsrelevante Funktionen zu unterstützen. Einige Nutzer bevorzugen z. B. eine höhere Sicherheitsstufe, die eine explizite Vermittlung durch Nutzer bei der Authentifizierung erfordert. Wenn ein IdP eine Tokenanfrage ohne eine solche Vermittlung erhält, könnte er die Anfrage anders verarbeiten. Du kannst beispielsweise einen Fehlercode zurückgeben, sodass der RP die FedCM API noch einmal mit mediation: required aufrufen kann.

Beispiel für einen HTTP-Header:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

Nach dem Empfang der Anfrage sollte der Server Folgendes tun:

1. Antworten Sie auf die Anfrage mit CORS (Cross-Origin Resource Sharing).
2. Prüfen Sie, ob die Anfrage einen Sec-Fetch-Dest: webidentity-HTTP-Header enthält.
3. Gleicht den Origin-Header mit dem RP-Ursprung ab, der durch client_id bestimmt wird. Lehnen Sie sie ab, wenn sie nicht übereinstimmen.
4. Gleiche account_id mit der ID des bereits angemeldeten Kontos ab. Lehnen Sie sie ab, wenn sie nicht übereinstimmen.
5. Mit einem Token antworten. Wenn die Anfrage abgelehnt wird, antworten Sie mit einer Fehlerantwort.

Wie das Token ausgestellt wird, hängt vom IdP ab. Im Allgemeinen ist es jedoch mit Informationen wie Konto-ID, Client-ID, Ausstellerherkunft (nonce) signiert, sodass der RP prüfen kann, ob das Token echt ist.

Der Browser erwartet eine JSON-Antwort mit der folgenden Property:

Property	Beschreibung
token (erforderlich)	Ein Token ist ein String, der Anforderungen zur Authentifizierung enthält.

{
  "token": "***********"
}

Das zurückgegebene Token wird vom Browser an den RP übergeben, damit der RP die Authentifizierung validieren kann.

Fehlerantwort zurückgeben

Der id_assertion_endpoint kann auch eine „Fehler“-Antwort zurückgeben, die zwei optionale Felder enthält:

• code: Der IdP kann einen der bekannten Fehler aus der für OAuth 2.0 angegebenen Fehlerliste (invalid_request, unauthorized_client, access_denied, server_error und temporarily_unavailable) auswählen oder einen beliebigen String verwenden. Letzteres zeigt von Chrome die Fehler-UI mit einer generischen Fehlermeldung an und übergibt den Code an das RP.
• url: Gibt eine für Menschen lesbare Webseite mit Informationen zum Fehler an, um Nutzern zusätzliche Informationen zum Fehler zur Verfügung zu stellen. Dieses Feld ist für Nutzer hilfreich, da Browser in einer nativen UI keine detaillierten Fehlermeldungen ausgeben können. Dazu gehören z. B. Links für die nächsten Schritte oder Kontaktdaten des Kundenservice. Wenn Nutzer mehr über die Fehlerdetails und deren Behebung erfahren möchten, können sie die entsprechende Seite in der Browser-Benutzeroberfläche aufrufen. Die URL muss zur selben Website wie der IdP configURL gehören.

// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Endpunktverbindung trennen

Wenn IdentityCredential.disconnect() aufgerufen wird, sendet der Browser eine ursprungsübergreifende POST-Anfrage mit Cookies mit SameSite=None und dem Inhaltstyp application/x-www-form-urlencoded an diesen Endpunkt der Verbindung mit den folgenden Informationen:

Property	Beschreibung
account_hint	Ein Hinweis für das IdP-Konto.
client_id	Die Client-ID des RP.

POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

Nach dem Empfang der Anfrage sollte der Server Folgendes tun:

1. Antworten Sie auf die Anfrage mit CORS (Cross-Origin Resource Sharing).
2. Prüfen Sie, ob die Anfrage einen Sec-Fetch-Dest: webidentity-HTTP-Header enthält.
3. Gleicht den Origin-Header mit dem RP-Ursprung ab, der durch client_id bestimmt wird. Lehnen Sie sie ab, wenn sie nicht übereinstimmen.
4. Gleichen Sie account_hint mit den IDs der bereits angemeldeten Konten ab.
5. Trennen Sie das Nutzerkonto vom RP.
6. Dem Browser mit den identifizierten Nutzerkontoinformationen im JSON-Format antworten.

Eine Beispielantwort für eine JSON-Nutzlast sieht so aus:

{
  "account_id": "account456"
}

Wenn der IdP wünscht, dass der Browser alle mit dem RP verknüpften Konten trennen soll, übergeben Sie einen String, der mit keiner Konto-ID übereinstimmt, z. B. "*".

Anmelde-URL

Mit der Login Status API muss der IdP den Anmeldestatus des Nutzers an den Browser senden. Der Status könnte jedoch nicht synchron sein, z. B. wenn die Sitzung abläuft. In einem solchen Szenario kann der Browser dem Nutzer die Möglichkeit geben, sich über die URL der Anmeldeseite, die mit login_url der IDP-Konfigurationsdatei angegeben ist, dynamisch beim IdP anzumelden.

Im FedCM-Dialogfeld wird eine Nachricht angezeigt, die eine Anmeldung vorschlägt, wie in der folgenden Abbildung dargestellt.

Wenn der Nutzer auf die Schaltfläche Weiter klickt, wird im Browser ein Pop-up-Fenster für die Anmeldeseite des IdP geöffnet.

Das Dialogfeld ist ein normales Browserfenster mit eigenen Cookies. Was im Dialogfeld geschieht, hängt vom IdP ab. Es sind keine Fenster-Handles verfügbar, um eine ursprungsübergreifende Kommunikationsanfrage an die RP-Seite zu senden. Nachdem der Nutzer angemeldet ist, sollte der IdP:

• Senden Sie den Set-Login: logged-in-Header oder rufen Sie die navigator.login.setStatus("logged-in") API auf, um den Browser darüber zu informieren, dass der Nutzer angemeldet ist.
• Rufen Sie IdentityProvider.close() auf, um das Dialogfeld zu schließen.

Browser über den Anmeldestatus des Nutzers beim Identitätsanbieter informieren

Die Login Status API ist ein Mechanismus, mit dem eine Website, insbesondere ein IdP, den Browser des Nutzers über den Anmeldestatus beim IdP informiert. Mit dieser API kann der Browser unnötige Anfragen an den IdP reduzieren und potenzielle Timing-Angriffe abschwächen.

IdPs können den Anmeldestatus des Nutzers dem Browser signalisieren, indem sie einen HTTP-Header senden oder eine JavaScript API aufrufen, wenn der Nutzer beim IdP angemeldet ist oder der Nutzer von allen IdP-Konten abgemeldet ist. Für jeden IdP (identifiziert durch seine Konfigurations-URL) behält der Browser eine Drei-Status-Variable bei, die den Anmeldestatus mit den möglichen Werten logged-in, logged-out und unknown darstellt. Der Standardstatus ist unknown.

Um zu signalisieren, dass der Nutzer angemeldet ist, senden Sie einen Set-Login: logged-in-HTTP-Header in einer Navigation der obersten Ebene oder eine Anfrage für eine Unterressource derselben Website am IdP-Ursprung:

Set-Login: logged-in

Alternativ können Sie die JavaScript API navigator.login.setStatus("logged-in") über den IdP-Ursprung in der Navigation auf oberster Ebene aufrufen:

navigator.login.setStatus("logged-in")

Bei diesen Aufrufen wird der Anmeldestatus des Nutzers als logged-in erfasst. Wenn der Anmeldestatus des Nutzers auf logged-in gesetzt ist, sendet der RP, der FedCM aufruft, Anfragen an den Kontenendpunkt des IdP und zeigt dem Nutzer die verfügbaren Konten im FedCM-Dialogfeld an.

Wenn Sie signalisieren möchten, dass der Nutzer aus allen seinen Konten abgemeldet ist, senden Sie den HTTP-Header Set-Login: logged-out in einer Navigation der obersten Ebene oder einer Anfrage an eine Unterressource derselben Website am IdP-Ursprung:

Set-Login: logged-out

Alternativ können Sie die JavaScript API navigator.login.setStatus("logged-out") über den IdP-Ursprung in der Navigation auf oberster Ebene aufrufen:

navigator.login.setStatus("logged-out")

Bei diesen Aufrufen wird der Anmeldestatus des Nutzers als logged-out erfasst. Wenn der Anmeldestatus des Nutzers logged-out lautet, schlägt das Aufrufen von FedCM unbemerkt fehl, ohne eine Anfrage an den Endpunkt des IdP-Kontos zu senden.

Der Status unknown wird festgelegt, bevor der IdP ein Signal über die Login Status API sendet. Unknown wurde für eine bessere Umstellung eingeführt, da sich ein Nutzer beim Versand dieser API möglicherweise bereits beim IdP angemeldet hat. Der IdP hat möglicherweise nicht die Möglichkeit, dies dem Browser zu signalisieren, wenn FedCM zum ersten Mal aufgerufen wird. In diesem Fall sendet Chrome eine Anfrage an den Kontenendpunkt des IdP und aktualisiert den Status anhand der Antwort vom Kontenendpunkt:

• Wenn der Endpunkt eine Liste aktiver Konten zurückgibt, aktualisieren Sie den Status auf logged-in und öffnen Sie das FedCM-Dialogfeld, um diese Konten anzuzeigen.
• Wenn der Endpunkt keine Konten zurückgibt, aktualisieren Sie den Status auf logged-out und schlagen Sie den FedCM-Aufruf fehl.

Nutzern die Anmeldung über einen dynamischen Anmeldevorgang ermöglichen

Auch wenn der IdP dem Browser weiterhin den Anmeldestatus des Nutzers mitteilt, ist dieser möglicherweise nicht synchron, z. B. wenn die Sitzung abläuft. Der Browser versucht, eine Anfrage mit Anmeldedaten an den Kontoendpunkt zu senden, wenn der Anmeldestatus logged-in lautet. Der Server gibt jedoch keine Konten zurück, da die Sitzung nicht mehr verfügbar ist. In einem solchen Szenario kann der Browser den Nutzer über ein Pop-up-Fenster dynamisch beim IdP anmelden.

Mit dem Identitätsanbieter bei der vertrauenden Partei anmelden

Sobald die Konfiguration und die Endpunkte des IdP verfügbar sind, können RPs navigator.credentials.get() aufrufen, um anzufordern, dass sich Nutzer beim IdP beim RP anmelden können.

Bevor Sie die API aufrufen, müssen Sie prüfen, ob FedCM im Browser des Nutzers verfügbar ist. Um zu prüfen, ob FedCM verfügbar ist, umschließen Sie Ihre FedCM-Implementierung mit diesem Code:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

So fordern Sie z. B. an, dass Nutzer sich vom RP aus beim IdP anmelden dürfen:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Das Attribut providers verwendet ein Array von IdentityProvider-Objekten mit den folgenden Attributen:

Property	Beschreibung
configURL (erforderlich)	Ein vollständiger Pfad der IdP-Konfigurationsdatei.
clientId (erforderlich)	Die vom IdP ausgestellte Client-ID des RP.
nonce (optional)	Ein zufälliger String, um sicherzustellen, dass die Antwort auf diese bestimmte Anfrage ausgegeben wird. Verhindert Replay-Angriffe.
loginHint (optional)	Durch Angabe eines der von Kontoendpunkten bereitgestellten login_hints-Werte wird im FedCM-Dialogfeld das angegebene Konto selektiv angezeigt.
domainHint (optional)	Durch Angabe eines der von Kontoendpunkten bereitgestellten domain_hints-Werte wird im FedCM-Dialogfeld das angegebene Konto selektiv angezeigt.

Der Browser behandelt die Anwendungsfälle für Registrierung und Anmeldung unterschiedlich, je nachdem, ob approved_clients in der Antwort vom Endpunkt der Kontenliste vorhanden ist. Im Browser wird kein Offenlegungstext „To weiter mit ...“ angezeigt, wenn sich der Nutzer bereits beim RP angemeldet hat.

Der Registrierungsstatus hängt davon ab, ob die folgenden Bedingungen erfüllt sind oder nicht:

• Wenn approved_clients die clientId der RP enthält.
• Der Browser merkt sich, dass sich der Nutzer bereits für den RP angemeldet hat.

Wenn das RP navigator.credentials.get() aufruft, finden die folgenden Aktivitäten statt:

1. Der Browser sendet Anfragen und ruft mehrere Dokumente ab:
   1. Die bekannte Datei und eine IdP-Konfigurationsdatei, die Endpunkte deklarieren.
   2. Eine Kontoliste:
   3. Optional: URLs für die Datenschutzerklärung und die Nutzungsbedingungen des RP, die vom Client-Metadatenendpunkt abgerufen werden.
2. Im Browser werden die Liste der Konten, mit denen sich der Nutzer anmelden kann, sowie die Nutzungsbedingungen und die Datenschutzerklärung, sofern verfügbar, angezeigt.
3. Wenn der Nutzer ein Konto für die Anmeldung auswählt, wird eine Anfrage an den Endpunkt für die ID-Assertion an den IdP gesendet, um ein Token abzurufen.
4. Der RP kann das Token validieren, um den Nutzer zu authentifizieren.

RPs sollten Browser unterstützen, die FedCM nicht unterstützen. Daher sollten Nutzer einen vorhandenen Nicht-FedCM-Anmeldeprozess verwenden können. Bis Drittanbieter-Cookies vollständig eingestellt werden, sollte dies kein Problem sein.

Sobald das Token vom RP-Server validiert wurde, kann der RP den Nutzer registrieren oder ihm die Anmeldung und das Starten einer neuen Sitzung ermöglichen.

Login Hint API

Nachdem sich der Nutzer angemeldet hat, wird er manchmal von der vertrauenden Partei (RP) zur erneuten Authentifizierung aufgefordert. Der Nutzer ist sich aber möglicherweise nicht sicher, welches Konto er verwendet hat. Wenn das RP angeben kann, mit welchem Konto er sich anmelden soll, ist es für den Nutzer einfacher, ein Konto auszuwählen.

RPs können selektiv ein bestimmtes Konto anzeigen, indem sie navigator.credentials.get() mit dem Attribut loginHint mit einem der login_hints-Werte aufrufen, die vom Endpunkt der Kontenliste abgerufen werden, wie im folgenden Codebeispiel gezeigt:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

Wenn keine Konten mit dem loginHint übereinstimmen, wird im FedCM-Dialogfeld eine Anmeldeaufforderung angezeigt, mit der sich der Nutzer bei einem IdP-Konto anmelden kann, das dem von RP angeforderten Hinweis entspricht. Wenn der Nutzer auf die Eingabeaufforderung tippt, wird ein Pop-up-Fenster mit der in der Konfigurationsdatei angegebenen Anmelde-URL geöffnet. An den Link werden dann der Anmeldehinweis und die Abfrageparameter für Domain-Hinweise angehängt.

Domain Hint API

Es gibt Fälle, in denen das RP bereits weiß, dass sich nur Konten, die mit einer bestimmten Domain verknüpft sind, bei der Website anmelden dürfen. Dies kommt insbesondere in Unternehmen vor, in denen der Zugriff auf die Website auf eine Unternehmensdomain beschränkt ist. Für eine bessere Nutzererfahrung ermöglicht die FedCM API, im RP nur die Konten anzuzeigen, die zur Anmeldung im RP verwendet werden können. Dadurch werden Szenarien verhindert, in denen ein Nutzer versucht, sich mit einem Konto außerhalb der Unternehmensdomain im RP anzumelden, und nur dann später eine Fehlermeldung erhalten (oder das Stummschalten, wenn die Anmeldung nicht funktioniert hat), da der richtige Kontotyp nicht verwendet wurde.

RPs können selektiv nur übereinstimmende Konten anzeigen, indem sie navigator.credentials.get() mit dem Attribut domainHint mit einem der domain_hints-Werte aufrufen, die vom Endpunkt der Kontenliste abgerufen werden, wie im folgenden Codebeispiel gezeigt:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

Wenn keine Konten mit dem domainHint übereinstimmen, wird im FedCM-Dialogfeld eine Anmeldeaufforderung angezeigt, mit der sich der Nutzer bei einem IdP-Konto anmelden kann, das dem von RP angeforderten Hinweis entspricht. Wenn der Nutzer auf die Eingabeaufforderung tippt, wird ein Pop-up-Fenster mit der in der Konfigurationsdatei angegebenen Anmelde-URL geöffnet. An den Link werden dann der Anmeldehinweis und die Abfrageparameter für Domain-Hinweise angehängt.

Fehlermeldung anzeigen

Manchmal ist der IdP aus legitimen Gründen nicht in der Lage, ein Token auszustellen, z. B. wenn der Client nicht autorisiert ist oder der Server vorübergehend nicht verfügbar ist. Wenn der IdP eine „Fehler“-Antwort zurückgibt, kann der RP diese abfangen. Außerdem benachrichtigt Chrome den Nutzer über eine Browser-UI mit den vom IdP bereitgestellten Fehlerinformationen.

try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

Nutzer nach der ersten Einwilligung automatisch neu authentifizieren

Mit der automatischen erneuten Authentifizierung von FedCM (kurz: „auto-reauthn“) können sich Nutzer automatisch neu authentifizieren, wenn sie nach der ersten Authentifizierung mit FedCM zurückkommen. „Erste Authentifizierung“ bedeutet hier, dass der Nutzer ein Konto erstellt oder sich auf der Website des RPs anmeldet, indem er zum ersten Mal in derselben Browserinstanz im Anmeldedialog von FedCM auf die Schaltfläche „Weiter als...“ tippt.

Während die explizite Nutzererfahrung sinnvoll ist, bevor der Nutzer das föderierte Konto erstellt hat, um das Tracking zu verhindern (eines der Hauptziele von FedCM), ist es unnötig umständlich, nachdem der Nutzer dies einmal durchlaufen hat: Nachdem der Nutzer die Berechtigung erteilt hat, Kommunikation zwischen dem RP und dem IdP zu ermöglichen, gibt es keinen Datenschutz- oder Sicherheitsvorteil, wenn bereits eine andere explizite Bestätigung durch den Nutzer bestätigt wurde.

Mit der automatischen erneuten Authentifizierung ändert der Browser sein Verhalten abhängig von der Option, die Sie beim Aufrufen von navigator.credentials.get() für mediation angeben.

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

Das mediation ist eine Property in der Credential Management API. Es verhält sich wie für PasswordCredential und FederatedCredential und wird teilweise auch von PublicKeyCredential unterstützt. Die -Eigenschaft akzeptiert die folgenden vier Werte:

• 'optional'(Standard): Wenn möglich, wird automatisch eine erneute Authentifizierung durchgeführt. Ist dies nicht der Fall, ist eine Vermittlung erforderlich. Wir empfehlen, diese Option auf der Anmeldeseite auszuwählen.
• 'required': Zum Fortfahren ist immer eine Vermittlung erforderlich, z. B. das Klicken auf die Schaltfläche „Weiter“ in der Benutzeroberfläche. Wählen Sie diese Option aus, wenn Ihre Nutzer jedes Mal ausdrücklich eine Berechtigung erteilen müssen, wenn sie authentifiziert werden müssen.
• 'silent': Wenn möglich, schlägt die automatische Authentifizierung automatisch fehl, ohne dass eine Vermittlung erforderlich ist. Wir empfehlen, diese Option auf anderen Seiten als der speziellen Anmeldeseite auszuwählen, auf denen die Nutzer angemeldet bleiben sollen, z. B. auf einer Artikelseite auf einer Versandwebsite oder einer Artikelseite auf einer Nachrichtenwebsite.
• 'conditional': Wird für WebAuthn verwendet und ist derzeit nicht für FedCM verfügbar.

Bei diesem Aufruf erfolgt die automatische erneute Authentifizierung unter den folgenden Bedingungen:

• FedCM ist verfügbar. Der Nutzer hat beispielsweise in den Einstellungen FedCM weder global noch für RP deaktiviert.
• Der Nutzer hat nur ein Konto mit der FedCM API verwendet, um sich in diesem Browser auf der Website anzumelden.
• Der Nutzer ist mit diesem Konto beim IdP angemeldet.
• In den letzten 10 Minuten wurde keine automatische Authentifizierung durchgeführt.
• Die RP hat nach der vorherigen Anmeldung navigator.credentials.preventSilentAccess() nicht aufgerufen.

Wenn diese Bedingungen erfüllt sind, wird versucht, den Nutzer automatisch noch einmal zu authentifizieren, sobald der FedCM-navigator.credentials.get() aufgerufen wird.

Wenn mediation: optional, kann die automatische erneute Authentifizierung aus Gründen, die nur dem Browser bekannt sind, nicht verfügbar sein. Das RP kann anhand des Attributs isAutoSelected prüfen, ob eine automatische erneute Authentifizierung durchgeführt wird.

So können Sie die API-Leistung bewerten und die Nutzerfreundlichkeit entsprechend verbessern. Ist sie nicht verfügbar, wird der Nutzer möglicherweise aufgefordert, sich mit expliziter Nutzervermittlung anzumelden. Dies ist ein Ablauf mit mediation: required.

Vermittlung mit preventSilentAccess() erzwingen

Die automatische Neu-Authentifizierung von Nutzern direkt nach der Abmeldung würde nicht zu einer sehr guten Nutzererfahrung beitragen. Aus diesem Grund hat FedCM nach einer automatischen Authentifizierung einen 10-minütigen Pausierungszeitraum, um dieses Verhalten zu verhindern. Das bedeutet, dass die automatische erneute Authentifizierung maximal alle 10 Minuten erfolgt, sofern sich der Nutzer nicht innerhalb von 10 Minuten wieder anmeldet. Das RP sollte navigator.credentials.preventSilentAccess() aufrufen, um den Browser explizit aufzufordern, die automatische erneute Authentifizierung zu deaktivieren, wenn sich ein Nutzer explizit vom RP abmeldet, z. B. durch Klicken auf eine Abmeldeschaltfläche.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

Nutzer können die automatische erneute Authentifizierung in den Einstellungen deaktivieren

Nutzer können die automatische Authentifizierung über das Einstellungsmenü deaktivieren:

• Rufen Sie in der Desktopversion von Chrome chrome://password-manager/settings > Automatisch anmelden auf.
• Öffnen Sie in Android Chrome Einstellungen > Passwortmanager > Tippen Sie rechts oben auf ein Zahnradsymbol > Automatische Anmeldung.

Durch Deaktivieren der Ein/Aus-Schaltfläche kann der Nutzer die automatische Authentifizierung vollständig deaktivieren. Diese Einstellung wird geräteübergreifend gespeichert und synchronisiert, wenn der Nutzer auf der Chrome-Instanz in einem Google-Konto angemeldet ist und die Synchronisierung aktiviert ist.

IdP vom RP trennen

Wenn sich ein Nutzer zuvor mit dem IdP über FedCM im RP angemeldet hat, wird die Beziehung vom Browser lokal als Liste der verbundenen Konten gespeichert. Das RP kann durch Aufrufen der Funktion IdentityCredential.disconnect() eine Trennung der Verbindung initiieren. Diese Funktion kann von einem RP-Frame auf oberster Ebene aufgerufen werden. Das RP muss einen configURL, den clientId, den er unter dem IdP verwendet, und ein accountHint übergeben, damit die Verbindung zum IdP getrennt wird. Ein Kontohinweis kann ein beliebiger String sein, solange der Endpunkt der Verknüpfung das Konto identifizieren kann. Das kann z. B. eine E-Mail-Adresse oder Nutzer-ID sein, die nicht unbedingt mit der Konto-ID übereinstimmt, die der Endpunkt der Kontoliste angegeben hat:

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

IdentityCredential.disconnect() gibt ein Promise zurück. Dieses Promise kann aus folgenden Gründen eine Ausnahme ausgeben:

• Der Nutzer hat sich nicht mit dem IdP über FedCM im RP angemeldet.
• Die API wird von einem iFrame ohne FedCM-Berechtigungsrichtlinie aufgerufen.
• Die configURL ist ungültig oder der Endpunkt zum Trennen der Verbindung fehlt.
• Die Prüfung der Content Security Policy (CSP) schlägt fehl.
• Es gibt eine ausstehende Anfrage zum Trennen der Verbindung.
• Der Nutzer hat FedCM in den Browsereinstellungen deaktiviert.

Wenn der Endpunkt zum Trennen der Verbindung des IdP eine Antwort zurückgibt, werden der RP und der IdP vom Browser getrennt und das Promise wird aufgelöst. Die ID der nicht verbundenen Konten wird in der Antwort vom Endpunkt der Trennung angegeben.

FedCM in einem ursprungsübergreifenden iFrame aufrufen

FedCM kann in einem ursprungsübergreifenden iFrame mithilfe einer identity-credentials-get-Berechtigungsrichtlinie aufgerufen werden, wenn der übergeordnete Frame dies zulässt. Dazu müssen Sie das Attribut allow="identity-credentials-get" so an das iFrame-Tag anhängen:

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Sie können sich das an einem Beispiel ansehen.

Wenn der übergeordnete Frame die Ursprünge auf den Aufruf von FedCM beschränken möchte, senden Sie optional einen Permissions-Policy-Header mit einer Liste zulässiger Ursprünge.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

Weitere Informationen zur Funktionsweise der Berechtigungsrichtlinie finden Sie unter Browserfunktionen mit Berechtigungsrichtlinie steuern.