RTCIdentityAssertion — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCIdentityAssertion

Beschreibung

Das Interface RTCIdentityAssertion gehört zur Identitäts-Erweiterung der WebRTC API. Es beschreibt, wer am anderen Ende einer Peer-to-Peer-Verbindung sitzt, und zwar so, wie es ein externer Identity Provider (IdP) bestätigt hat. Damit kann eine Anwendung prüfen, ob der Gesprächspartner tatsächlich der ist, der er zu sein vorgibt, und zwar unabhängig vom Signalisierungsserver, der ja theoretisch manipuliert sein könnte.

Instanzen bekommt man normalerweise nicht selbst erzeugt, sondern über die Eigenschaft RTCPeerConnection.peerIdentity. Sie liefert ein Promise, das mit einem RTCIdentityAssertion erfüllt wird, sobald die Identitätsbestätigung (Assertion) aus der entfernten SDP-Beschreibung vom IdP geprüft wurde. Scheitert die Prüfung, wird das Promise abgelehnt.

Das Objekt hat zwei Eigenschaften:

idp (string): die Domain des Identity Providers, der die Identität bestätigt hat, z. B. "idp.example.org".
name (string): die bestätigte Identität des Peers in der Form benutzer@domain (RFC-5322-Adressformat).

Die Gegenseite legt ihren IdP vorher mit RTCPeerConnection.setIdentityProvider() fest. Nutzen lässt sich das Ganze für Ende-zu-Ende-authentifizierte Anrufe, zum Beispiel wenn man einen Kontakt verifiziert anzeigen oder Medien nur an einen bestimmten Peer freigeben will (Option peerIdentity bei getUserMedia()/RTCPeerConnection).

Parameter

Name	Typ	Default	Beschreibung
$idp Pflicht	string		Konstruktor-Parameter bzw. Eigenschaft: Domain des Identity Providers, der die Identität bestätigt hat.
$name Pflicht	string		Konstruktor-Parameter bzw. Eigenschaft: bestätigte Identität des entfernten Peers im Format `benutzer@domain`.

Beispiele

Identität des entfernten Peers auslesen

const pc = new RTCPeerConnection();

// ... Signalisierung: Offer/Answer austauschen, setRemoteDescription() aufrufen ...

const zeigePeerIdentitaet = async () => {
  try {
    const assertion = await pc.peerIdentity; // RTCIdentityAssertion
    console.log(`Bestätigt durch: ${assertion.idp}`);
    console.log(`Gesprächspartner: ${assertion.name}`);
  } catch (err) {
    console.warn('Identität konnte nicht verifiziert werden:', err);
  }
};

zeigePeerIdentitaet();

Bestätigt durch: idp.example.org Gesprächspartner: alice@example.org

Eigenen Identity Provider setzen (Gegenseite)

const pc = new RTCPeerConnection();

// Die Gegenseite registriert ihren IdP – die Assertion wird dann in die SDP eingebettet
pc.setIdentityProvider('idp.example.org', {
  protocol: 'default',
  usernameHint: 'alice@example.org'
});

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
console.log(offer.sdp.includes('a=identity'));

true

Erwarteten Kontakt prüfen und in der UI markieren

const pruefeKontakt = async (pc, erwartet) => {
  if (!('peerIdentity' in RTCPeerConnection.prototype)) {
    return 'nicht unterstützt';
  }
  try {
    const { idp, name } = await pc.peerIdentity;
    return name === erwartet ? `verifiziert (${idp})` : `WARNUNG: ${name}`;
  } catch {
    return 'nicht verifiziert';
  }
};

const status = await pruefeKontakt(pc, 'bob@example.net');
document.querySelector('#status').textContent = status;

verifiziert (idp.example.net)

Objekt direkt erzeugen (laut Spezifikation)

// Nur zu Testzwecken; normalerweise liefert der Browser die Instanz
if (typeof RTCIdentityAssertion === 'function') {
  const assertion = new RTCIdentityAssertion('idp.example.org', 'carol@example.org');
  console.log(assertion.idp, assertion.name);
}

idp.example.org carol@example.org

// Wichtig · Fallstricke

Browser-Kompatibilität: Die WebRTC-Identitäts-API ist experimentell und wird praktisch nur von Firefox unterstützt. Chrome, Edge und Safari kennen weder RTCIdentityAssertion noch peerIdentity oder setIdentityProvider(). Deshalb vor der Nutzung immer eine Funktionserkennung machen ('peerIdentity' in RTCPeerConnection.prototype). Ob sich der Konstruktor direkt aufrufen lässt, ist je nach Implementierung verschieden.

Das Promise von peerIdentity wird erst erfüllt, wenn eine entfernte Beschreibung mit gültiger Identitätsbestätigung gesetzt ist. Fehlt die Assertion, bleibt es unter Umständen lange offen. Eine Zeitbegrenzung (Timeout) ist deshalb sinnvoll.
Den IdP-Code lädt der Browser von https://<idp>/.well-known/idp-proxy/<protocol>. Das funktioniert nur in sicheren Kontexten (HTTPS).
Sicherheit: Die Bestätigung ist nur so vertrauenswürdig wie der IdP. Prüfen Sie immer beide Werte, idp und name, gegen eine Liste zugelassener Anbieter. Der Benutzername allein reicht nicht.
Nachdem die Identität einmal festgelegt ist, kann sie sich während der Verbindung nicht mehr ändern. Eine abweichende neue Assertion führt zu einem Fehler.

Siehe auch

RTCPeerConnection RTCPeerConnection.peerIdentity RTCPeerConnection.setIdentityProvider() RTCPeerConnection.getIdentityAssertion() RTCSessionDescription