Entwicklerleitfaden für die Federated Credential Management API

Informationen zum Verwenden von FedCM für die datenschutzfreundliche Identitätsföderation.

FedCM (Federated Credential Management) ist ein datenschutzfreundlicher Ansatz für föderierte Identitätsdienste (z. B. „Über Google anmelden“), mit dem sich Nutzer auf Websites anmelden können, ohne ihre personenbezogenen Daten mit dem Identitätsdienst oder der Website zu teilen.

Weitere Informationen zu FedCM-Anwendungsfällen, Nutzerflüssen und API-Roadmaps finden Sie unter Einführung in die FedCM API.

FedCM-Entwicklungsumgebung

Für die Verwendung von FedCM ist sowohl beim IdP als auch beim RP in Chrome ein sicherer Kontext (HTTPS oder localhost) erforderlich.

Code in Chrome auf Android debuggen

Richten Sie einen Server lokal ein und führen Sie ihn aus, um Fehler in Ihrem FedCM-Code zu beheben. Sie können auf diesen Server zugreifen, wenn Sie ein Android-Gerät mit einem USB-Kabel mit Portweiterleitung an Ihren Computer angeschlossen haben.

Du kannst die Entwicklertools auf dem Computer verwenden, um Fehler in Chrome unter Android zu beheben. Folge dazu der Anleitung unter Remote-Fehlerbehebung für Android-Geräte.

Drittanbieter-Cookies in Chrome blockieren

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

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

FedCM API verwenden

Sie integrieren sich in FedCM, indem Sie eine bekannte Datei, eine Konfigurationsdatei und Endpunkte für die Kontoliste, die Ausstellung von Bescheinigungen und optional Clientmetadaten erstellen.

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

.well-known-Datei erstellen

Um zu verhindern, dass Tracker die API missbrauchen, muss eine .well-known-Datei von /.well-known/web-identity der eTLD+1 des IdP ausgeliefert 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 der IdP-Konfigurationsdatei enthalten, die von RPs als Pfadteil von configURL in navigator.credentials.get angegeben werden können. Die Anzahl der URL-Strings im Array ist auf einen begrenzt. Dies kann sich jedoch in Zukunft durch Ihr Feedback ändern.

IdP-Konfigurationsdatei und Endpoints 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 an den navigator.credentials.get-Aufruf, der auf einem RP ausgeführt wird, übergeben 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 als configURL eine vollständige URL des Speicherorts der IdP-Konfigurationsdatei an. Wenn navigator.credentials.get() auf dem RP aufgerufen wird, ruft der Browser die Konfigurationsdatei mit einer GET-Anfrage ohne den Origin- oder Referer-Header ab. Die Anfrage enthält keine Cookies und folgt keinen Weiterleitungen. So kann der IdP nicht herausfinden, wer die Anfrage gestellt hat und welcher RP eine Verbindung herstellen möchte. 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:

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

Hier ist ein Beispiel für einen Antworttext des 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
    }]
  }
}

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

Endpunkt für Konten

Der Kontenendpunkt des IdP gibt eine Liste der Konten zurück, in 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 client_id-Parameter, Origin-Header oder Referer-Header. So kann der IdP nicht herausfinden, bei welchem RP sich der Nutzer anmelden möchte. Beispiel:

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

Nach Erhalt der Anfrage sollte der Server Folgendes tun:

1. Prüfen Sie, ob die Anfrage einen Sec-Fetch-Dest: webidentity-HTTP-Header enthält.
2. Ordnen Sie die Sitzungscookies den IDs der bereits angemeldeten Konten zu.
3. Antworten Sie mit der Liste der Konten.

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

Beispiel für einen 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, antworte mit HTTP 401 (Nicht autorisiert).

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

Clientmetadatenendpunkt

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

Der Browser sendet eine GET-Anfrage mit der 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 Erhalt der Anfrage sollte der Server Folgendes tun:

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

Zu den Eigenschaften für den Endpunkt für Clientmetadaten gehören:

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 verwendet und sind für den RP nicht verfügbar.

ID-Assertion-Endpunkt

Der ID-Assertion-Endpunkt des IdP gibt eine Assertion für den angemeldeten Nutzer zurück. Wenn sich der Nutzer über den 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:

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 Erhalt der Anfrage sollte der Server Folgendes tun:

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

Wie das Token ausgestellt wird, liegt im Ermessen des Identitätsanbieters. Im Allgemeinen wird es jedoch mit Informationen wie der Konto-ID, der Client-ID, dem Ausstellerursprung und nonce signiert, damit die RP die Echtheit des Tokens überprüfen kann.

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

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

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

Fehlerantwort zurückgeben

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

• code: Der IdP kann einen der bekannten Fehler aus der in OAuth 2.0 angegebenen Fehlerliste (invalid_request, unauthorized_client, access_denied, server_error und temporarily_unavailable) auswählen oder einen beliebigen String verwenden. In letzterem Fall rendert Chrome die Fehler-UI mit einer generischen Fehlermeldung und übergibt den Code an das RP.
• url: Hier wird eine für Menschen lesbare Webseite mit Informationen zum Fehler angegeben, 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 ausführlichen Fehlermeldungen ausgeben können. Zum Beispiel Links für die nächsten Schritte, Kontaktdaten des Kundenservice usw. Wenn ein Nutzer mehr über die Fehlerdetails und deren Behebung erfahren möchte, kann er die entsprechende Seite über die Browser-UI aufrufen. Die URL muss der Website des Identitätsanbieters configURL entsprechen.

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

Endpunkt trennen

Durch Aufrufen von IdentityCredential.disconnect() 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 die Verbindung trennt. Folgende Informationen werden zurückgegeben:

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 Erhalt der Anfrage sollte der Server Folgendes tun:

1. Antworten Sie mit CORS (Cross-Origin Resource Sharing) auf die Anfrage.
2. Prüfe, ob die Anfrage einen Sec-Fetch-Dest: webidentity-HTTP-Header enthält.
3. Vergleiche den Origin-Header mit dem vom client_id bestimmten RP-Ursprung. 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 von der RP.
6. Sie antworten dem Browser mit den identifizierten Nutzerkontoinformationen im JSON-Format.

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

{
  "account_id": "account456"
}

Wenn der IdP möchte, dass der Browser die Verbindung zu allen Konten aufhebt, die mit dem RP verknüpft sind, muss er stattdessen einen String übergeben, der mit keiner Konto-ID übereinstimmt, z. B. "*".

Anmelde-URL

Mit der Login Status API muss der Identitätsanbieter den Anmeldestatus des Nutzers an den Browser weitergeben. Der Status kann jedoch nicht mehr aktuell sein, z. B. wenn die Sitzung abläuft. In einem solchen Szenario kann der Browser den Nutzer dynamisch über die Anmeldeseiten-URL in der login_url der IdP-Konfigurationsdatei beim IdP anmelden.

Im FedCM-Dialogfeld wird eine Meldung angezeigt, in der eine Anmeldung vorgeschlagen wird (siehe Abbildung unten).

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

Das Dialogfeld ist ein normales Browserfenster mit eigenen Cookies. Was im Dialogfeld passiert, bleibt dem IdP überlassen. Es sind keine Fenster-Handles verfügbar, um eine ursprungsübergreifende Kommunikationsanfrage an die RP-Seite zu senden. Nach der Anmeldung des Nutzers sollte der IdP:

• Sende den Set-Login: logged-in-Header oder rufe 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.

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

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

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 wenn der Nutzer von allen IdP-Konten abgemeldet wird. Für jeden IdP (identifiziert durch seine Konfigurations-URL) behält der Browser eine Variable mit drei Status bei, die den Anmeldestatus mit den möglichen Werten logged-in, logged-out und unknown darstellt. Der Standardstatus ist unknown.

Um anzuzeigen, dass der Nutzer angemeldet ist, senden Sie einen Set-Login: logged-in-HTTP-Header in einer Navigation auf oberster Ebene oder eine Anfrage für eine Subressource auf 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 einer Navigation der obersten Ebene aufrufen:

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

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

Um zu signalisieren, dass der Nutzer von allen seinen Konten abgemeldet ist, senden Sie den HTTP-Header Set-Login: logged-out in einer Navigation der obersten Ebene oder einer Unterressourcenanfrage auf 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 einer Navigation der obersten Ebene aufrufen:

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

Bei diesen Aufrufen wird der Anmeldestatus des Nutzers als logged-out aufgezeichnet. Wenn der Anmeldestatus des Nutzers logged-out ist, schlägt der Aufruf von FedCM ohne Meldung fehl, ohne dass eine Anfrage an den Kontoendpunkt des IdP gesendet wird.

Der Status unknown wird festgelegt, bevor der Identitätsanbieter ein Signal über die Login Status API sendet. Unknown wurde für eine bessere Umstellung eingeführt, da sich ein Nutzer möglicherweise bereits beim IdP angemeldet hat, als diese API versendet wurde. Der IdP hat möglicherweise nicht die Möglichkeit, dies dem Browser zum Zeitpunkt des ersten FedCM-Aufrufs zu signalisieren. In diesem Fall sendet Chrome eine Anfrage an den Kontoendpunkt des Identitätsanbieters und aktualisiert den Status basierend auf der Antwort vom Kontoendpunkt:

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

Nutzer über einen dynamischen Anmeldevorgang anmelden

Auch wenn der IdP weiterhin den Anmeldestatus des Nutzers an den Browser mitteilt, könnte er nicht synchronisiert sein, z. B. wenn die Sitzung abläuft. Der Browser versucht, eine Anfrage mit Anmeldedaten an den Endpunkt „accounts“ zu senden, wenn der Anmeldestatus logged-in ist. 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 dynamisch über ein Pop-up-Fenster beim IdP anmelden.

Mit dem Identitätsanbieter bei der vertrauenden Seite anmelden

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

Bevor Sie die API aufrufen, müssen Sie bestätigen, dass [FedCM im Browser des Nutzers verfügbar ist]. Wenn Sie prüfen möchten, ob FedCM verfügbar ist, fügen Sie diesen Code in Ihre FedCM-Implementierung ein:

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

So fordern Sie an, dass Nutzer sich über den RP beim IdP anmelden können:

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

Die providers-Eigenschaft nimmt ein Array von IdentityProvider-Objekten mit den folgenden Eigenschaften an:

Der Browser verarbeitet die Anwendungsfälle für die Registrierung und Anmeldung unterschiedlich, je nachdem, ob approved_clients in der Antwort vom Endpunkt der Kontoliste vorhanden ist. Der Browser zeigt keinen Offenlegungstext „Weiter mit…“ an, wenn sich der Nutzer bereits für die RP registriert hat.

Der Registrierungsstatus wird anhand der folgenden Bedingungen ermittelt:

• Wenn approved_clients den clientId des RP enthält.
• Wenn der Browser merkt, dass sich der Nutzer bereits beim RP registriert hat.

Wenn der RP navigator.credentials.get() aufruft, werden die folgenden Aktivitäten ausgeführt:

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

RPs müssen Browser unterstützen, die FedCM nicht unterstützen. Daher sollten Nutzer einen vorhandenen Anmeldevorgang verwenden können, der nicht auf FedCM basiert. Bis Drittanbieter-Cookies vollständig eingestellt werden, sollte das kein Problem darstellen.

Sobald das Token vom RP-Server validiert wurde, kann die RP den Nutzer registrieren oder ihm ermöglichen, sich anzumelden und eine neue Sitzung zu starten.

Login Hint API

Nachdem sich der Nutzer angemeldet hat, fordert die vertrauende Partei (RP) den Nutzer manchmal auf, sich noch einmal zu authentifizieren. Der Nutzer ist sich jedoch möglicherweise nicht sicher, welches Konto er verwendet hat. Wenn im RP angegeben werden kann, mit welchem Konto sich anmelden soll, ist es für den Nutzer einfacher, ein Konto auszuwählen.

RPs können selektiv ein bestimmtes Konto darstellen, indem sie navigator.credentials.get() mit der Property loginHint und 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 der loginHint übereinstimmen, wird im FedCM-Dialogfeld eine Anmeldeaufforderung angezeigt, über die sich der Nutzer in einem IdP-Konto anmelden kann, das mit dem vom RP angeforderten Hinweis übereinstimmt. Wenn der Nutzer auf die Aufforderung tippt, wird ein Pop-up-Fenster mit der in der Konfigurationsdatei angegebenen Log-in-URL geöffnet. An den Link werden dann der Anmeldehinweis und die Suchparameter für den Domainhinweis angehängt.

Domain Hint API

Es gibt Fälle, in denen der RP bereits weiß, dass sich nur Konten, die mit einer bestimmten Domain verknüpft sind, auf der Website anmelden dürfen. Dies kommt besonders häufig in Unternehmensszenarien vor, in denen die Website, auf die zugegriffen wird, auf eine Unternehmensdomain beschränkt ist. Für eine bessere Nutzerfreundlichkeit kann der RP über die FedCM API nur die Konten anzeigen, mit denen er sich beim RP anmelden kann. So wird verhindert, dass ein Nutzer versucht, sich mit einem Konto außerhalb der Unternehmensdomain beim RP anzumelden, und später eine Fehlermeldung erhält (oder keine Reaktion, weil die Anmeldung nicht funktioniert hat), weil nicht der richtige Kontotyp verwendet wurde.

RPs können selektiv nur übereinstimmende Konten anzeigen, indem sie navigator.credentials.get() mit der Eigenschaft domainHint und einem der domain_hints-Werte aufrufen, die vom Endpunkt für die Kontoliste abgerufen wurden, 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 der domainHint übereinstimmen, wird im FedCM-Dialogfeld eine Anmeldeaufforderung angezeigt, mit der sich der Nutzer bei einem IdP-Konto anmelden kann, das dem vom RP angeforderten Hinweis entspricht. Wenn der Nutzer auf die Aufforderung 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 Suchparameter für den Domainhinweis angehängt.

Fehlermeldung anzeigen

Manchmal kann der IdP aus legitimen Gründen kein Token ausstellen, z. B. wenn der Client nicht autorisiert ist oder der Server vorübergehend nicht verfügbar ist. Wenn der Identitätsanbieter eine „Fehler“-Antwort zurückgibt, kann der RP diese abfangen. Chrome benachrichtigt den Nutzer außerdem, indem eine Browser-Benutzeroberfläche mit den vom Identitätsanbieter bereitgestellten Fehlerinformationen angezeigt wird.

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 Erstauthentifizierung automatisch noch einmal authentifizieren

Mit der automatischen erneuten FedCM-Authentifizierung (kurz: „automatische erneute Authentifizierung“) kann sich der Nutzer automatisch noch einmal authentifizieren, wenn er nach der anfänglichen Authentifizierung mit FedCM zurückkehrt. „Die erste Authentifizierung“ bedeutet hier, dass der Nutzer ein Konto erstellt oder sich auf der Website des RP anmeldet, indem er zum ersten Mal in derselben Browserinstanz im Anmeldedialogfeld von FedCM auf die Schaltfläche Weiter als... tippt.

Die explizite Nutzererfahrung ist sinnvoll, bevor der Nutzer das föderierte Konto erstellt hat, um das Tracking zu verhindern (eines der Hauptziele von FedCM). Nach dem ersten Durchlauf ist sie jedoch unnötig umständlich: Nachdem der Nutzer die Berechtigung zur Kommunikation zwischen dem RP und dem IdP erteilt hat, hat es keine Vorteile in Bezug auf Datenschutz oder Sicherheit, eine weitere explizite Nutzerbestätigung für etwas zu erzwingen, das er bereits zuvor akzeptiert hat.

Bei der automatischen erneuten Authentifizierung ändert sich das Verhalten des Browsers 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;

mediation ist ein Attribut in der Credential Management API. Es verhält sich genau wie PasswordCredential und FederatedCredential und wird teilweise auch von PublicKeyCredential unterstützt. Die Property kann die folgenden vier Werte haben:

• 'optional' (Standard): Automatische erneute Autorisierung, falls möglich, andernfalls Vermittlung erforderlich. Wir empfehlen, diese Option auf der Anmeldeseite auszuwählen.
• 'required': Es ist immer eine Vermittlung erforderlich, um fortzufahren, z. B. das Klicken auf die Schaltfläche „Weiter“ in der Benutzeroberfläche. Wählen Sie diese Option aus, wenn Ihre Nutzer jedes Mal, wenn sie authentifiziert werden müssen, ausdrücklich die Berechtigung erteilen sollen.
• 'silent': wenn möglich, automatische erneute Authentifizierung; schlägt ohne Benachrichtigung fehl, ohne dass eine Vermittlung erforderlich ist. Wir empfehlen diese Option auf Seiten auszuwählen, die nicht die Anmeldeseite sind, auf denen Nutzer aber angemeldet bleiben sollen, z. B. auf einer Artikelseite einer Versandwebsite oder auf einer Artikelseite 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 FedCM in den Einstellungen beispielsweise weder global noch für die 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 Identitätsanbieter angemeldet.
• Die automatische erneute Authentifizierung wurde in den letzten 10 Minuten nicht durchgeführt.
• Der RP hat nach der vorherigen Anmeldung nicht navigator.credentials.preventSilentAccess() aufgerufen.

Wenn diese Bedingungen erfüllt sind, wird der Nutzer automatisch neu authentifiziert, sobald die FedCM-navigator.credentials.get() aufgerufen wird.

Wenn mediation: optional, ist die automatische erneute Authentifizierung möglicherweise nicht verfügbar, wenn nur der Browser weiß. Der RP kann prüfen, ob die automatische erneute Authentifizierung durchgeführt wird, indem das Attribut isAutoSelected geprüft wird.

So können Sie die API-Leistung bewerten und die UX 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 erneute Authentifizierung von Nutzern direkt nach der Abmeldung würde nicht zu einer sehr guten Nutzererfahrung beitragen. Aus diesem Grund gibt es bei FedCM nach einer automatischen erneuten Autorisierung eine 10-minütige Ruhezeit, um dieses Verhalten zu verhindern. Das bedeutet, dass die automatische erneute Authentifizierung maximal alle 10 Minuten erfolgt, es sei denn, der Nutzer meldet sich innerhalb von 10 Minuten wieder an. Der RP sollte navigator.credentials.preventSilentAccess() aufrufen, um explizit die automatische erneute Authentifizierung vom Browser anzufordern, 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 Autorisierung in den Einstellungen deaktivieren.

Nutzer können die automatische erneute Autorisierung im Menü „Einstellungen“ deaktivieren:

• Rufe in Chrome auf einem Computer chrome://password-manager/settings > „Automatisch anmelden“ auf.
• Öffne in Android Chrome Einstellungen > Passwortmanager > Tippe oben rechts auf ein Zahnrad > Automatisch anmelden.

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

Verbindung zwischen dem IdP und dem RP trennen

Wenn sich ein Nutzer zuvor über den Identitätsanbieter über FedCM beim RP angemeldet hat, wird die Beziehung lokal im Browser als Liste der verbundenen Konten gespeichert. Der RP kann eine Verbindungsunterbrechung durch Aufrufen der Funktion IdentityCredential.disconnect() initiieren. Diese Funktion kann von einem RP-Frame auf oberster Ebene aufgerufen werden. Der RP muss eine configURL, die clientId, die er beim IdP verwendet, und eine accountHint übergeben, damit die Verbindung zum IdP getrennt wird. Ein Kontohinweis kann ein beliebiger String sein, solange der Disconnect-Endpunkt das Konto identifizieren kann, z. B. eine E-Mail-Adresse oder Nutzer-ID, die nicht unbedingt mit der Konto-ID übereinstimmen muss, die der Kontolisten-Endpunkt 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 Promise zurück. Dieses Versprechen kann aus folgenden Gründen eine Ausnahme auslösen:

• Der Nutzer hat sich nicht über den IdP über FedCM beim RP angemeldet.
• Die API wird innerhalb eines iFrames ohne FedCM-Berechtigungsrichtlinie aufgerufen.
• Die configURL ist ungültig oder der Disconnect-Endpunkt fehlt.
• Die CSP-Prüfung (Content Security Policy) ist fehlgeschlagen.
• Es gibt eine ausstehende Anfrage zum Trennen einer Verbindung.
• Der Nutzer hat FedCM in den Browsereinstellungen deaktiviert.

Wenn der Disconnect-Endpunkt des IdP eine Antwort zurückgibt, werden die RP und der IdP im Browser getrennt und das Promise wird aufgelöst. Die ID der getrennten Konten ist in der Antwort vom Disconnect-Endpunkt angegeben.

FedCM innerhalb eines ursprungsübergreifenden iFrames aufrufen

FedCM kann mithilfe einer identity-credentials-get-Berechtigungsrichtlinie von einem ursprungsübergreifenden iFrame aus aufgerufen werden, wenn der übergeordnete Frame dies zulässt. Fügen Sie dazu das allow="identity-credentials-get"-Attribut wie unten gezeigt an das iFrame-Tag an:

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

In diesem Beispiel sehen Sie, wie das funktioniert.

Optional kann der übergeordnete Frame die Ursprünge einschränken, die FedCM aufrufen dürfen. Senden Sie dazu eine Permissions-Policy-Überschrift mit einer Liste der zulässigen 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 der Berechtigungsrichtlinie steuern.