Identitätslösung mit FedCM auf der Seite der vertrauenden Seite implementieren

Vertrauende Parteien müssen die folgenden Schritte ausführen, um FedCM auf ihrer Website zu aktivieren:

• Achten Sie darauf, dass FedCM-Endpunkte auf der Website des vertrauenden Dienstes zulässig sind.
• Verwenden Sie die FedCM JavaScript API, um die Nutzerauthentifizierung zu initiieren.
• Stellen Sie dem Identitätsanbieter (oder mehreren Identitätsanbietern ab Chrome 136) die Metadaten des Identitätsanbieters zur Verfügung, z. B. URLs zur Datenschutzerklärung und zu den Nutzungsbedingungen.
• [optional] Passen Sie die Nutzerfreundlichkeit an, indem Sie einen UX-Modus auswählen, Anmelde- oder Domainhinweise angeben, benutzerdefinierte Parameter übergeben, bestimmte Nutzerinformationen anfordern, eine benutzerdefinierte Fehlermeldung angeben oder auswählen, wie Nutzer neu authentifiziert werden sollen.

FedCM API auf der Relying Party aufrufen

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

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, umschließen Sie Ihre FedCM-Implementierung mit diesem Code:

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Damit sich ein Nutzer mit FedCM beim IdP auf einer vertrauenden Partei anmelden kann, kann die vertrauende Partei navigator.credentials.get() aufrufen. Ab Chrome 136 kann RP mehrere Identitätsanbieter unterstützen, indem ein Array mit mehreren Identitätsanbietern in einem einzelnen navigator.credentials.get()-Aufruf angegeben wird, z. B.:

  const credential = await navigator.credentials.get({
      identity: {
        // Specify the IdP (or multiple IdPs, supported from Chrome 136) this Relying Party supports
        providers: [
        {
              configURL: 'https://accounts.idp-1.example/config.json',
              clientId: '********'
        },
        {
          configURL: 'https://accounts.idp-2.example/config.json',
          clientId: '********'
        }]
      }
    },
  );
  const { token } = credential;
  
  // Get the current IdP's configURL to identify which provider the user is signed in with
  const currentIdpConfigUrl = credential.configURL;
  if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
    // handle the case where the user signed in with idp1
  } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
    // handle the case where the user signed in with idp2
    }

Testen Sie die Funktion für mehrere IdPs, indem Sie sich mit IdP1 und IdP2 anmelden.

Kontexteigenschaft

Mit der optionalen Eigenschaft context kann der RP den String in der FedCM-Dialogfeld-UI ändern (z. B. „Bei rp.example anmelden…“, „idp.example verwenden…“), um beispielsweise vordefinierte Authentifizierungskontexte zu berücksichtigen. Die Eigenschaft context kann die folgenden Werte haben:

• signin (Standard)
• signup
• use

Wenn Sie context beispielsweise auf use setzen, wird die folgende Meldung angezeigt:

Der Browser behandelt Anmeldungen und Registrierungen unterschiedlich, je nachdem, ob approved_clients in der Antwort vom Endpunkt für die Kontoliste vorhanden ist. Der Browser zeigt keinen Offenlegungstext „Um mit … fortzufahren“ an, wenn sich der Nutzer bereits für das RP registriert hat.
Die providers-Eigenschaft verwendet ein Array von IdentityProvider-Objekten mit den folgenden Eigenschaften:

„Providers“-Property

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

Aktivmodus

FedCM unterstützt verschiedene Konfigurationen für den UX-Modus. Der passive Modus ist der Standardmodus und muss von Entwicklern nicht konfiguriert werden.

So verwenden Sie FedCM im Aktivmodus:

1. Prüfen Sie die Verfügbarkeit der Funktion im Browser des Nutzers.
2. Rufen Sie die API mit einer vorübergehenden Nutzergeste auf, z. B. einem Klick auf eine Schaltfläche.
3. Übergeben Sie den Parameter mode an 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'
      }
    });
  }

Hier können Sie den Aktivmodus ausprobieren.

Benutzerdefiniertes Symbol im aktiven Modus

Im aktiven Modus können IdPs das offizielle Logo des vertrauenden Dienstes direkt in die Antwort des Client-Metadaten-Endpunkts einfügen. Der Rechteinhaber muss seine Branding-Daten im Voraus bereitstellen.

FedCM aus einem ursprungsübergreifenden iFrame aufrufen

FedCM kann über ein identity-credentials-get-Berechtigungsrichtlinie in einem ursprungsübergreifenden iFrame aufgerufen werden, wenn der übergeordnete Frame dies zulässt. Fügen Sie dazu dem iFrame-Tag das Attribut allow="identity-credentials-get" hinzu:

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

Beispiel

Wenn der übergeordnete Frame die Ursprünge für den Aufruf von FedCM einschränken möchte, senden Sie optional einen Permissions-Policy-Header 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

Mithilfe des Anmeldehinweises kann der RP empfehlen, mit welchem Konto sich ein Nutzer anmelden sollte. 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 der Kontoliste 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 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. An den Link werden dann die Abfrageparameter „login_hint“ und „domain_hint“ angehängt.

Domain Hint API

RPs können selektiv nur Konten anzeigen, die mit einer bestimmten Domain verknüpft sind. Das kann für die RPs nützlich sein, die auf eine Unternehmensdomain beschränkt sind.

Wenn nur bestimmte Domainkonten angezeigt werden sollen, muss RP navigator.credentials.get() mit dem Attribut domainHint und einem der domain_hints-Werte aufrufen, die aus dem Endpunkt der 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 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. An den Link werden dann die Abfrageparameter „login_hint“ und „domain_hint“ angehängt.

Weitere Informationen finden Sie in der Demo.

Benutzerdefinierte Parameter

Mit der Funktion „Benutzerdefinierte Parameter“ kann der RP dem ID-Bestätigungsendpunkt 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 anzufordern, die über die grundlegende Anmeldung hinausgehen. Das Übergeben zusätzlicher Parameter kann in folgenden Szenarien nützlich sein:

• Der RP muss dynamisch zusätzliche Berechtigungen anfordern, die der IdP hat, z. B. Rechnungsadresse oder Kalenderzugriff. Der Nutzer kann diese Berechtigungen über einen vom IdP gesteuerten UX-Ablauf autorisieren, der mit Continue on gestartet wird. Der IdP gibt diese Informationen dann weiter.

Um die API zu verwenden, fügt der RP der Eigenschaft params Parameter als Objekt im navigator.credentials.get()-Aufruf 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&params=%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 (eine beliebige Kombination aus Name, E-Mail-Adresse und Profilbild) angeben, die der IdP mit ihm teilen soll. Die angeforderten Informationen werden in der Offenlegungs-UI des FedCM-Dialogfelds angezeigt. Der Nutzer sieht eine Meldung, in der er darüber informiert wird, dass idp.example die angeforderten Informationen mit rp.example teilt, wenn er sich anmeldet.

Damit die Funktion „Felder“ verwendet werden kann, muss RP dem navigator.credentials.get()-Aufruf ein fields-Array hinzufügen. Die Felder können eine beliebige Kombination aus name, email und picture enthalten. In Zukunft können weitere Werte hinzukommen. 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 Endpunkt für die ID-Bestätigung, die den vom RP angegebenen Parameter fields enthält, wobei die Felder, die der Browser dem Nutzer in einem Parameter disclosure_shown_for offengelegt hat, enthalten sind. 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 Offenlegungs-UI.

Das ist auch dann der Fall, wenn die Antwort vom accounts-Endpunkt keine Client-ID enthält, die mit dem RP in approved_clients übereinstimmt.

In diesem Fall ist der an den ID-Assertion-Endpunkt gesendete disclosure_text_shown-Wert 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 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 Fehlerantwort zurückgibt, kann der Relying Party sie abfangen und Chrome kann den Nutzer benachrichtigen, indem die 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 ersten Authentifizierung automatisch neu authentifizieren

Mit der automatischen FedCM-Reauthentifizierung (kurz „auto-reauthn“) können sich Nutzer automatisch neu authentifizieren. Die folgenden Bedingungen müssen erfüllt sein, damit die Nutzerauthentifizierung automatisch wiederholt wird:

• Der Nutzer hat die anfängliche Authentifizierung bereits mit FedCM durchgeführt. „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 FedCM-Anmeldedialog auf die Schaltfläche Weiter als… tippt.
• Der Nutzer hat nur ein Konto, über das er die Rückgabe durchführt. Wenn für mehrere Identitätsanbieter zurückgegebene Konten vorhanden sind, wird der Nutzer nicht automatisch neu authentifiziert.

Die explizite Nutzerinteraktion ist sinnvoll, bevor der Nutzer das föderierte Konto erstellt hat, um Tracking zu verhindern (eines der Hauptziele von FedCM). Sie ist jedoch unnötig umständlich, nachdem der Nutzer sie einmal durchlaufen hat: Nachdem der Nutzer die Berechtigung zur Kommunikation zwischen dem RP und dem IdP erteilt hat, gibt es keinen Datenschutz- oder Sicherheitsvorteil, eine weitere explizite Nutzerbestätigung für etwas zu erzwingen, das er bereits zuvor bestätigt hat.

Bei der automatischen Reauthentifizierung ändert der Browser sein Verhalten je nach der Option, die Sie für 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 eine Eigenschaft in der Credential Management API und verhält sich auf dieselbe Weise wie für PasswordCredential und FederatedCredential. Sie wird auch teilweise von PublicKeyCredential unterstützt. Die Property kann die folgenden vier Werte haben:

• 'optional'(Standard): Die automatische erneute Authentifizierung erfolgt, sofern möglich. Andernfalls ist eine Vermittlung erforderlich. Wir empfehlen, diese Option auf der Anmeldeseite auszuwählen.
• 'required': Erfordert immer eine Vermittlung, um fortzufahren, z. B. durch 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, explizit die Berechtigung erteilen sollen.
• 'silent': Wenn möglich, automatische erneute Authentifizierung. Andernfalls wird ohne Vermittlung ein Fehler zurückgegeben. Wir empfehlen, diese Option auf Seiten zu verwenden, die nicht die Anmeldeseite sind, auf denen Nutzer aber angemeldet bleiben sollen, z. B. auf einer Artikelseite einer Nachrichtenwebsite oder einer Artikelseite einer Versandwebsite.
• '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 beispielsweise nicht global oder für den RP in den Einstellungen deaktiviert.
• Der Nutzer hat sich mit nur einem Konto über die FedCM API in diesem Browser auf der Website angemeldet.
• Der Nutzer ist mit diesem Konto beim Identitätsanbieter angemeldet.
• Die automatische erneute Authentifizierung hat in den letzten 10 Minuten nicht stattgefunden.
• Der RP hat navigator.credentials.preventSilentAccess() nach der vorherigen Anmeldung nicht aufgerufen.

Wenn diese Bedingungen erfüllt sind, wird ein Versuch gestartet, den Nutzer automatisch neu zu authentifizieren, sobald die FedCM-navigator.credentials.get() aufgerufen wird.

Wenn mediation: optional, ist die automatische Re-Authentifizierung möglicherweise nicht verfügbar. Die Gründe dafür sind nur dem Browser bekannt. Der RP kann prüfen, ob die automatische Re-Authentifizierung durchgeführt wird, indem er das Attribut isAutoSelected untersucht.

Das ist hilfreich, um die API-Leistung zu bewerten und die Nutzerfreundlichkeit entsprechend zu verbessern. Wenn sie nicht verfügbar ist, wird der Nutzer möglicherweise aufgefordert, sich mit einer expliziten Nutzervermittlung anzumelden. Das ist ein Ablauf mit mediation: required.

Vermittlung mit preventSilentAccess() erzwingen

Wenn Nutzer sofort nach der Abmeldung automatisch neu authentifiziert werden, ist das nicht sehr nutzerfreundlich. Aus diesem Grund gibt es bei FedCM nach einer automatischen Reauthentifizierung eine 10-minütige Ruhephase, um dieses Verhalten zu verhindern. Das bedeutet, dass die automatische Reauthentifizierung höchstens einmal 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 explizit aufzufordern, die automatische Reauthentifizierung 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 Reauthentifizierung in den Einstellungen deaktivieren.

Nutzer können die automatische erneute Authentifizierung im Einstellungsmenü 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 des Schalters kann der Nutzer das automatische erneute Authentifizierungsverhalten vollständig deaktivieren. Diese Einstellung wird gespeichert und auf allen Geräten synchronisiert, wenn der Nutzer in der Chrome-Instanz in einem Google-Konto angemeldet ist und die Synchronisierung aktiviert ist.

Verbindung zwischen IdP und RP trennen

Wenn sich ein Nutzer zuvor über FedCM mit dem IdP in der vertrauenden Partei angemeldet hat, wird die Beziehung vom Browser lokal als Liste der verknüpften Konten gespeichert. Der RP kann eine Trennung durch Aufrufen der Funktion IdentityCredential.disconnect() initiieren. Diese Funktion kann über einen RP-Frame der obersten Ebene aufgerufen werden. Der RP muss eine configURL, die clientId, die er unter dem IdP verwendet, und eine accountHint für die Trennung des IdP übergeben. Ein Kontohinweis kann ein beliebiger String sein, solange der Trennungsendpunkt das Konto identifizieren kann, z. B. eine E‑Mail-Adresse oder Nutzer-ID, die nicht unbedingt mit der Konto-ID übereinstimmen muss, die vom Kontolistenendpunkt bereitgestellt 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 ein Promise zurück. Dieses Promise kann aus folgenden Gründen eine Ausnahme auslösen:

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

Wenn der Trennungs-Endpunkt des Identitätsanbieters eine Antwort zurückgibt, werden RP und Identitätsanbieter im Browser getrennt und das Promise wird aufgelöst. Die IDs der getrennten Konten werden in der Antwort vom Trennungsendpunkt angegeben.

Nächste Schritte

FedCM auf der Seite des IdP implementieren

Hier erfahren Sie, wie Sie Ihre Identitätslösung mit FedCM auf der Seite des Identitätsanbieters implementieren.

Anpassung und Deaktivierung

Hier erfahren Sie, wie Nutzer und Entwickler die Teilnahme an FedCM verwalten und die Funktion auf verschiedenen Plattformen und Websites aktivieren oder deaktivieren können.