new IdentityCredentialError() — Methode · JavaScript-Referenz

Signatur

new IdentityCredentialError(message, options)

Beschreibung

Der Konstruktor IdentityCredentialError() erzeugt eine Instanz von IdentityCredentialError. Diese Klasse erweitert DOMException und gehört zur Federated Credential Management API (FedCM). Sie beschreibt Fehler, die ein Identitätsanbieter (IdP) während einer föderierten Anmeldung meldet, z. B. wenn der id_assertion_endpoint statt eines Tokens ein Fehlerobjekt zurückgibt.

Normalerweise erzeugt der Browser solche Objekte selbst: Das Promise von navigator.credentials.get({ identity: … }) wird mit einem IdentityCredentialError abgelehnt. Über die Eigenschaften error (Fehlercode, z. B. "invalid_request", "unauthorized_client", "access_denied", "server_error", "temporarily_unavailable") und url (Seite mit Erklärungen für Nutzer) kann die vertrauende Seite (Relying Party) passend reagieren.

Den Konstruktor selbst aufzurufen ist vor allem in Tests, Mocks und Polyfills sinnvoll, etwa um die Fehlerbehandlung der eigenen Anmeldelogik ohne echten Identitätsanbieter zu prüfen. Die Eigenschaft name der Instanz lautet immer "IdentityCredentialError".

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Fehlerbeschreibung; landet in der geerbten Eigenschaft `message`.
$options	object	{}	Optionales Konfigurationsobjekt mit den Feldern: `error` (`string`): Fehlercode des IdP, z. B. `"access_denied"`. Standard: `""`. `url` (`string`): URL einer Seite mit Hinweisen zum Fehler. Standard: `""`.

Rückgabewert

Typ

IdentityCredentialError

Beschreibung

Eine neue IdentityCredentialError-Instanz (Unterklasse von DOMException) mit den Eigenschaften name, message, error und url.

Beispiele

Instanz erzeugen und Eigenschaften lesen

const err = new IdentityCredentialError('Anmeldung abgelehnt', {
  error: 'access_denied',
  url: 'https://idp.example/hilfe/zugriff-verweigert'
});

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

IdentityCredentialError Anmeldung abgelehnt access_denied https://idp.example/hilfe/zugriff-verweigert true

FedCM-Fehler bei der Anmeldung behandeln

const signIn = async () => {
  try {
    const credential = await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/fedcm.json',
          clientId: 'meine-app-123'
        }]
      }
    });
    return credential.token;
  } catch (e) {
    if (typeof IdentityCredentialError !== 'undefined' &&
        e instanceof IdentityCredentialError) {
      console.warn(`IdP-Fehler: ${e.error || 'unbekannt'}`);
      if (e.url) console.info(`Weitere Infos: ${e.url}`);
    } else {
      console.error('Sonstiger Fehler:', e.name, e.message);
    }
    return null;
  }
};

signIn();

IdP-Fehler: temporarily_unavailable Weitere Infos: https://idp.example/status

Fehlerbehandlung im Test mit einem Mock prüfen

// navigator.credentials.get durch einen Mock ersetzen
const originalGet = navigator.credentials.get.bind(navigator.credentials);

navigator.credentials.get = async () => {
  throw new IdentityCredentialError('IdP nicht erreichbar', {
    error: 'server_error'
  });
};

const meldeFehler = (e) =>
  e.name === 'IdentityCredentialError' ? `FedCM: ${e.error}` : 'Unbekannt';

try {
  await navigator.credentials.get({ identity: { providers: [] } });
} catch (e) {
  console.log(meldeFehler(e));
} finally {
  navigator.credentials.get = originalGet; // Original wiederherstellen
}

FedCM: server_error

// Wichtig · Fallstricke

Experimentell: Die API ist nur in Chromium-Browsern (Chrome, Edge, Opera) ab etwa Version 120 verfügbar, Firefox und Safari unterstützen sie nicht. Vor der Nutzung mit typeof IdentityCredentialError !== 'undefined' auf Unterstützung prüfen.
In frühen Entwürfen hieß die Eigenschaft code statt error. Ältere Beispiele oder Implementierungen können deshalb abweichen.
Nur in sicheren Kontexten (HTTPS) verfügbar, wie die gesamte FedCM-API.
Nicht jeder Fehler aus navigator.credentials.get() ist ein IdentityCredentialError. Abbruch durch Nutzer oder ein AbortSignal ergibt z. B. einen normalen DOMException mit NetworkError bzw. AbortError. Daher immer per instanceof oder name unterscheiden.
Die url stammt vom Identitätsanbieter. Vor dem Anzeigen oder Verlinken sollte man sie prüfen, z. B. ob sie zur erwarteten IdP-Herkunft passt. So verhindert man, dass Nutzer auf fremde Seiten weitergeleitet werden.

Siehe auch

new DynamicsCompressorNode() new FederatedCredential() new GPUInternalError() new PasswordCredential() new QuotaExceededError()