PublicKeyCredential.signalUnknownCredential() — Methode · JavaScript-Referenz

Signatur

PublicKeyCredential.signalUnknownCredential(options)

Beschreibung

Die statische Methode PublicKeyCredential.signalUnknownCredential() gehört zur WebAuthn Signal API. Mit ihr meldet eine Relying Party (RP) dem Browser und damit dem Passkey-Anbieter (z. B. Google Passwortmanager, iCloud-Schlüsselbund), dass eine Credential-ID auf dem Server nicht bekannt ist. Das passiert typischerweise, wenn der Nutzer seinen Passkey serverseitig gelöscht hat, das Konto entfernt wurde oder eine Registrierung nie vollständig abgeschlossen wurde.

Ohne dieses Signal bietet der Authenticator dem Nutzer den veralteten Passkey bei jeder Anmeldung weiter an, was zu fehlgeschlagenen Logins und Verwirrung führt. Nach dem Signal kann der Anbieter den Eintrag entfernen oder ausblenden. Was genau passiert, entscheidet der Authenticator. Die Methode gibt keine Rückmeldung darüber, ob tatsächlich etwas gelöscht wurde.

Üblich ist der Aufruf direkt nach einer fehlgeschlagenen Anmeldung: navigator.credentials.get() liefert eine Assertion, der Server findet die zugehörige Credential-ID aber nicht in seiner Datenbank. Dann ruft der Client signalUnknownCredential() mit der RP-ID und der Credential-ID im Base64URL-Format auf. Anders als signalAllAcceptedCredentials() betrifft das Signal genau eine Credential und braucht keine Benutzer-ID. Deshalb eignet es sich auch für nicht angemeldete Nutzer.

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Objekt, das die unbekannte Credential beschreibt.
$options.rpId Pflicht	string	Die RP-ID, also die Domain der Relying Party (z. B. `"example.com"`). Sie muss zur aktuellen Origin passen, also gleich der Domain oder eine registrierbare übergeordnete Domain sein.
$options.credentialId Pflicht	string	Die Credential-ID als Base64URL-kodierter String. Das entspricht dem Wert von `PublicKeyCredential.id`, nicht `rawId`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Signal angenommen wurde. Es sagt nicht, ob der Authenticator die Credential tatsächlich gelöscht hat. Es wird abgelehnt mit SecurityError, wenn die RP-ID nicht zur Origin passt, und mit TypeError, wenn credentialId kein gültiges Base64URL ist.

Beispiele

Feature-Erkennung und einfacher Aufruf

// Nur aufrufen, wenn der Browser die Signal API unterstützt
if (window.PublicKeyCredential &&
    typeof PublicKeyCredential.signalUnknownCredential === 'function') {
  await PublicKeyCredential.signalUnknownCredential({
    rpId: 'example.com',
    credentialId: 'vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA' // Base64URL
  });
  console.log('Signal gesendet');
} else {
  console.log('Signal API nicht verfügbar');
}

Signal gesendet

Veralteten Passkey nach fehlgeschlagenem Login melden

const loginMitPasskey = async () => {
  const optionen = await fetch('/webauthn/login/options').then(r => r.json());
  // challenge vom Server (Base64URL) in ArrayBuffer umwandeln (Chrome 129+ / Safari 18.4+)
  const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(optionen);

  const credential = await navigator.credentials.get({ publicKey });

  const antwort = await fetch('/webauthn/login/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(credential.toJSON())
  });

  if (antwort.status === 404) {
    // Server kennt diese Credential-ID nicht (mehr)
    if (PublicKeyCredential.signalUnknownCredential) {
      await PublicKeyCredential.signalUnknownCredential({
        rpId: publicKey.rpId ?? location.hostname,
        credentialId: credential.id // bereits Base64URL
      });
    }
    throw new Error('Dieser Passkey ist nicht mehr gültig. Bitte anders anmelden.');
  }
  return antwort.json();
};

Fehlerbehandlung bei ungültigen Eingaben

try {
  await PublicKeyCredential.signalUnknownCredential({
    rpId: 'fremde-domain.de', // passt nicht zur aktuellen Origin
    credentialId: 'abc123'
  });
} catch (err) {
  if (err.name === 'SecurityError') {
    console.error('RP-ID passt nicht zur Origin');
  } else if (err instanceof TypeError) {
    console.error('credentialId ist kein gültiges Base64URL');
  } else {
    throw err;
  }
}

RP-ID passt nicht zur Origin

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode kommt aus WebAuthn Level 3 und ist bisher nur in Chromium-Browsern (ab Version 132) und neueren Safari-Versionen verfügbar. Prüfe sie immer vorher mit typeof PublicKeyCredential.signalUnknownCredential === 'function'.
Base64URL, nicht ArrayBuffer: credentialId muss ein Base64URL-String ohne Padding sein. Übergib credential.id, nicht credential.rawId.
Keine Erfolgsgarantie: Das Promise wird auch dann erfüllt, wenn der Authenticator die Credential gar nicht kennt oder das Signal ignoriert. Baue keine Logik darauf auf, dass danach gelöscht wurde.
Datenschutz: Aus Datenschutzgründen gibt es weder eine Nutzerinteraktion noch eine Rückmeldung. Sende das Signal nur, wenn der Server die ID wirklich nicht kennt. Wird es fälschlich gesendet, verliert der Nutzer womöglich einen gültigen Passkey.
Die Methode braucht einen sicheren Kontext (HTTPS) und muss mit einer RP-ID aufgerufen werden, die zur Origin passt.
Um mehrere Credentials auf einmal abzugleichen, nutze signalAllAcceptedCredentials(). Dafür muss der Nutzer angemeldet sein.

Siehe auch

PublicKeyCredential.signalCurrentUserDetails() PublicKeyCredential.signalAllAcceptedCredentials() PublicKeyCredential.getClientCapabilities() PublicKeyCredential.getClientExtensionResults() PublicKeyCredential.toJSON()