IdentityCredentialRequestOptions — Schnittstelle · JavaScript-Referenz

Signatur

interface IdentityCredentialRequestOptions

Beschreibung

IdentityCredentialRequestOptions gehört zur Federated Credential Management API (FedCM). Das Objekt ist keine Klasse, die man instanziiert, sondern ein einfaches Objekt (Wörterbuch). Man übergibt es als identity-Eigenschaft an navigator.credentials.get(). Darin steht, bei welchen Identitätsanbietern (IdPs) sich der Nutzer anmelden kann, zum Beispiel „Mit Anbieter X anmelden“. Das Ganze funktioniert ohne Drittanbieter-Cookies und ohne Weiterleitungen oder Pop-ups.

Die wichtigste Eigenschaft ist providers. Das ist ein Array mit Konfigurationen einzelner Identitätsanbieter (IdentityProviderRequestOptions). Jeder Eintrag braucht mindestens configURL (die URL der Konfigurationsdatei des IdP) und clientId (die Kennung, die der IdP an die vertrauende Website, den Relying Party, vergeben hat). Optional sind nonce, loginHint, domainHint, fields und params.

Mit context legt man den Text des Browser-Dialogs fest („Anmelden“, „Registrieren“, „Verwenden“, „Fortfahren“). mode bestimmt, ob der Dialog automatisch erscheint ("passive") oder nur nach einer Nutzeraktion wie einem Klick auf einen Anmelde-Button ("active"). War die Anmeldung erfolgreich, erfüllt sich das Promise mit einem IdentityCredential. Dessen Eigenschaft token schickt man zur Prüfung an das eigene Backend.

Parameter

Name	Typ	Default	Beschreibung
$providers Pflicht	Array<IdentityProviderRequestOptions>		Liste der Identitätsanbieter. Jeder Eintrag enthält `configURL` (string, Pflicht), `clientId` (string, Pflicht) und optional `nonce`, `loginHint`, `domainHint`, `fields` (z. B. `["name", "email", "picture"]`) und `params` (zusätzliche Schlüssel-Wert-Paare für den IdP).
$context	"signin" \| "signup" \| "use" \| "continue"	"signin"	Legt den Text im FedCM-Dialog fest, z. B. „Bei example.com anmelden“ oder „Bei example.com registrieren“.
$mode	"passive" \| "active"	"passive"	`"passive"` zeigt den Dialog ohne Nutzeraktion an. `"active"` muss durch eine Nutzeraktion ausgelöst werden (z. B. einen Klick) und zeigt einen modalen Dialog. In älteren Chrome-Versionen hießen die Werte `"widget"` und `"button"`.

Beispiele

Einfache FedCM-Anmeldung mit einem Identitätsanbieter

const signIn = async () => {
  // Unterstützt der Browser FedCM?
  if (!('IdentityCredential' in window)) {
    console.log('FedCM wird nicht unterstützt');
    return;
  }

  /** @type {IdentityCredentialRequestOptions} */
  const identity = {
    context: 'signin',
    providers: [
      {
        configURL: 'https://idp.example/fedcm.json',
        clientId: 'rp-client-123',
        nonce: crypto.randomUUID()
      }
    ]
  };

  try {
    const credential = await navigator.credentials.get({ identity });
    console.log('Token erhalten:', credential.token.slice(0, 12) + '…');
  } catch (err) {
    console.error('Anmeldung abgebrochen oder fehlgeschlagen:', err.name);
  }
};

signIn();

Token erhalten: eyJhbGciOiJS…

Aktiver Modus per Button-Klick mit Token-Prüfung im Backend

const button = document.querySelector('#login-idp');

button.addEventListener('click', async () => {
  const controller = new AbortController();

  try {
    const credential = await navigator.credentials.get({
      identity: {
        mode: 'active', // nur nach Nutzeraktion erlaubt
        context: 'continue',
        providers: [{
          configURL: 'https://idp.example/fedcm.json',
          clientId: 'rp-client-123',
          loginHint: 'anna@example.com',
          fields: ['name', 'email', 'picture']
        }]
      },
      signal: controller.signal
    });

    // Token serverseitig prüfen lassen
    const res = await fetch('/api/auth/fedcm', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: credential.token })
    });
    console.log('Server-Status:', res.status);
  } catch (err) {
    console.error(err.name, err.message);
  }
});

Server-Status: 200

Mehrere Identitätsanbieter zur Auswahl anbieten

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [
      { configURL: 'https://idp-a.example/fedcm.json', clientId: 'a-42' },
      { configURL: 'https://idp-b.example/config.json', clientId: 'b-99' }
    ]
  },
  mediation: 'optional'
});

// configURL zeigt, welcher Anbieter gewählt wurde
console.log(credential.configURL, credential.isAutoSelected);

https://idp-a.example/fedcm.json false

// Wichtig · Fallstricke

Browser-Unterstützung: FedCM ist experimentell und funktioniert nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Mit 'IdentityCredential' in window prüft man die Verfügbarkeit und bietet sonst einen Fallback an, etwa eine OAuth-Weiterleitung.
Sicherer Kontext: Die API steht nur über HTTPS zur Verfügung. In iframes muss die Permissions-Policy identity-credentials-get erlaubt sein.
Mit mode: "active" ohne Nutzeraktion wird das Promise abgelehnt. Mehrere providers gleichzeitig werden erst in neueren Chrome-Versionen unterstützt.
Die Namen und die Position einiger Optionen haben sich geändert: mode hieß früher "button"/"widget", und nonce wird inzwischen eher über params übergeben. Den aktuellen Stand der Spezifikation sollte man vor dem Einsatz prüfen.
Sicherheit: Das token muss immer serverseitig geprüft werden (Signatur, Aussteller, Zielgruppe/clientId, Nonce). Nur im Browser zu prüfen reicht nicht. Pro Anmeldeversuch sollte eine neue Nonce erzeugt werden, damit ein abgefangenes Token nicht erneut verwendet werden kann (Replay-Angriff).
Wenn der Nutzer den Dialog schließt, weil er abbricht oder weil der Browser nach wiederholtem Abbrechen eine Sperrzeit verhängt, wird das Promise mit einer DOMException abgelehnt, z. B. NetworkError oder AbortError. Diesen Fall sollte man sauber abfangen.

Siehe auch

PublicKeyCredentialRequestOptions IdentityCredentialError IdentityCredential PublicKeyCredentialCreationOptions CredentialsContainer