Passkeys / WebAuthn

WebAuthn (Web Authentication, Teil des FIDO2-Standards) ermöglicht passwortlose und Zwei-Faktor-Authentifizierung mit Gerätebiometrie (Touch ID, Face ID, Windows Hello), in das Betriebssystem integrierten Plattform-Authentifikatoren oder mobilen Hardware-Sicherheitsschlüsseln (YubiKey, Titan Key).

Auris implementiert die WebAuthn-API sowohl als eigenständige passwortlose Authentifizierungsmethode als auch als 2FA-Zweifaktor nach E-Mail/Passwort-Login.

Browser-Unterstützung

WebAuthn wird in allen modernen Browsern unterstützt:

Funktionsweise

Registrierungs-Flow

Authentifizierungs-Flow

Client-seitige Bibliothek

Auris verwendet @simplewebauthn/browser auf der Client-Seite, um die Browser-WebAuthn-API-Aufrufe zu verwalten. Diese Bibliothek abstrahiert Browser-Kompatibilitätsprobleme und bietet typisierte Wrapper um navigator.credentials.create() und navigator.credentials.get().

npm install @simplewebauthn/browser

Implementierung

Passkey registrieren

import { startRegistration } from '@simplewebauthn/browser'
 
async function registerPasskey(accessToken) {
  // Schritt 1: Registrierungsoptionen von Auris abrufen
  const optionsResponse = await fetch('/api/user/2fa/webauthn/challenge', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ type: 'registration' }),
  })
  const options = await optionsResponse.json()
 
  // Schritt 2: Browser fordert Benutzer zur Biometrie/Sicherheitsschlüssel auf
  let credential
  try {
    credential = await startRegistration(options)
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.error('Benutzer hat abgebrochen oder Zeitüberschreitung')
      return
    }
    throw err
  }
 
  // Schritt 3: Credential an Auris senden
  const verifyResponse = await fetch('/api/user/2fa/webauthn', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      credential,
      name: 'Mein MacBook', // Vom Benutzer angegebener Name für das Credential
    }),
  })
 
  const result = await verifyResponse.json()
  if (result.verified) {
    console.log('Passkey erfolgreich registriert')
  }
}

import { useState } from 'react'
import { startRegistration } from '@simplewebauthn/browser'
import { useAuris } from '@auris/react'
 
function PasskeyManager() {
  const { getAccessToken } = useAuris()
  const [credentials, setCredentials] = useState([])
  const [name, setName] = useState('')
  const [registering, setRegistering] = useState(false)
 
  async function handleRegister() {
    setRegistering(true)
    try {
      const token = await getAccessToken()
 
      const optionsRes = await fetch('/api/user/2fa/webauthn/challenge', {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ type: 'registration' }),
      })
      const options = await optionsRes.json()
 
      const credential = await startRegistration(options)
 
      const verifyRes = await fetch('/api/user/2fa/webauthn', {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ credential, name }),
      })
      const result = await verifyRes.json()
 
      if (result.verified) {
        setCredentials((prev) => [...prev, result.credential])
        setName('')
      }
    } finally {
      setRegistering(false)
    }
  }
 
  async function handleDelete(credentialId) {
    const token = await getAccessToken()
    await fetch(`/api/user/2fa/webauthn/${credentialId}`, {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${token}` },
    })
    setCredentials((prev) => prev.filter((c) => c.id !== credentialId))
  }
 
  return (
    <div>
      <h3>Registrierte Passkeys</h3>
      {credentials.map((cred) => (
        <div key={cred.id}>
          <span>{cred.name}</span>
          <span>{cred.createdAt}</span>
          <button onClick={() => handleDelete(cred.id)}>Entfernen</button>
        </div>
      ))}
 
      <div>
        <input
          placeholder="Gerätename (z. B. Mein MacBook)"
          value={name}
          onChange={(e) => setName(e.target.value)}
        />
        <button onClick={handleRegister} disabled={registering || !name}>
          {registering ? 'Geräteaufforderung folgen...' : 'Passkey hinzufügen'}
        </button>
      </div>
    </div>
  )
}

Mit Passkey authentifizieren

import { startAuthentication } from '@simplewebauthn/browser'
 
async function authenticateWithPasskey() {
  // Schritt 1: Authentifizierungsoptionen von Auris abrufen
  const optionsResponse = await fetch('/api/auth/webauthn/challenge', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
  })
  const options = await optionsResponse.json()
 
  // Schritt 2: Browser fordert Benutzer auf (Biometrie oder Key-Tipp)
  let assertion
  try {
    assertion = await startAuthentication(options)
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.error('Benutzer hat abgebrochen oder kein passendes Credential gefunden')
      return
    }
    throw err
  }
 
  // Schritt 3: Assertion verifizieren und Tokens empfangen
  const verifyResponse = await fetch('/api/auth/webauthn/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ assertion }),
  })
 
  const result = await verifyResponse.json()
  if (result.accessToken) {
    // Tokens speichern und weiterleiten
    console.log('Authentifiziert als:', result.user)
  }
}

WebAuthn als 2FA

Wenn als zweiter Faktor (statt als eigenständige passwortlose Methode) konfiguriert, wird WebAuthn nach dem ersten Faktor (E-Mail/Passwort oder Social) verwendet.

Konfiguration: WebAuthn-2FA in Console → Authentication → Multi-Factor Authentication → Passkeys aktivieren.

2FA-Flow:

1. Benutzer schließt Erstauthentifizierung ab
2. Auris stellt ein Partial-Session-Token aus (kein vollständiges Access Token)
3. Deine Anwendung verwendet das Partial-Token, um den WebAuthn-Challenge-Endpunkt aufzurufen
4. Benutzer tippt auf seinen Sicherheitsschlüssel oder scannt Biometrie
5. Assertion wird verifiziert; Auris stellt vollständige Access- und Refresh-Tokens aus

Credential-Verwaltung

Benutzer können mehrere Credentials registrieren — eines pro Gerät oder Sicherheitsschlüssel. Jedem Credential kann ein sprechender Name zur Identifikation gegeben werden.

Best Practice ist es, Benutzern die Registrierung von mindestens zwei Credentials zu ermöglichen (z. B. Touch ID eines Laptops und ein Hardware-Schlüssel), damit sie ein Backup haben, wenn ein Gerät verloren geht.

Auris speichert pro Credential:

• Credential-ID (Base64url-kodiert, eindeutige Kennung)
• Öffentlicher Schlüssel (COSE-Format)
• Signatur-Zähler (wird bei jeder Verwendung erhöht; Auris erkennt Authentifikator-Klonen, wenn der Zähler zurückgeht)
• Vom Benutzer angegebener Name
• Zeitstempel der letzten Verwendung
• Erstellungszeitstempel
• Authentifikator-Anhangtyp (Plattform oder Cross-Plattform)

Sicherheitsüberlegungen

Phishing-Resistenz — WebAuthn-Credentials sind an den Relying-Party-Ursprung (rpId, also deine Domain) gebunden. Eine Phishing-Site auf einer anderen Domain kann keine für deine Domain ausgestellten Credentials verwenden. Dies ist ein erheblicher Vorteil gegenüber Passwörtern und OTP-Codes.

Keine gemeinsamen Geheimnisse — Der private Schlüssel verlässt niemals den Authentifikator. Auris speichert nur den öffentlichen Schlüssel. Ein Datenbankbruch legt kein Credential-Material frei.

Signatur-Zähler-Validierung — Auris verfolgt den internen Signaturzähler des Authentifikators. Wenn eine Assertion mit einem Zähler gleich oder kleiner dem gespeicherten Wert eintrifft, markiert Auris das Credential als potenziell geklont und erfordert eine Überprüfung.

Resident Keys und auffindbare Credentials — Wenn residentKey: required gesetzt ist, wird das Credential auf dem Authentifikator selbst gespeichert und kann ohne vorherige Angabe eines Benutzernamens verwendet werden (Benutzername-loser Login). Dies ist die Grundlage moderner Passkey-Flows.

Verwandte Anleitungen

• SMS OTP — Telefonbasierter zweiter Faktor
• Hosted Login (PKCE) — Standard-interaktiver Authentifizierungs-Flow
• Magic Links — E-Mail-basierte passwortlose Authentifizierung