IdentityCredential — Schnittstelle · JavaScript-Referenz

Signatur

interface IdentityCredential extends Credential

Beschreibung

IdentityCredential ist der Ergebnistyp der Federated Credential Management API (FedCM). Damit lassen sich Anmeldungen per Identitätsanbieter (IdP, z. B. „Mit Google anmelden") umsetzen, ohne auf Drittanbieter-Cookies, Pop-ups oder Weiterleitungen angewiesen zu sein. Der Browser zeigt dafür einen eigenen, vertrauenswürdigen Konto-Auswahldialog an und vermittelt zwischen der vertrauenden Website (RP, Relying Party) und dem IdP.

Man erhält eine Instanz nicht per Konstruktor, sondern als aufgelösten Wert von navigator.credentials.get() mit der Option identity. Die wichtigste Eigenschaft ist token: ein vom IdP ausgestellter Wert (meist ein JWT/ID-Token), den die RP an ihren eigenen Server schickt und dort serverseitig prüft, bevor eine Sitzung angelegt wird.

IdentityCredential.token (nur lesbar) – der vom IdP ausgestellte Token als string.
IdentityCredential.isAutoSelected (nur lesbar) – true, wenn die Anmeldung per automatischer Wiederanmeldung (mediation: "optional"/"silent") ohne Benutzerinteraktion erfolgte.
IdentityCredential.configURL (nur lesbar, neuere Versionen) – die Konfigurations-URL des IdP, der den Nachweis ausgestellt hat.
Geerbt von Credential: id und type (immer "identity").
Statisch: IdentityCredential.disconnect(options) – trennt die Verbindung zwischen RP und IdP für ein Konto (Chrome 122+).

Einsatzgebiet sind Login-Buttons und Ein-Klick-Anmeldungen auf Websites, die einen oder mehrere externe Identitätsanbieter unterstützen. Die unten aufgeführten Parameter beschreiben die identity-Option von navigator.credentials.get(), mit der ein IdentityCredential angefordert wird.

Parameter

Name	Typ	Default	Beschreibung
$identity.providers Pflicht	Array<Object>		Liste der Identitätsanbieter. Jeder Eintrag enthält u. a. `configURL` (URL der IdP-Konfigurationsdatei), `clientId` (von IdP vergebene Client-ID der RP), optional `nonce`, `loginHint`, `domainHint` und `params`.
$identity.providers[].configURL Pflicht	string		Vollständige URL der `config.json` des IdP; der IdP muss zusätzlich `/.well-known/web-identity` bereitstellen.
$identity.providers[].clientId Pflicht	string		Kennung der vertrauenden Website beim IdP.
$identity.providers[].nonce	string		Zufallswert zum Schutz vor Replay-Angriffen; wird in den Token übernommen und serverseitig geprüft.
$identity.context	"signin" \| "signup" \| "use" \| "continue"	"signin"	Steuert die Formulierung im Browser-Dialog.
$identity.mode	"passive" \| "active"	"passive"	`"active"` (Button-Modus) erfordert eine Benutzeraktivierung, z. B. Klick auf einen Login-Button; neuere Chrome-Versionen.
$mediation	"optional" \| "required" \| "silent" \| "conditional"	"optional"	Steuert, ob eine automatische Wiederanmeldung erlaubt ist (`"silent"`/`"optional"`) oder immer eine Bestätigung verlangt wird (`"required"`).
$signal	AbortSignal		Ermöglicht das Abbrechen der laufenden Anfrage, z. B. per `AbortController`.

Rückgabewert

Typ

Promise<IdentityCredential | null>

Beschreibung

navigator.credentials.get() löst mit einem IdentityCredential auf, dessen token an den eigenen Server gesendet wird. Bei Abbruch durch den Nutzer oder fehlender Berechtigung wird das Promise mit einer DOMException (z. B. NetworkError, NotAllowedError, AbortError) abgelehnt.

Beispiele

IdentityCredential per FedCM anfordern

const signIn = async () => {
  if (!('IdentityCredential' in window)) {
    console.log('FedCM wird nicht unterstützt – Fallback auf Redirect-Login');
    return;
  }

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signin',
      providers: [{
        configURL: 'https://idp.example/fedcm/config.json',
        clientId: 'rp-client-123',
        nonce: crypto.randomUUID()
      }]
    },
    mediation: 'optional'
  });

  console.log(credential instanceof IdentityCredential, credential.type);
  console.log('Automatisch gewählt:', credential.isAutoSelected);
  return credential;
};

signIn();

true "identity" Automatisch gewählt: false

Token an den eigenen Server senden und prüfen lassen

const loginButton = document.querySelector('#login-fedcm');

loginButton.addEventListener('click', async () => {
  try {
    const { token } = await navigator.credentials.get({
      identity: {
        mode: 'active', // Button-Modus, benötigt Benutzeraktivierung
        providers: [{
          configURL: 'https://idp.example/fedcm/config.json',
          clientId: 'rp-client-123'
        }]
      }
    });

    const response = await fetch('/api/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token })
    });

    if (!response.ok) throw new Error('Token-Prüfung fehlgeschlagen');
    console.log('Angemeldet');
  } catch (err) {
    console.error(`Anmeldung fehlgeschlagen: ${err.name}`);
  }
});

Angemeldet

Abbruch mit AbortController nach Timeout

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10_000);

try {
  const credential = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm/config.json',
        clientId: 'rp-client-123'
      }]
    },
    signal: controller.signal
  });
  console.log('Token-Länge:', credential.token.length);
} catch (err) {
  if (err.name === 'AbortError') console.log('Anmeldedialog abgebrochen');
} finally {
  clearTimeout(timer);
}

Anmeldedialog abgebrochen

Verbindung zum IdP trennen (Abmelden/Konto entkoppeln)

const disconnectAccount = async (email) => {
  try {
    await IdentityCredential.disconnect({
      configURL: 'https://idp.example/fedcm/config.json',
      clientId: 'rp-client-123',
      accountHint: email
    });
    console.log('Verbindung getrennt');
  } catch (err) {
    console.error('Trennen fehlgeschlagen:', err.name);
  }
};

disconnectAccount('nutzer@example.com');

Verbindung getrennt

Siehe auch

IdentityCredentialError FederatedCredential OTPCredential Credential PasswordCredential