PublicKeyCredential.signalCurrentUserDetails() — Methode · JavaScript-Referenz

Signatur

PublicKeyCredential.signalCurrentUserDetails(options)

Beschreibung

Die statische Methode PublicKeyCredential.signalCurrentUserDetails() gehört zur WebAuthn Signal API. Mit ihr meldet eine Website (die Relying Party, kurz RP) dem Browser und damit dem Authentifikator bzw. Passkey-Anbieter (z. B. Google Passwortmanager, iCloud-Schlüsselbund, 1Password), wie der aktuelle name und displayName eines Benutzerkontos lauten.

Das Problem dahinter: Beim Anlegen eines Passkeys per navigator.credentials.create() werden user.name und user.displayName im Authentifikator gespeichert und später in der Kontoauswahl angezeigt. Ändert der Benutzer auf der Website seine E-Mail-Adresse oder seinen Namen, zeigt der Passkey-Anbieter sonst weiterhin die veralteten Daten an. Mit signalCurrentUserDetails() lässt sich das synchronisieren.

Typische Einsatzzeitpunkte sind direkt nach einer erfolgreichen Anmeldung sowie nach einer Änderung der Profildaten. Die Methode ist ein reines Signal: Der Browser gibt keine Auskunft darüber, ob überhaupt ein passender Passkey existiert oder ob der Anbieter die Daten tatsächlich übernommen hat – das schützt die Privatsphäre des Benutzers. Das Promise wird in der Regel erfüllt, sobald die Eingaben gültig sind.

Der Benutzer wird über die Kombination aus rpId und userId identifiziert. Die userId muss exakt dem user.id entsprechen, das bei der Registrierung verwendet wurde, allerdings Base64URL-kodiert als String.

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Objekt mit den aktuellen Benutzerdaten. Alle folgenden Eigenschaften sind Pflicht.
$options.rpId Pflicht	string	ID der Relying Party, i. d. R. die registrierbare Domain (z. B. `"example.com"`). Muss zum Ursprung der aufrufenden Seite passen.
$options.userId Pflicht	string	Base64URL-kodierte Benutzer-ID, identisch mit dem `user.id` bei der Passkey-Erstellung (ohne Padding `=`).
$options.name Pflicht	string	Aktueller Benutzername bzw. Kontokennung, z. B. die E-Mail-Adresse.
$options.displayName Pflicht	string	Aktueller, für Menschen lesbarer Anzeigename, z. B. `"Anna Schmidt"`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Promise, das mit undefined erfüllt wird, sobald das Signal angenommen wurde. Es wird mit einem SecurityError (ungültige oder nicht passende rpId) bzw. einem TypeError (z. B. userId kein gültiges Base64URL) abgelehnt. Eine Erfüllung bedeutet nicht, dass ein Passkey aktualisiert wurde.

Beispiele

Benutzerdaten nach erfolgreicher Anmeldung synchronisieren

// Nach erfolgreicher Passkey-Anmeldung liefert der Server die aktuellen Profildaten
const syncPasskeyDetails = async (user) => {
  // Feature-Erkennung: nicht jeder Browser kennt die Signal API
  if (typeof PublicKeyCredential?.signalCurrentUserDetails !== 'function') {
    console.log('Signal API nicht verfügbar');
    return;
  }

  await PublicKeyCredential.signalCurrentUserDetails({
    rpId: 'example.com',
    userId: user.webauthnUserId, // Base64URL-String, z. B. 'dXNlci0xMjM0'
    name: user.email,
    displayName: user.fullName
  });
  console.log('Benutzerdaten an Passkey-Anbieter gemeldet');
};

syncPasskeyDetails({
  webauthnUserId: 'dXNlci0xMjM0',
  email: 'anna.schmidt@example.com',
  fullName: 'Anna Schmidt'
});

Benutzerdaten an Passkey-Anbieter gemeldet

Nach Profiländerung signalisieren – mit Fehlerbehandlung

const form = document.querySelector('#profil-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const data = Object.fromEntries(new FormData(form));

  // Profil zuerst serverseitig speichern
  const res = await fetch('/api/profil', {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  const profil = await res.json();

  try {
    await PublicKeyCredential.signalCurrentUserDetails?.({
      rpId: location.hostname,
      userId: profil.webauthnUserId,
      name: profil.email,
      displayName: profil.displayName
    });
  } catch (err) {
    // Signal-Fehler sollen den Speichervorgang nicht blockieren
    console.warn(`Signal fehlgeschlagen: ${err.name}`);
  }
});

ArrayBuffer-User-ID in Base64URL umwandeln

// Falls die User-ID als Bytes vorliegt (wie bei create()), zuerst kodieren
const toBase64Url = (buffer) =>
  btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');

const userIdBytes = new TextEncoder().encode('user-1234');
const userId = toBase64Url(userIdBytes);
console.log(userId);

await PublicKeyCredential.signalCurrentUserDetails({
  rpId: 'example.com',
  userId,
  name: 'anna.schmidt@example.com',
  displayName: 'Anna Schmidt'
});

dXNlci0xMjM0

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Methode ist Teil der recht neuen WebAuthn Signal API und steht in Chromium-Browsern ab Version 132 zur Verfügung. Andere Browser unterstützen sie teils noch nicht. Immer per Feature-Erkennung (typeof PublicKeyCredential?.signalCurrentUserDetails === 'function') oder über PublicKeyCredential.getClientCapabilities() prüfen.
Nur in einem sicheren Kontext (HTTPS) verfügbar.
userId ist ein Base64URL-String, kein ArrayBuffer. Standard-Base64 mit +, / oder = führt zu einem TypeError.
Die rpId muss zum Ursprung passen (gleiche Domain oder übergeordnete registrierbare Domain), sonst gibt es einen SecurityError.
Ein erfülltes Promise garantiert nicht, dass ein Passkey existiert oder aktualisiert wurde. Ob und wie der Anbieter die Daten übernimmt, entscheidet er selbst. Die Anwendungslogik darf also nicht vom Ergebnis abhängen.
Nur aufrufen, wenn der Benutzer authentifiziert ist. Sonst könnten Dritte Kontodaten eines fremden Benutzers erraten oder melden.

Siehe auch

PublicKeyCredential PublicKeyCredential.signalAllAcceptedCredentials() PublicKeyCredential.signalUnknownCredential() PublicKeyCredential.getClientCapabilities() CredentialsContainer.create() CredentialsContainer.get() PublicKeyCredential.parseRequestOptionsFromJSON()