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:
|
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:
- Prüfen Sie, ob die Anfrage einen
Sec-Fetch-Dest: webidentity
-HTTP-Header enthält. - Gleichen Sie die Sitzungs-Cookies mit den IDs der Konten ab, in denen Sie sich bereits angemeldet haben.
- 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:
- Bestimmen Sie den RP für
client_id
. - 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:
- Antworten Sie auf die Anfrage mit CORS (Cross-Origin Resource Sharing).
- Prüfen Sie, ob die Anfrage einen
Sec-Fetch-Dest: webidentity
-HTTP-Header enthält. - Gleicht den
Origin
-Header mit dem RP-Ursprung ab, der durchclient_id
bestimmt wird. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - Gleiche
account_id
mit der ID des bereits angemeldeten Kontos ab. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - 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
undtemporarily_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 IdPconfigURL
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:
- Antworten Sie auf die Anfrage mit CORS (Cross-Origin Resource Sharing).
- Prüfen Sie, ob die Anfrage einen
Sec-Fetch-Dest: webidentity
-HTTP-Header enthält. - Gleicht den
Origin
-Header mit dem RP-Ursprung ab, der durchclient_id
bestimmt wird. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - Gleichen Sie
account_hint
mit den IDs der bereits angemeldeten Konten ab. - Trennen Sie das Nutzerkonto vom RP.
- 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 dienavigator.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
dieclientId
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:
- Der Browser sendet Anfragen und ruft mehrere Dokumente ab:
- Die bekannte Datei und eine IdP-Konfigurationsdatei, die Endpunkte deklarieren.
- Eine Kontoliste:
- Optional: URLs für die Datenschutzerklärung und die Nutzungsbedingungen des RP, die vom Client-Metadatenendpunkt abgerufen werden.
- 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.
- 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.
- 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 Authentifizierung 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.