FedCM (Federated Credential Management) ist ein datenschutzfreundlicher Ansatz für föderierte Identitätsdienste (z. B. „Über… anmelden“), mit dem sich Nutzer auf Websites anmelden können, ohne ihre personenbezogenen Daten mit dem Identitätsdienst oder der Website zu teilen.
Die FedCM-Implementierung umfasst mehrere wichtige Schritte sowohl für den IdP (Identity Provider) als auch für die RP (Relying Party).
IdPs müssen die folgenden Schritte ausführen, um FedCM zu implementieren:
- Erstellen Sie eine .well-known-Datei.
- Erstellen Sie eine Konfigurationsdatei.
- Erstellen Sie die folgenden Endpunkte:
- Informieren Sie den Browser über den Anmeldestatus des Nutzers.
Publisher müssen die folgenden Schritte ausführen, um FedCM auf ihrer Website zu aktivieren:
- FedCM-Endpunkte müssen auf der Website des RP zulässig sein.
- Verwende die FedCM JavaScript API, um die Nutzerauthentifizierung zu initiieren.
- Metadaten (z. B. URLs zu Datenschutzerklärung und Nutzungsbedingungen) an den Identitätsanbieter weitergeben
- [Optional] Du kannst die Nutzerfreundlichkeit anpassen, indem du einen UX-Modus auswählst, Anmeldedaten oder Domainhinweise angibst, benutzerdefinierte Parameter übergibst, spezifische Nutzerinformationen anforderst, eine benutzerdefinierte Fehlermeldung angibst oder festlegst, wie Nutzer neu authentifiziert werden sollen.
FedCM als IdP implementieren
Weitere Informationen zur Implementierung von FedCM auf Seiten des Identitätsanbieters
.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.
Die bekannte Datei kann die folgenden Properties enthalten:
| Attribut | Erforderlich | Beschreibung |
|---|---|---|
provider_urls
|
erforderlich | Array von Pfaden zu IdP-Konfigurationsdateien. Wird ignoriert (ist aber trotzdem erforderlich), wenn accounts_endpoint und login_url angegeben sind. |
accounts_endpoint
|
empfohlen, erfordert login_url |
URL für den Endpunkt „Konten“. So ist die Unterstützung mehrerer Konfigurationen möglich, solange für jede Konfigurationsdatei dieselbe login_url- und accounts_endpoint-URL verwendet wird.Hinweis: Der Parameter wird ab Chrome 132 unterstützt. |
login_url
|
empfohlen, erfordert accounts_endpoint |
Die URL der Anmeldeseite, über die sich der Nutzer beim IdP anmelden kann. So ist die Unterstützung mehrerer Konfigurationen möglich, solange in jeder Konfigurationsdatei dieselbe login_url und accounts_endpoint verwendet wird.Hinweis: Der Parameter wird ab Chrome 132 unterstützt. |
Wenn die IdP-Endpunkte beispielsweise unter https://accounts.idp.example/ bereitgestellt werden, müssen sie eine .well-known-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"]
}
Identitätsanbieter können mehrere Konfigurationsdateien für einen Identitätsanbieter aufnehmen, indem sie accounts_endpoint und login_url in der bekannten Datei angeben.
Diese Funktion kann in folgenden Fällen nützlich sein:
- Ein Identitätsanbieter muss mehrere unterschiedliche Test- und Produktionskonfigurationen unterstützen.
- Ein Identitätsanbieter muss unterschiedliche Konfigurationen pro Region unterstützen (z. B.
eu-idp.exampleundus-idp.example).
Um mehrere Konfigurationen zu unterstützen (z. B. um zwischen Test- und Produktionsumgebung zu unterscheiden), muss der Identitätsanbieter accounts_endpoint und login_url angeben:
{
// This property is required, but will be ignored when IdP supports
// multiple configs (when `accounts_endpoint` and `login_url` are
// specified), as long as `accounts_endpoint` and `login_url` in
// that config file match those in the well-known file.
"provider_urls": [ "https://idp.example/fedcm.json" ],
// Specify accounts_endpoint and login_url properties to support
// multiple config files.
// Note: The accounts_endpoint and login_url must be identical
// across all config files. Otherwise,
// the configurations won't be supported.
"accounts_endpoint": "https://idp.example/accounts",
"login_url": "https://idp.example/login"
}
IdP-Konfigurationsdatei und Endpoints erstellen
Die IdP-Konfigurationsdatei enthält eine Liste der erforderlichen Endpunkte für den Browser. IdPs müssen eine oder mehrere Konfigurationsdateien sowie die erforderlichen Endpunkte und URLs hosten. Alle JSON-Antworten müssen mit dem Inhaltstyp application/json ausgeliefert werden.
Die URL der Konfigurationsdatei wird durch die Werte bestimmt, die für den navigator.credentials.get()-Aufruf angegeben werden, der auf einem RP ausgeführt wird.
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
Der RP gibt die URL der Konfigurationsdatei an den FedCM API-Aufruf weiter, damit sich der Nutzer anmelden kann:
// Executed on RP's side:
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
// To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
configURL: 'https://accounts.idp.example/fedcm.json',
clientId: '********',
});
const { token } = credential;
Der Browser ruft 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 Identitätsanbieter muss einen Konfigurationsendpunkt implementieren, der mit einer JSON-Antwort antwortet. Das JSON-Objekt enthält die folgenden Eigenschaften:
| Attribut | Beschreibung |
|---|---|
accounts_endpoint (erforderlich) |
URL für den Kontenendpunkt. |
accounts.include (optional)
|
Benutzerdefinierter String für das Kontolabel, der angibt, welche Konten bei Verwendung dieser Konfigurationsdatei zurückgegeben werden sollen, z. B. "accounts": {"include": "developer"}.
Ein IdP kann benutzerdefinierte Kontolabels so implementieren:
Ein IdP implementiert beispielsweise die "https://idp.example/developer-config.json" Konfigurationsdatei mit "accounts": {"include": "developer"}. Der IdP kennzeichnet einige Konten auch mit dem Label "developer", indem er den Parameter labels im Endpunkt „accounts“ verwendet. Wenn ein RP navigator.credentials.get() mit der Konfigurationsdatei "https://idp.example/developer-config.json" aufruft, werden nur Konten mit dem Label "developer" zurückgegeben.
|
client_metadata_endpoint (optional) |
URL für den Client-Metadatenendpunkt. |
id_assertion_endpoint (erforderlich) |
URL für den Endpunkt für Identitätsbestätigungen. |
disconnect (optional) |
URL für den Endpunkt zum Trennen der Verbindung. |
login_url (erforderlich) |
Die URL der Anmeldeseite, über die sich der Nutzer beim IdP anmelden kann. |
branding (optional) |
Objekt mit verschiedenen Branding-Optionen. |
branding.background_color (optional) |
Brandingoption, mit der die Hintergrundfarbe der Schaltfläche „Als… fortfahren“ festgelegt wird. Verwenden Sie die entsprechende CSS-Syntax: hex-color, hsl(), rgb() oder named-color. |
branding.color (optional) |
Brandingoption, mit der die Textfarbe der Schaltfläche „Als… fortfahren“ festgelegt wird. Verwenden Sie die entsprechende CSS-Syntax: hex-color, hsl(), rgb() oder named-color. |
branding.icons (optional) |
Array von Symbolobjekten. Diese Symbole werden im Anmeldedialogfeld angezeigt. Das Symbolobjekt hat zwei Parameter:
|
modes |
Objekt mit Spezifikationen dazu, wie die FedCM-Benutzeroberfläche in verschiedenen Modi angezeigt wird:
|
modes.active
|
Objekt mit Eigenschaften, mit denen sich das FedCM-Verhalten in einem bestimmten Modus anpassen lässt. Sowohl modes.active als auch modes.passive können den folgenden Parameter enthalten:
Hinweis: Die Funktion „Anderes Konto verwenden“ und der aktive Modus werden ab Chrome 132 unterstützt. |
modes.passive
|
Hier ist ein Beispiel für den Antworttext des Identitätsanbieters:
{
"accounts_endpoint": "/accounts.example",
"client_metadata_endpoint": "/client_metadata.example",
"id_assertion_endpoint": "/assertion.example",
"disconnect_endpoint": "/disconnect.example",
"login_url": "/login",
// When RPs use this config file, only those accounts will be
//returned that include `developer` label in the accounts endpoint.
"accounts": {"include": "developer"},
"modes": {
"active": {
"supports_use_other_account": true,
}
},
"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:
Anderes Konto verwenden
Nutzer können zu einem anderen Konto wechseln, als mit dem sie derzeit angemeldet sind, wenn der Identitätsanbieter mehrere Konten unterstützt oder das vorhandene Konto ersetzt.
Damit der Nutzer andere Konten auswählen kann, muss der Identitätsanbieter diese Funktion in der Konfigurationsdatei angeben:
{
"accounts_endpoint" : "/accounts.example",
"modes": {
"active": {
// Allow the user to choose other account (false by default)
"supports_use_other_account": true
}
// "passive" mode can be configured separately
}
}
Endpunkt für Konten
Der Kontoendpunkt des Identitätsanbieters gibt eine Liste der Konten zurück, in denen der Nutzer beim Identitätsanbieter angemeldet ist. Wenn der Identitätsanbieter mehrere Konten unterstützt, werden über diesen Endpunkt alle angemeldeten Konten zurückgegeben.
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.example 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:
- Prüfe, ob die Anfrage einen
Sec-Fetch-Dest: webidentity-HTTP-Header enthält. - Ordnen Sie die Sitzungscookies den IDs der bereits angemeldeten Konten zu.
- Antworten Sie mit der Liste der Konten.
Der Browser erwartet eine JSON-Antwort, die eine accounts-Eigenschaft mit einem Array von Kontoinformationen mit den folgenden Eigenschaften enthält:
| Attribut | Beschreibung |
|---|---|
id (erforderlich) |
Die eindeutige ID des Nutzers. |
name (erforderlich) |
Vorname und Nachname 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 zur Angabe eines Kontos unterstützt. Der RP kann navigator.credentials.get() mit der Property loginHint aufrufen, um das angegebene Konto selektiv anzuzeigen. |
domain_hints (optional) |
Ein Array aller Domains, die dem Konto zugeordnet sind. Der RP kann navigator.credentials.get() mit einer domainHint-Property aufrufen, um die Konten zu filtern. |
labels (optional)
|
Array von Strings mit benutzerdefinierten Kontolabels, die mit einem Konto verknüpft sind. Ein IdP kann benutzerdefinierte Kontolabels so implementieren:
Ein IdP implementiert beispielsweise die https://idp.example/developer-config.json Konfigurationsdatei mit "accounts": {"include": "developer"}. Der IdP kennzeichnet einige Konten auch mit dem Label "developer", indem er den Parameter labels im Kontoendpunkt verwendet. Wenn ein RP navigator.credentials.get() mit der Konfigurationsdatei https://idp.example/developer-config.json aufruft, werden nur Konten mit dem Label "developer" zurückgegeben.Benutzerdefinierte Kontolabels unterscheiden sich von Anmelde- und Domainhinweisen dadurch, dass sie vollständig vom IdP-Server verwaltet werden und der RP nur die zu verwendende Konfigurationsdatei angibt. |
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",
// Ids of those RPs where this account can be used
"approved_clients": ["123", "456", "789"],
// This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
// with a `loginHint` value specified, for example, `exampleHint`, only those
// accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
"login_hints": ["demo1", "exampleHint"],
// This account is labelled. IdP can implement a specific config file for a
// label, for example, `https://idp.example/developer-config.json`. Like that
// RPs can filter out accounts by calling `navigator.credentials.get()` with
// `https://idp.example/developer-config.json` config file.
"labels": ["hr", "developer"]
}, {
"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"],
"domain_hints": ["@domain.example"]
}]
}
Wenn der Nutzer nicht angemeldet ist, antworte mit HTTP 401 (Nicht autorisiert).
Die zurückgegebene Kontoliste wird vom Browser verwendet und ist für den RP nicht verfügbar.
Endpunkt für Identitätsbestätigung
Der Endpunkt für Identitätsbestätigungen des IdP gibt eine Bestätigung für den angemeldeten Nutzer zurück.
Wenn sich der Nutzer über einen navigator.credentials.get()-Aufruf auf einer RP-Website anmeldet, sendet der Browser eine POST-Anfrage mit Cookies mit SameSite=None und einem Inhaltstyp von application/x-www-form-urlencoded an diesen Endpunkt mit den folgenden Informationen:
| Attribut | Beschreibung |
|---|---|
client_id (erforderlich) |
Die Client-ID des RP. |
account_id (erforderlich) |
Die eindeutige ID des Nutzers, der sich anmeldet. |
disclosure_text_shown |
Das Ergebnis ist ein String mit "true" oder "false" (kein boolescher Wert). In folgenden Fällen wird das Ergebnis "false" zurückgegeben:
|
is_auto_selected |
Wenn die automatische Reautorisierung auf dem RP ausgeführt wird, entspricht is_auto_selected "true". Andernfalls "false". Dies ist hilfreich, um mehr sicherheitsbezogene Funktionen zu unterstützen. Einige Nutzer bevorzugen beispielsweise eine höhere Sicherheitsstufe, bei der eine explizite Nutzermitwirkung bei der Authentifizierung erforderlich ist. Wenn ein IdP eine Tokenanfrage ohne diese Vermittlung erhält, kann er die Anfrage anders verarbeiten. Gib beispielsweise einen Fehlercode zurück, damit der RP die FedCM API noch einmal mit mediation: required aufrufen kann. |
fields (optional)
|
Array von Strings, das die Nutzerinformationen („name“, „email“, „picture“) angibt, die der RP vom IdP benötigt. Der Browser sendet fields, disclosure_text_shown und disclosure_shown_for mit den angegebenen Feldern in der POST-Anfrage, wie im folgenden Beispiel.Hinweis: Der Parameter „Felder“ wird ab Chrome 132 unterstützt. |
params (optional)
|
Ein gültiges JSON-Objekt, mit dem zusätzliche benutzerdefinierte Schlüssel/Wert-Parameter angegeben werden können, z. B.:
params-Wert in JSON serialisiert und dann prozentcodiert.Hinweis: Die Parameters API wird von Chrome 132 und höher unterstützt. |
Beispiel für einen HTTP-Header:
POST /assertion.example HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
// params value is serialized to JSON and then percent-encoded.
account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true¶ms=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture
Nach Erhalt der Anfrage sollte der Server Folgendes tun:
- Antworten Sie mit CORS (Cross-Origin Resource Sharing) auf die Anfrage.
- Prüfe, ob die Anfrage einen
Sec-Fetch-Dest: webidentity-HTTP-Header enthält. - Vergleiche den
Origin-Header mit dem vomclient_idbestimmten RP-Ursprung. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - Vergleiche
account_idmit der ID des bereits angemeldeten Kontos. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - Antworten Sie mit einem Token. Wenn die Anfrage abgelehnt wird, antworte mit einer Fehlerantwort.
Der Identitätsanbieter kann festlegen, wie das Token ausgestellt wird. Im Allgemeinen wird es mit Informationen wie der Konto-ID, der Client-ID, dem Ausstellerursprung und dem Nonce signiert, damit der RP überprüfen kann, ob das Token echt ist.
Der Browser erwartet eine JSON-Antwort mit der folgenden Eigenschaft:
| Attribut | Beschreibung |
|---|---|
token |
Ein Token ist ein String, der Ansprüche zur Authentifizierung enthält. |
continue_on |
Weiterleitungs-URL, die eine mehrstufige Anmeldeabfolge ermöglicht. |
Das zurückgegebene Token wird vom Browser an den RP übergeben, damit dieser die Authentifizierung validieren kann.
{
// IdP can respond with a token to authenticate the user
"token": "***********"
}
Funktion „Weiter“
Der IdP kann in der Antwort des Endpunkts für die Identitätsbestätigung eine Weiterleitungs-URL angeben, um einen mehrstufigen Anmeldevorgang zu ermöglichen. Das ist nützlich, wenn der Identitätsanbieter zusätzliche Informationen oder Berechtigungen anfordern muss, z. B. in folgenden Fällen:
- Berechtigung zum Zugriff auf die serverseitigen Ressourcen des Nutzers.
- Bestätigung, dass die Kontaktdaten aktuell sind
- Jugendschutzeinstellungen.
Der Endpunkt für die Bestätigung der Identität kann eine continue_on-Eigenschaft zurückgeben, die einen absoluten oder relativen Pfad zum Endpunkt für die Bestätigung der Identität enthält.
{
// In the id_assertion_endpoint, instead of returning a typical
// "token" response, the IdP decides that it needs the user to
// continue on a popup window:
"continue_on": "https://idp.example/continue_on_url"
}
Wenn die Antwort den Parameter continue_on enthält, wird ein neues Pop-up-Fenster geöffnet und der Nutzer wird zum angegebenen Pfad weitergeleitet.
Nach der Nutzerinteraktion mit der Seite continue_on sollte der IdP IdentityProvider.resolve() mit dem Token als Argument aufrufen, damit das Versprechen aus dem ursprünglichen navigator.credentials.get()-Aufruf erfüllt werden kann:
document.getElementById('example-button').addEventListener('click', async () => {
let accessToken = await fetch('/generate_access_token.cgi');
// Closes the window and resolves the promise (that is still hanging
// in the relying party's renderer) with the value that is passed.
IdentityProvider.resolve(accessToken);
});
Der Browser schließt dann automatisch das Pop-up und gibt das Token an den API-Aufrufer zurück. Ein einmaliger IdentityProvider.resolve()-Aufruf ist die einzige Möglichkeit, wie das übergeordnete Fenster (RP) und das Pop-up-Fenster (IdP) miteinander kommunizieren können.
Wenn der Nutzer die Anfrage ablehnt, kann der IdP das Fenster schließen, indem er IdentityProvider.close() aufruft.
IdentityProvider.close();
Die Continuation API erfordert eine explizite Nutzerinteraktion (Klicks), um zu funktionieren. So funktioniert die Continuation API mit verschiedenen Vermittlungsmodi:
- Im passiven Modus:
mediation: 'optional'(Standardeinstellung): Die Continuation API funktioniert nur mit einer Nutzergeste, z. B. dem Klicken auf eine Schaltfläche auf der Seite oder in der FedCM-Benutzeroberfläche. Wenn die automatische Neuauthentifizierung ohne Nutzeraktion ausgelöst wird, wird kein Pop-up-Fenster geöffnet und das Versprechen wird abgelehnt.mediation: 'required': Der Nutzer wird immer aufgefordert, zu interagieren, sodass die Continuation API immer funktioniert.
- Im aktiven Modus:
- Eine Nutzeraktivierung ist immer erforderlich. Die Continuation API ist kompatibel.
Wenn der Nutzer aus irgendeinem Grund sein Konto im Pop-up geändert hat (z. B. wenn der IdP die Funktion „Anderes Konto verwenden“ anbietet oder bei der Delegierung), kann der resolve-Aufruf ein optionales zweites Argument annehmen, z. B.:
IdentityProvider.resolve(token, {accountId: '1234');
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 OAuth 2.0-Fehlerliste (invalid_request,unauthorized_client,access_denied,server_errorundtemporarily_unavailable) auswählen oder einen beliebigen String verwenden. In diesem Fall rendert Chrome die Fehler-UI mit einer generischen Fehlermeldung und übergibt den Code an den 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 nützlich, da Browser keine umfassenden Fehlermeldungen in einer integrierten Benutzeroberfläche anzeigen können. Zum Beispiel: Links zu den nächsten Schritten oder Kontaktdaten des Kundenservice. Wenn ein Nutzer mehr über die Fehlerdetails und die Behebung erfahren möchte, kann er die bereitgestellte Seite über die Browser-Benutzeroberfläche aufrufen. Die URL muss der Website des IdentitätsanbietersconfigURLentsprechen.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Benutzerdefinierte Kontolabels
Mit Benutzerdefinierte Kontolabels kann der IdP Nutzerkonten mit Labels versehen. Der RP kann dann festlegen, dass nur Konten mit bestimmten Labels abgerufen werden sollen, indem er die configURL für das jeweilige Label angibt. Das kann hilfreich sein, wenn ein RP Konten nach bestimmten Kriterien herausfiltern muss, z. B. um nur rollenspezifische Konten wie "developer" oder "hr" anzuzeigen.
Ähnliche Filter sind mit den Funktionen Domainhinweis und Anmeldehinweis möglich. Geben Sie sie dazu im navigator.credentials.get()-Aufruf an. Mit benutzerdefinierten Kontolabels können Nutzer jedoch durch Angabe der Konfigurationsdatei gefiltert werden. Das ist besonders nützlich, wenn mehrere configURLs verwendet werden. Benutzerdefinierte Kontolabels unterscheiden sich auch dadurch, dass sie vom IdP-Server und nicht vom RP bereitgestellt werden, z. B. Anmelde- oder Domainhinweise.
Angenommen, ein Identitätsanbieter möchte zwischen "developer"- und "hr"-Konten unterscheiden. Dazu muss der IdP zwei configURLs für "developer" und "hr" unterstützen:
- Die Entwicklerkonfigurationsdatei
https://idp.example/developer/fedcm.jsonhat ein"developer"-Label und die Unternehmenskonfigurationsdateihttps://idp.example/hr/fedcm.jsonein"hr"-Label:
// The developer config file at `https://idp.example/developer/fedcm.json`
{
"accounts_endpoint": "https://idp.example/accounts",
"client_metadata_endpoint": "/client_metadata",
"login_url": "https://idp.example/login",
"id_assertion_endpoint": "/assertion",
"accounts": {
// Account label
"include": "developer"
}
}
// The hr config file at `https://idp.example/hr/fedcm.json`
{
"accounts_endpoint": "https://idp.example/accounts",
"client_metadata_endpoint": "/client_metadata",
"login_url": "https://idp.example/login",
"id_assertion_endpoint": "/assertion",
"accounts": {
// Account label
"include": "hr"
}
}
- Bei einer solchen Konfiguration sollte die well-known-Datei
accounts_endpointundlogin_urlenthalten, um mehrere configURLs zuzulassen:
{
"provider_urls": [ "https://idp.example/fedcm.json" ],
"accounts_endpoint": "https://idp.example/accounts",
"login_url": "https://idp.example/login"
}
- Der gemeinsame Endpunkt für IdP-Konten (in diesem Beispiel
https://idp.example/accounts) gibt eine Liste von Konten zurück, die für jedes Konto einelabels-Property mit zugewiesenen Labels in einem Array enthält:
{
"accounts": [{
"id": "123",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"labels": ["developer"]
}], [{
"id": "4567",
"given_name": "Jane",
"name": "Jane Doe",
"email": "jane_doe@idp.example",
"picture": "https://idp.example/profile/4567",
"labels": ["hr"]
}]
}
Wenn ein RP "hr"-Nutzern die Anmeldung ermöglichen möchte, kann er die configURL https://idp.example/hr/fedcm.json im navigator.credentials.get()-Aufruf angeben:
let { token } = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
nonce: '234234',
configURL: 'https://idp.example/hr/fedcm.json',
},
}
});
Daher ist für die Anmeldung des Nutzers nur die Konto-ID 4567 verfügbar. Die Konto-ID 123 wird vom Browser automatisch ausgeblendet, damit dem Nutzer kein Konto zur Verfügung gestellt wird, das vom IdP auf dieser Website nicht unterstützt wird.
- Labels sind Strings. Wenn das Array
labelsoder das Feldincludeeinen anderen Wert als einen String enthält, wird es ignoriert. - Wenn in der
configURLkeine Labels angegeben sind, werden alle Konten in der FedCM-Kontoauswahl angezeigt. - Wenn für ein Konto keine Labels angegeben sind, wird es nur dann in der Kontoauswahl angezeigt, wenn auch für die
configURLkein Label angegeben ist. - Wenn im passiven Modus kein Konto mit dem angeforderten Label übereinstimmt (ähnlich wie bei der Funktion „Domainhinweis“), wird im FedCM-Dialogfeld eine Anmeldeaufforderung angezeigt, über die sich der Nutzer in einem IdP-Konto anmelden kann. Im aktiven Modus wird das Pop-up-Fenster für die Anmeldung direkt geöffnet.
Endpunkt trennen
Durch das Aufrufen von IdentityCredential.disconnect() sendet der Browser eine ursprungsübergreifende POST-Anfrage mit Cookies mit SameSite=None und einem Inhaltstyp von application/x-www-form-urlencoded an diesen Disconnect-Endpunkt mit den folgenden Informationen:
| Attribut | Beschreibung |
|---|---|
account_hint |
Ein Hinweis für das IdP-Konto. |
client_id |
Die Client-ID des RP. |
POST /disconnect.example 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:
- Antworten Sie mit CORS (Cross-Origin Resource Sharing) auf die Anfrage.
- Prüfe, ob die Anfrage einen
Sec-Fetch-Dest: webidentity-HTTP-Header enthält. - Vergleiche den
Origin-Header mit dem vomclient_idbestimmten RP-Ursprung. Lehnen Sie sie ab, wenn sie nicht übereinstimmen. - Vergleiche
account_hintmit den IDs der bereits angemeldeten Konten. - Trennen Sie die Verbindung des Nutzerkontos vom RP.
- Antworte dem Browser mit den Informationen zum identifizierten Nutzerkonto 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. "*".
Client-Metadatenendpunkt
Der Client-Metadatenendpunkt der IdP gibt die Metadaten der vertrauenden Partei zurück, z. B. die Datenschutzerklärung, die Nutzungsbedingungen und die Logosymbole der vertrauenden Partei. RPs sollten dem Identitätsanbieter 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 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.example?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:
- Ermitteln Sie den RP für die
client_id. - Antworten Sie mit den Client-Metadaten.
Zu den Eigenschaften für den Endpunkt für Clientmetadaten gehören:
| Attribut | Beschreibung |
|---|---|
privacy_policy_url (optional) |
URL der Datenschutzerklärung des Rechtssubjekts. |
terms_of_service_url (optional) |
URL der Nutzungsbedingungen des Resellers. |
icons (optional) |
Array von Objekten, z. B. [{ "url": "https://rp.example/rp-icon.ico", "size": 40}] |
Der Browser erwartet vom Endpunkt eine JSON-Antwort:
{
"privacy_policy_url": "https://rp.example/privacy_policy.html",
"terms_of_service_url": "https://rp.example/terms_of_service.html",
"icons": [{
"url": "https://rp.example/rp-icon.ico",
"size": 40
}]
}
Die zurückgegebenen Clientmetadaten werden vom Browser verwendet und sind für den RP nicht verfügbar.
Anmelde-URL
Über diesen Endpunkt kann sich der Nutzer beim IdP anmelden.
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 URL der Anmeldeseite 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, liegt im Ermessen des Identitätsanbieters. Es sind keine Fenster-Handles verfügbar, um eine plattformübergreifende Kommunikationsanfrage an die RP-Seite zu senden. Nachdem sich der Nutzer angemeldet hat, sollte der Identitätsanbieter Folgendes tun:
- Sende den
Set-Login: logged-in-Header oder rufe dienavigator.login.setStatus("logged-in")API auf, um den Browser darüber zu informieren, dass der Nutzer angemeldet ist. - Drücken Sie
IdentityProvider.close(), um das Dialogfeld zu schließen.
Browser über den Anmeldestatus des Nutzers informieren
Die Login Status API ist ein Mechanismus, mit 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.
Identitätsanbieter können den Anmeldestatus des Nutzers an den Browser senden, indem sie einen HTTP-Header senden oder eine JavaScript API aufrufen, wenn der Nutzer beim Identitätsanbieter angemeldet ist oder von allen seinen Identitätsanbieterkonten abgemeldet ist. Für jeden IdP (identifiziert durch seine Konfigurations-URL) speichert der Browser eine Drei-Zustands-Variable, die den Anmeldestatus mit den folgenden möglichen Werten darstellt:
logged-inlogged-outunknown(Standard)
| Anmeldestatus | Beschreibung |
|---|---|
logged-in |
Wenn der Anmeldestatus des Nutzers auf logged-in gesetzt ist, sendet die RP, die FedCM aufruft, Anfragen an den Kontoendpunkt des Identitätsanbieters und zeigt dem Nutzer im FedCM-Dialogfeld verfügbare Konten an. |
logged-out |
Wenn der Anmeldestatus des Nutzers logged-out ist, schlägt der Aufruf von FedCM stillschweigend fehl, ohne dass eine Anfrage an den Kontoendpunkt des IdP gesendet wird. |
unknown (Standard) |
Der Status unknown wird festgelegt, bevor der Identitätsanbieter ein Signal über die Login Status API sendet. Wenn der Status unknown ist, sendet der Browser eine Anfrage an den Kontoendpunkt des Identitätsanbieters und aktualisiert den Status anhand der Antwort vom Kontoendpunkt. |
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-Methode navigator.login.setStatus('logged-in') über den IdP-Ursprung in einer Navigation auf oberster Ebene aufrufen:
navigator.login.setStatus('logged-in')
Der Anmeldestatus des Nutzers wird auf logged-in gesetzt.
Um anzuzeigen, dass der Nutzer von allen seinen Konten abgemeldet ist, senden Sie einen Set-Login: logged-out-HTTP-Header in einer Navigation auf oberster Ebene oder eine Anfrage für eine Subressource 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')
Der Anmeldestatus des Nutzers wird auf logged-out gesetzt.
Der Status unknown wird festgelegt, bevor der Identitätsanbieter ein Signal über die Login Status API sendet. Der Browser stellt eine Anfrage an den Kontenendpunkt des Identitätsanbieters und aktualisiert den Status basierend auf der Antwort vom Kontenendpunkt:
- Wenn der Endpunkt eine Liste aktiver Konten zurückgibt, aktualisiere den Status zu
logged-inund öffne das FedCM-Dialogfeld, um diese Konten anzuzeigen. - Wenn der Endpunkt keine Konten zurückgibt, aktualisiere den Status zu
logged-outund scheitere den FedCM-Aufruf.
Nutzer über einen dynamischen Anmeldevorgang anmelden
Auch wenn der Identitätsanbieter den Anmeldestatus des Nutzers ständig an den Browser weitergibt, kann es zu einer Synchronisierungsverzögerung kommen, 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.
FedCM als RP implementieren
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 du die API aufrufst, musst du prüfen, ob 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
} else {
// FedCM is not supported, use a different identity solution
}
Damit sich Nutzer über FedCM bei einem RP beim IdP anmelden können, kann der RP navigator.credentials.get() aufrufen, z. B. so:
const credential = await navigator.credentials.get({
identity: {
context: 'signin',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
mode: 'active',
params: {
nonce: '******'
}
}]
}
});
const { token } = credential;
Kontexteigenschaft
Mit der optionalen context-Eigenschaft kann der RP den String in der FedCM-Dialog-Benutzeroberfläche ändern (z. B. „Bei rp.beispiel anmelden…“, „Idp.beispiel verwenden…“), um beispielsweise vordefinierte Authentifizierungskontexte zu berücksichtigen. Die Property context kann die folgenden Werte haben:
signin(Standard)signupuse
Wenn Sie beispielsweise context auf use festlegen, wird die folgende Meldung angezeigt:
Der Browser verarbeitet die Anwendungsfälle für die Registrierung und Anmeldung unterschiedlich, je nachdem, ob approved_clients in der Antwort vom Endpunkt „Kontenliste“ vorhanden ist. Wenn sich der Nutzer bereits für die Rezensionsplattform registriert hat, wird im Browser kein Hinweistext „Um mit . . . fortzufahren“ angezeigt.
Die providers-Eigenschaft nimmt ein Array von IdentityProvider-Objekten mit den folgenden Eigenschaften an:
Property „Anbieter“
Die providers-Eigenschaft nimmt ein Array von IdentityProvider-Objekten mit den folgenden Eigenschaften an:
| Attribut | Beschreibung |
|---|---|
configURL (erforderlich) |
Der vollständige Pfad zur IdP-Konfigurationsdatei. |
clientId (erforderlich) |
Die vom IdP ausgestellte Client-ID des RP. |
nonce (optional) |
Ein zufälliger String, der dafür sorgt, dass die Antwort für diese bestimmte Anfrage ausgegeben wird. Verhindert Replay-Angriffe. |
loginHint (optional) |
Wenn du einen der login_hints-Werte angibst, die von den Kontoendpunkten bereitgestellt werden, wird im FedCM-Dialogfeld nur das angegebene Konto angezeigt. |
domainHint (optional) |
Wenn du einen der domain_hints-Werte angibst, die von den Kontoendpunkten bereitgestellt werden, wird im FedCM-Dialogfeld nur das angegebene Konto angezeigt. |
mode (optional) |
String, der den UI-Modus von FedCM angibt. Es kann einen der folgenden Werte haben:
Hinweis: Der Parameter mode wird ab Chrome 132 unterstützt.
|
fields (optional) |
Array von Strings, das die Nutzerinformationen („name“, „email“, „picture“) angibt, die der RP vom IdP benötigt. Hinweis: Die Field API wird ab Chrome 132 unterstützt. |
parameters (optional) |
Benutzerdefiniertes Objekt, mit dem zusätzliche Schlüssel/Wert-Parameter angegeben werden können:
Hinweis: parameters wird ab Chrome 132 unterstützt.
|
Aktivmodus
FedCM unterstützt verschiedene Konfigurationen des UX-Modus. Der passive Modus ist der Standardmodus und muss nicht konfiguriert werden.
So verwenden Sie FedCM im Aktivmodus:
- Prüfen Sie die Verfügbarkeit der Funktion im Browser des Nutzers.
- Rufen Sie die API mit einer vorübergehenden Nutzergeste auf, z. B. einem Klick auf eine Schaltfläche.
- Übergeben Sie den Parameter
modean den API-Aufruf:
let supportsFedCmMode = false;
try {
navigator.credentials.get({
identity: Object.defineProperty(
// Check if this Chrome version supports the Mode API.
{}, 'mode', {
get: function () { supportsFedCmMode = true; }
}
)
});
} catch(e) {}
if (supportsFedCmMode) {
// The button mode is supported. Call the API with mode property:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/config.json',
clientId: '123',
}],
// The 'mode' value defines the UX mode of FedCM.
// - 'active': Must be initiated by user interaction (e.g., clicking a button).
// - 'passive': Can be initiated without direct user interaction.
mode: 'active'
}
});
}
Benutzerdefiniertes Symbol im Aktivmodus
Im Aktivmodus können IdPs das offizielle Logosymbol des RP direkt in die Antwort des Client-Metadaten-Endpunkts einfügen. Der RP muss seine Branding-Daten im Voraus angeben.
FedCM innerhalb eines ursprungsübergreifenden iFrames aufrufen
FedCM kann über eine identity-credentials-get-Berechtigungsrichtlinie innerhalb eines iframes mit unterschiedlichen Ursprüngen aufgerufen werden, sofern 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.
Login Hint API
Anhand des Anmeldehinweises kann der RP empfehlen, mit welchem Konto sich ein Nutzer anmelden soll. Das kann hilfreich sein, um Nutzer neu zu authentifizieren, die sich nicht sicher sind, welches Konto sie zuvor verwendet haben.
RPs können ein bestimmtes Konto selektiv anzeigen, indem sie navigator.credentials.get() mit der Eigenschaft loginHint und einem der login_hints-Werte aufrufen, die vom Endpunkt „Kontenliste“ abgerufen wurden, wie im folgenden Codebeispiel gezeigt:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/manifest.json',
clientId: '123',
// Accounts endpoint can specify a 'login_hints' array for an account.
// When RP specifies a 'exampleHint' value, only those accounts will be
// shown to the user whose 'login_hints' array contains the 'exampleHint'
// value
loginHint : 'exampleHint'
}]
}
});
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 Anmelde-URL geöffnet. Dem Link werden dann die Abfrageparameter „Anmeldehinweis“ und „Domainhinweis“ angehängt.
Domain Hint API
RPs können selektiv nur Konten anzeigen, die mit einer bestimmten Domain verknüpft sind. Das kann für RPs nützlich sein, die auf eine Unternehmensdomain beschränkt sind.
Wenn nur bestimmte Domainkonten angezeigt werden sollen, sollte der RP navigator.credentials.get() mit dem Attribut domainHint und einem der domain_hints-Werte aufrufen, die vom Endpunkt „Kontenliste“ abgerufen wurden, wie im folgenden Codebeispiel gezeigt:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/manifest.json',
clientId: 'abc',
// Accounts endpoint can specify a 'domain_hints' array for an account.
// When RP specifies a '@domain.example' value, only those accounts will be
// shown to the user whose 'domain_hints' array contains the
// '@domain.example' value
domainHint : '@domain.example'
}]
}
});
Wenn keine Konten mit der domainHint ü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 Anmelde-URL geöffnet. Dem Link werden dann die Abfrageparameter „Anmeldehinweis“ und „Domainhinweis“ angehängt.
domainHint übereinstimmen.Benutzerdefinierte Parameter
Mit der Funktion „Benutzerdefinierte Parameter“ kann der RP dem Endpunkt für die ID-Bestätigung zusätzliche Schlüssel/Wert-Parameter zur Verfügung stellen. Mit der Parameters API können RPs zusätzliche Parameter an den IdP übergeben, um Berechtigungen für Ressourcen über die grundlegende Anmeldung hinaus anzufordern. Das Übergeben zusätzlicher Parameter kann in folgenden Fällen nützlich sein:
- Der RP muss dynamisch zusätzliche Berechtigungen anfordern, die der IdP hat, z. B. die Rechnungsadresse oder den Kalenderzugriff. Der Nutzer kann diese Berechtigungen über einen vom IdP gesteuerten UX-Vorgang autorisieren, der über die Funktion „Weiter mit“ gestartet wird. Der IdP gibt diese Informationen dann weiter.
Um die API zu verwenden, fügt der RP der params-Eigenschaft als Objekt im navigator.credentials.get()-Aufruf Parameter hinzu:
let {token} = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
// Key/value pairs that need to be passed from the
// RP to the IdP but that don't really play any role with
// the browser.
params: {
IDP_SPECIFIC_PARAM: '1',
foo: 'BAR'
}
},
}
});
Der Browser übersetzt dies automatisch in eine POST-Anfrage an den IdP mit Parametern als einzelnes URL-codiertes JSON-serialisiertes Objekt:
// The assertion endpoint is drawn from the config file
POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
account_id=123&client_id=client1234¶ms=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.
Wenn der RP zusätzliche Berechtigungen benötigt, kann der IdP einen Weiterleitungslink bereitstellen. Beispiel in Node.js:
if (rpRequestsPermissions) {
// Response with a URL if the RP requests additional permissions
return res.json({
continue_on: '/example-redirect',
});
}
Felder
Der RP kann die Nutzerinformationen angeben, die der IdP mit ihm teilen muss (beliebige Kombination aus Name, E-Mail-Adresse und Profilbild). Die angeforderten Informationen werden in die Offenlegungs-UI des FedCM-Dialogfelds aufgenommen. Der Nutzer wird darüber informiert, dass idp.example die angeforderten Informationen an rp.example weitergibt, wenn er sich anmeldet.
Wenn der RP die Funktion „Felder“ verwenden möchte, muss er dem navigator.credentials.get()-Aufruf ein fields-Array hinzufügen. Die Felder können beliebige Permutationen von name, email und picture enthalten. Diese Liste kann in Zukunft um weitere Werte erweitert werden.
Eine Anfrage mit fields würde so aussehen:
let { token } = await navigator.credentials.get({
identity: {
providers: [{
// RP requests the IdP to share only user email and profile picture
fields: [ 'email', 'picture'],
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
},
}
});
Der Browser übersetzt sie automatisch in eine HTTP-Anfrage an den ID-Bestätigungsendpunkt, die den vom RP angegebenen Parameter fields mit den Feldern enthält, die der Browser dem Nutzer in einem disclosure_shown_for-Parameter offengelegt hat. Aus Gründen der Abwärtskompatibilität sendet der Browser auch disclosure_text_shown=true, wenn der Offenlegungstext angezeigt wurde und die angeforderten Felder alle drei Felder enthalten: 'name', 'email' und 'picture'.
POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture
Wenn fields ein leeres Array ist, überspringt der User-Agent die Benutzeroberfläche für die Offenlegung.
Das ist auch dann der Fall, wenn die Antwort vom Konten-Endpunkt keine Client-ID enthält, die mit dem RP in approved_clients übereinstimmt.
In diesem Fall ist disclosure_text_shown, das an den ID-Bestätigungsendpunkt gesendet wird, im HTTP-Text falsch:
POST /id_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=false
Fehlermeldung anzeigen
Manchmal kann der Identitätsanbieter 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 sie abfangen und Chrome kann den Nutzer benachrichtigen, indem die Browseroberflä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 „auto-reauthn“) können sich Nutzer automatisch noch einmal authentifizieren, wenn sie nach der anfänglichen Authentifizierung mit FedCM wiederkommen. „Die erste Authentifizierung“ bedeutet hier, dass der Nutzer ein Konto erstellt oder sich in der Website des RP anmeldet, indem er zum ersten Mal in derselben Browserinstanz auf die Schaltfläche Weiter als… im Anmeldedialogfeld von FedCM tippt.
Die explizite Nutzererfahrung ist sinnvoll, bevor der Nutzer das föderierte Konto erstellt hat, um Tracking zu verhindern (eines der Hauptziele von FedCM). Nach der Ersteinrichtung 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 der Browser sein Verhalten je nach der Option, die Sie für die mediation beim Aufrufen von navigator.credentials.get() 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. Für die Property sind die folgenden vier Werte zulässig:
'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': Automatische erneute Authentifizierung, falls möglich, andernfalls geräuschloses Scheitern ohne Mediation. Wir empfehlen diese Option auf Seiten auszuwählen, die nicht die Anmeldeseite sind, auf denen Nutzer aber angemeldet bleiben sollen, z. B. eine Artikelseite auf einer Versandwebsite oder eine 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. Beispiel: Der Nutzer hat FedCM nicht global oder für den RP in den Einstellungen deaktiviert.
- Der Nutzer hat sich in diesem Browser nur mit einem Konto mit der FedCM API auf der Website angemeldet.
- Der Nutzer ist mit diesem Konto beim Identitätsanbieter angemeldet.
- Die automatische Reaktivierung hat nicht innerhalb der letzten 10 Minuten stattgefunden.
- 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, ist die automatische erneute Authentifizierung aus Gründen, die nur dem Browser bekannt sind, möglicherweise nicht verfügbar. Der RP kann anhand der Property isAutoSelected prüfen, ob die automatische erneute Authentifizierung durchgeführt wird.
So können Sie die API-Leistung bewerten und die UX entsprechend verbessern.
Wenn die Funktion nicht verfügbar ist, werden Nutzer möglicherweise aufgefordert, sich mit expliziter Nutzervermittlung anzumelden. Das ist ein Ablauf mit mediation: required.
Vermittlung mit preventSilentAccess() erzwingen
Die automatische erneute Authentifizierung von Nutzern direkt nach der Abmeldung würde die Nutzerfreundlichkeit beeinträchtigen. 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 den Browser ausdrücklich 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 Autorisierung in den Einstellungen deaktivieren.
Nutzer können die automatische erneute Autorisierung im Menü „Einstellungen“ deaktivieren:
- Klicken Sie in der Desktopversion von Chrome auf
chrome://password-manager/settings> „Automatisch anmelden“. - Öffnen Sie in Chrome für Android die Einstellungen > Passwortmanager > tippen Sie rechts oben auf das Zahnradsymbol > „Automatische Anmeldung“.
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 der obersten 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 vom Kontolisten-Endpunkt angegeben wurde:
// 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 eine 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 zur Kontotrennung.
- Der Nutzer hat FedCM in den Browsereinstellungen deaktiviert.
Wenn der Disconnect-Endpunkt des IdPs 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.