IdentityCredentialError.error — Eigenschaft · JavaScript-Referenz

Signatur

IdentityCredentialError.error

Beschreibung

Die schreibgeschützte Eigenschaft error der Schnittstelle IdentityCredentialError enthält den Fehlercode einer fehlgeschlagenen Anmeldung über die Federated Credential Management API (FedCM). Der Wert ist entweder einer der Fehlercodes aus der OAuth-2.0-Spezifikation oder ein beliebiger String mit weiteren Angaben zum Fehler.

Ein IdentityCredentialError entsteht, wenn navigator.credentials.get({ identity: … }) abgelehnt wird, weil der Identity Provider (IdP) an seinem ID-Assertion-Endpunkt statt eines Tokens eine Fehlerantwort liefert, z. B. {"error": {"code": "access_denied", "url": "https://idp.example/hilfe"}}. Der Browser übernimmt dabei code in die Eigenschaft error und url in die Eigenschaft url. Außerdem zeigt er dem Nutzer einen eigenen Fehlerdialog an.

Mit der Eigenschaft kann die Relying Party (die Website, auf der sich der Nutzer anmeldet) gezielt auf den Fehler reagieren: bei temporarily_unavailable einen neuen Versuch anbieten, bei access_denied auf eine andere Anmeldemethode umleiten oder den Fehler für die Fehleranalyse protokollieren.

Häufige Werte sind:

invalid_request: Die Anfrage ist fehlerhaft oder unvollständig.
unauthorized_client: Der Client darf keine Anmeldung anfordern.
access_denied: Der Nutzer oder der IdP hat den Zugriff abgelehnt.
server_error: Beim IdP ist ein interner Fehler aufgetreten.
temporarily_unavailable: Der IdP ist überlastet oder wird gerade gewartet.

Rückgabewert

Typ

string

Beschreibung

Der Fehlercode des IdP, zum Beispiel "access_denied", oder ein vom IdP frei gewählter String. Wenn der IdP keinen Code mitschickt, ist der Wert ein leerer String.

Beispiele

Fehlercode bei der FedCM-Anmeldung auswerten

const signIn = async () => {
  try {
    const credential = await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/fedcm.json',
          clientId: 'meine-client-id',
          nonce: crypto.randomUUID()
        }]
      }
    });
    return credential.token;
  } catch (e) {
    if (e instanceof IdentityCredentialError) {
      console.warn('IdP-Fehler:', e.error, e.url);
    } else {
      console.error('Anderer Fehler:', e.name, e.message);
    }
    return null;
  }
};

signIn();

IdP-Fehler: access_denied https://idp.example/hilfe

Je nach Fehlercode unterschiedlich reagieren

const handleIdentityError = (err) => {
  switch (err.error) {
    case 'temporarily_unavailable':
    case 'server_error':
      return 'Der Anmeldedienst ist gerade nicht erreichbar. Bitte später erneut versuchen.';
    case 'access_denied':
      return 'Zugriff verweigert. Bitte melde dich mit E-Mail und Passwort an.';
    case 'invalid_request':
    case 'unauthorized_client':
      return 'Konfigurationsfehler – bitte den Support kontaktieren.';
    default:
      return `Unbekannter Fehler: ${err.error || '(kein Code)'}`;
  }
};

// Test ohne echten IdP: Fehler von Hand erzeugen
const err = new IdentityCredentialError('Anmeldung fehlgeschlagen', {
  error: 'temporarily_unavailable',
  url: 'https://idp.example/status'
});
console.log(err.error);
console.log(handleIdentityError(err));

temporarily_unavailable Der Anmeldedienst ist gerade nicht erreichbar. Bitte später erneut versuchen.

Mit Feature-Erkennung sicher protokollieren

const logAuthError = (e) => {
  const isIdentityError =
    typeof IdentityCredentialError !== 'undefined' &&
    e instanceof IdentityCredentialError;

  const payload = {
    name: e.name,
    message: e.message,
    code: isIdentityError ? e.error : null,
    helpUrl: isIdentityError ? e.url : null
  };
  // Nur interne Daten verschicken, keine Tokens
  navigator.sendBeacon('/api/log/auth', JSON.stringify(payload));
  return payload;
};

// Wichtig · Fallstricke

Experimentell: Die FedCM Error API gibt es bisher nur in Chromium-Browsern (Chrome und Edge ab Version 120). In Firefox und Safari ist IdentityCredentialError nicht definiert. Prüfe deshalb vorher mit typeof IdentityCredentialError !== 'undefined', sonst wirft instanceof einen ReferenceError.
Die Eigenschaft steht nur zur Verfügung, wenn der IdP an seinem ID-Assertion-Endpunkt eine Fehlerantwort nach Spezifikation sendet. Viele andere Fehler (Nutzer schließt den Dialog, Netzwerkfehler, fehlerhafte configURL) kommen als normale DOMException, meist mit dem Namen NetworkError oder AbortError, und haben keine Eigenschaft error.
Der Wert kann ein beliebiger String sein. Verlasse dich nicht darauf, dass nur die OAuth-Codes vorkommen, und sieh immer einen default-Zweig vor.
Sicherheit: Der Wert stammt vom IdP. Gib ihn nicht ungefiltert per innerHTML aus, sondern mit textContent.
Der Browser zeigt bei solchen Fehlern bereits einen eigenen Fehlerdialog an. Eigene Hinweise sollten diesen ergänzen und nicht doppeln.

Siehe auch

IdentityCredentialError IdentityCredentialError.url IdentityCredential CredentialsContainer.get() DOMException PaymentRequestEvent.paymentRequestOrigin PublicKeyCredential.response