IdentityCredentialError — Schnittstelle · JavaScript-Referenz

Signatur

interface IdentityCredentialError extends DOMException

Beschreibung

IdentityCredentialError gehört zur Federated Credential Management API (FedCM). Das Promise von navigator.credentials.get({ identity: … }) wird mit einem solchen Objekt abgewiesen, wenn der Nutzer im Browser-Dialog zwar ein Konto ausgewählt hat, der Identitätsanbieter aber am id_assertion_endpoint kein Token ausstellt. Stattdessen antwortet der IdP mit einem Fehlerobjekt (z. B. {"error": {"code": "access_denied", "url": "https://idp.example/hilfe"}}). Der Browser leitet diese Angaben an die vertrauende Seite (Relying Party, RP) weiter.

Das Interface erbt von DOMException. Deshalb stehen name (immer "IdentityCredentialError") und message zur Verfügung. Dazu kommen zwei eigene, schreibgeschützte Eigenschaften:

error: ein Fehlercode als Zeichenkette. Häufig werden OAuth-ähnliche Werte verwendet, etwa "invalid_request", "unauthorized_client", "access_denied", "server_error" oder "temporarily_unavailable". Der IdP darf aber auch eigene Codes senden.
url: eine vom IdP angegebene URL mit menschenlesbaren Informationen zum Fehler, zum Beispiel eine Hilfeseite.

Typischerweise nutzt man das Interface, um im catch-Block zwischen einem IdP-Fehler und anderen Fehlern zu unterscheiden. Andere Fehler sind etwa NotAllowedError, wenn der Nutzer den Dialog schließt, oder NetworkError. So kann die RP gezielt reagieren: einen erneuten Versuch anbieten, auf die Hilfe-URL verweisen oder auf eine klassische Anmeldung umschalten. Der Konstruktor ist vor allem für Tests und Polyfills gedacht, im normalen Betrieb erzeugt der Browser die Instanz.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Konstruktor-Parameter: menschenlesbare Fehlerbeschreibung, landet in `message`.
$options	{ error?: string, url?: string }	{}	Konstruktor-Parameter: Objekt mit dem Fehlercode `error` und der Hilfe-URL `url`. Beide Werte werden als gleichnamige Eigenschaften bereitgestellt.

Rückgabewert

Typ

IdentityCredentialError

Beschreibung

Eine neue Instanz mit name === "IdentityCredentialError" und den Eigenschaften message, error und url.

Beispiele

FedCM-Anmeldung mit Auswertung des IdP-Fehlers

const signIn = async () => {
  try {
    const credential = await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/fedcm.json',
          clientId: 'rp-123',
          nonce: crypto.randomUUID()
        }]
      }
    });
    // Token zur Prüfung an das eigene Backend schicken
    await fetch('/api/login', { method: 'POST', body: credential.token });
  } catch (err) {
    if (err.name === 'IdentityCredentialError') {
      console.warn(`IdP-Fehler: ${err.error}`, err.url);
    } else if (err.name === 'NotAllowedError') {
      console.info('Anmeldung abgebrochen oder nicht erlaubt.');
    } else {
      console.error('Unerwarteter Fehler:', err);
    }
  }
};

document.querySelector('#login').addEventListener('click', signIn);

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

Nutzerfreundliche Meldungen je Fehlercode

const messages = {
  access_denied: 'Der Anbieter hat den Zugriff verweigert.',
  temporarily_unavailable: 'Der Anbieter ist gerade nicht erreichbar. Bitte später erneut versuchen.',
  server_error: 'Beim Anbieter ist ein Fehler aufgetreten.'
};

const showIdpError = (err) => {
  const text = messages[err.error] ?? 'Anmeldung fehlgeschlagen.';
  const box = document.querySelector('#fehler');
  box.textContent = text; // textContent statt innerHTML – kein XSS
  if (err.url) {
    const link = document.createElement('a');
    link.href = new URL(err.url).href;
    link.textContent = ' Mehr erfahren';
    link.rel = 'noopener';
    link.target = '_blank';
    box.append(link);
  }
};

Instanz im Test manuell erzeugen

const err = new IdentityCredentialError('Token konnte nicht ausgestellt werden', {
  error: 'temporarily_unavailable',
  url: 'https://idp.example/status'
});

console.log(err.name);
console.log(err instanceof DOMException);
console.log(err.error, err.url);

IdentityCredentialError true temporarily_unavailable https://idp.example/status

// Wichtig · Fallstricke

Kompatibilität: Das Interface ist experimentell und nur in Chromium-basierten Browsern verfügbar. Prüfe die Unterstützung vorab, z. B. mit 'IdentityCredential' in window bzw. typeof IdentityCredentialError !== 'undefined'. Sieh außerdem immer einen klassischen Anmeldeweg als Rückfall vor.
In frühen Entwürfen hieß die Eigenschaft code statt error. Ältere Browserversionen oder Beispiele können deshalb abweichen.
Ein IdentityCredentialError entsteht nur, wenn der IdP ausdrücklich ein Fehlerobjekt zurückgibt. Schließt der Nutzer den Dialog oder blockiert der Browser FedCM, z. B. wegen einer Abkühlphase nach mehrmaligem Abbrechen oder wegen deaktivierter Einstellungen, erhältst du meist einen NotAllowedError. Netzwerkprobleme führen zu einem NetworkError.
Sicherheit: error und url stammen vom IdP und sind aus Sicht der RP fremde Daten. Füge sie nie per innerHTML ein, sondern verwende textContent. Prüfe außerdem, ob die URL das Schema https: hat, bevor du sie als Link anzeigst.
Browser zeigen dem Nutzer ggf. selbst einen Fehlerdialog an. Deine Anwendung sollte dieselbe Meldung nicht noch einmal aufdringlich wiederholen.
FedCM benötigt einen sicheren Kontext (HTTPS). In iframes ist die Permissions-Policy identity-credentials-get erforderlich.

Siehe auch

Credential IdentityCredential IdentityProvider FederatedCredential FederatedCredentialInit