Anwendungsfälle für Hauptschlüssel

In diesem Thema werden einige Anwendungsfälle für Passkeys beschrieben.

Anwendungsfall 1: Bootstrapping

Bootstrapping eines Kontos im Web.

1.1: Authentifizieren des Benutzers

Dieser Abschnitt gilt, wenn die vertrauende Seite (RP) noch nicht weiß, wer das Clientgerät steuert. Es ist kein Browserartefakt für das RP verfügbar (z. B. ein Cookie oder eine Anmeldeinformations-ID im lokalen Speicher), obwohl wir derzeit davon ausgehen, dass der Benutzer über ein vorhandenes Konto mit dem RP verfügt.

Um ein Konto zu starten, dienen Sie dem Benutzer eine Anmeldeseite.

Beginnen Sie, indem Sie den Benutzer zur Eingabe seines Kontobezeichners fragen; in der Regel ein Benutzername oder eine E-Mail-Adresse.

Um die Benutzeroberfläche für autoAusfüllen für Passkeys zu unterstützen, stellen Sie folgendes sicher:

1. Fügen Sie den username Wert allen webauthn vorhandenen AutoVervollständigen-Anmerkungen im Eingabefeld für Den Benutzernamen hinzu.

<div>
  <label for="username">Username:</label>
  <input name="username" id="loginform.username"
         autocomplete="username webauthn">
</div>

2. Verwenden Sie beim Laden der Seite eine if Anweisung, um zu überprüfen, ob die Benutzeroberfläche für das automatische Ausfüllen (bedingte Vermittlung) verfügbar ist, und rufen navigator.credentials.get() Sie dann mit mediation: "conditional" und .userVerification: "preferred"

  <script>
    (async () => {
      if (
      typeof window.PublicKeyCredential !== 'undefined'
      && typeof window.PublicKeyCredential.isConditionalMediationAvailable === 'function'
      ) {
        const available = await PublicKeyCredential.isConditionalMediationAvailable();

      if (available) {
          try {
            // Retrieve authentication options for `navigator.credentials.get()`
            // from your server.
            const authOptions = await getAuthenticationOptions();
      // This call to `navigator.credentials.get()` is "set and forget."
      // The Promise will resolve only if the user successfully interacts
      // with the browser's autofill UI to select a passkey.
      const webAuthnResponse = await navigator.credentials.get({
          mediation: "conditional",
      publicKey: {
          ...authOptions,
          // See note about userVerification below.
          userVerification: "preferred",
              }
            });
      // Send the response to your server for verification, and
      // authenticate the user if the response is valid.
      await verifyAutoFillResponse(webAuthnResponse);
          } catch (err) {
          console.error('Error with conditional UI:', err);
          }
        }
      }
    })();
  </script>

Die oben genannten Ursachen führen dazu, dass Folgendes geschieht:

• Rufen Sie die Authentifizierungsoptionen vom Server ab. Geben Sie mindestens ein Zufälliges challenge zurück und rpId werden dieser Authentifizierungsanforderung zugeordnet.
• Wenn der Benutzer mit Ihrem Benutzernamenfeld interagiert, überprüft der Browser und die Plattform, ob ein Kennungsschlüssel (im Plattformauthentifikator) vorhanden ist, der mit der vertrauenden Seite verwendet werden kann.
• Wenn dies der Fall ist , wird dem Benutzer der Passkey als Option zur Auswahl angezeigt (zusammen mit anderen Anmeldeinformationen, die automatisch ausgefüllt werden können, z. B. Benutzernamen, die im Kennwort-Manager des Browsers gespeichert sind). Der Browser/die Plattform kann eine Benutzeroberfläche ähnlich wie die unten gezeigte rendern. Obwohl das genaue Aussehen und Verhalten von einer Plattform oder einem Formfaktor zu einem anderen variiert:

• Wenn der Benutzer den Kennungsschlüssel auswählt, führt die Plattformbenutzeroberfläche den Benutzer durch eine (häufig biometrische) Überprüfung des Benutzers.
• Wenn der Benutzer die Benutzerüberprüfung erfolgreich bestanden hat, wird der navigator.credentials.get() Aufruf erfolgreich ausgeführt und gibt eine WebAuthn-Antwort zurück.
• Wenn der Benutzer eine andere Anmeldeinformation als einen Passkey auswählt, wählt der Browser/die Plattform eine andere geeignete Aktion aus (z. B. das automatische Ausfüllen des Benutzernamens), und der navigator.credentials.get() Aufruf wird nicht aufgelöst.
• Wenn der Benutzer die Option "Passkey von einem anderen Gerät" auswählt (der genaue Text variiert geringfügig nach Plattform), führt der Browser/die Plattform den Benutzer durch die Verwendung eines FIDO2-Sicherheitsschlüssels oder des Cross-Device Authentication (CDA)-Flusses, um einen Passkey von ihrem Smartphone oder Tablet zu verwenden, um eine WebAuthn-Antwort an den navigator.credentials.get() Anruf zu übermitteln.
• Senden Sie die WebAuthn-Antwort zur Überprüfung und zusätzliche Sicherheitsprüfungen an Ihren Server. Wenn alle Überprüfungen erfolgreich sind, beginnen Sie eine authentifizierte Sitzung für diesen Benutzer.

Aus diesem Grund wird dies als bedingte Benutzeroberfläche (oder, häufiger, der Benutzeroberflächenmodus für automatisches Ausfüllen) von WebAuthn bezeichnet– die Plattformauthentifikator-UI, die den Benutzer durch die Überprüfung oder durch die Verwendung seines Telefons führt, nur angezeigt, wenn der Benutzer über einen Passkey auf diesem Gerät verfügt (oder die Option "anderes Gerät" auswählt).

Wie Sie sehen können, ist der navigator.credentials.get() Aufruf in diesem Modus entweder erfolgreich oder nicht, weil er nie aufgelöst wird. Wenn dies erfolgreich ist, zeigt das Ergebnis des Aufrufs sowohl eine Benutzer-ID als auch eine signierte WebAuthn-Assertion an, mit der die vertrauende Seite (RP) den Benutzer authentifiziert.

Wenn der Anruf nicht erfolgreich ist, sollten Sie eine ältere Benutzerauthentifizierung durchführen. Sie erhalten einen Benutzernamen von dieser ersten Seite, und auf nachfolgenden Seiten erhalten Sie dann geeignete weitere Anmeldeprobleme (z. B. Kennwörter, Reagieren auf SMS-Herausforderungen usw.) für den Benutzer. Dazu können Schritte zur Kontowiederherstellung gehören, falls der Benutzer sein Kennwort vergessen hat oder die regulären Anmeldeaufforderungen anderweitig nicht bestehen kann. Sobald der Benutzer alle Anmeldeprobleme bestanden hat, gilt er als authentifiziert und angemeldet.

Wenn der Benutzer noch nicht über ein Konto mit der vertrauenden Seite (RP) verfügt, geben Sie dem Benutzer in der Regel die Möglichkeit auf der Anmeldeseite, ein Konto zu erstellen. Wenn der Benutzer diese Option auswäht, sammeln Sie die erforderlichen Informationen von ihm, um ein neues Konto zu öffnen. Wenn sie ein neues Konto erfolgreich öffnen, werden sie auch als authentifiziert und angemeldet betrachtet.

Sobald der Benutzer angemeldet ist, kann es an der Zeit sein, einen neuen Kennungsschlüssel für ihn einzurichten. Führen Sie dies für einen der folgenden Fälle aus:

• Der Benutzer hat sein Konto auf dem Gerät gestartet, indem er Nicht-Passkey-Anmeldeprobleme (z. B. das Verwenden eines Kennworts) übergibt.
• Der Benutzer hat gerade ein neues Konto bei der vertrauenden Seite (RP) erstellt und wird daher als angemeldet betrachtet.
• Der Benutzer hat einen Kennungsschlüssel verwendet, aber er hat ein anderes Gerät als das aktuell verwendete Gerät verwendet (indem er im obigen Beispiel "ein anderes Gerät" auswählt). Dies kann durch Prüfen des AuthenticatorAttachment-Attributs im zurückgegebenen PublicKeyCredential-Objekt bestätigt werden.

1.2: Geräteübergreifende Authentifizierung

Wenn der Benutzer einen Passkey von einem anderen Gerät (z. B. einem Smartphone, Tablet oder FIDO2-Sicherheitsschlüssel) verwendet hat, hat die AuthenticatorAttachment-Eigenschaft in der Authentifizierungsantwort (getAssertion) den Wert cross-platform.

Bieten Sie dem Benutzer in diesem Szenario die Wahl, einen Passkey auf dem lokalen Gerät zu erstellen. Dies führt in Zukunft zu einer nahtloseren Benutzererfahrung, da der Benutzer nicht mehr benötigt wird, um sein anderes Gerät zu verwenden.

1.3: Hinweis zur Benutzerüberprüfung

Diese Anleitung legt userVerification auf preferredfest, was bedeutet, dass die Benutzerüberprüfung nach Möglichkeit versucht wird.

Einige Geräte, z. B. Desktopcomputer und ältere Laptops, verfügen möglicherweise nicht über biometrische Sensoren. Wenn "userVerification" auf diesen Geräten festgelegt requiredist, wird der Benutzer möglicherweise aufgefordert, sein Systemanmeldungskennwort für jede Anmeldung mit einem Kennungsschlüssel einzugeben. Und das kann frustrierend für sie sein.

Bei preferred Verwendung erfordern einige Plattformauthentifikatoren immer eine Überprüfung der Benutzerüberprüfung, wenn das Gerät über biometrische Sensoren verfügt, die Benutzerüberprüfung jedoch auf Geräten ohne diese überspringt.

Das Benutzerüberprüfungsergebnis (übermittelt in Authentifikator-Datenkennzeichnungen) spiegelt das tatsächliche Benutzerüberprüfungsergebnis wider und sollte immer anhand Ihrer Anforderungen auf dem Server überprüft werden.

1.4: Den Benutzer für Passkeys anmelden

Überprüfen Sie zunächst, ob der Benutzer unter Verwendung anderer Anmeldemethoden, einschließlich mehrstufiger Authentifizierung, ausreichend stark authentifiziert ist.

Stellen Sie zweitens sicher, dass die Kombination aus Gerät und Betriebssystem (Betriebssystem) des Benutzers Passkeys unterstützt, indem Sie Folgendes aufrufen:

PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()

Wenn Passkeys unterstützt werden, wird dies zurückgegeben true. Wenn sie nicht unterstützt werden, wird sie zurückgegeben false, und Sie sollten den Passkey-Registrierungsfluss abbrechen.

Stellen Sie dem Benutzer ein Opt-In oder "upsell"-Modal/Interstitial oder eine Seite bereit, die sie zum Erstellen eines Kennungsschlüssels anbietet:

Tipp

Um sicherzustellen, dass der Benutzer die vollständige Zustimmung erteilt, sollten Sie in Erwägung ziehen, längere Beschreibungen anzuzeigen (oder zu verknüpfen), die erklären, dass alle Benutzer, die das aktuelle Gerät entsperren können, auf das Konto bei der vertrauenden Partei (RP) zugreifen können.

Wenn der Benutzer zustimmt, rufen Sie navigator.credentials.create() die im folgenden Beispiel gezeigten Optionen auf:

navigator.credentials.create({
  publicKey: {
    rp: {
      // User-friendly name of your service.
      name: "Passkeys Developer",
      // Relying party (RP) identifier (hostname/FQDN).
      id: passkeys.contoso"
    },

    user: {
      // Persistent, unique identifier for the user account in your backend.
      id: Uint8Array.from("0525bc79-5a63-4e47-b7d1-597e25f5caba", c => c.charCodeAt(0)),
      // User-friendly identifier often displayed to the user (for example, email address).
      name: "amanda@contoso.com",
      // Human-readable display name, sometimes displayed by the client.
      displayName: "Amanda Brady"
    },
    // The challenge is a buffer of cryptographically random bytes generated on your backend,
    // and should be tightly bound to the current user session.
    challenge: Uint8Array.from("XZJscsUqtBH7ZB90t2g0EbZTZYlbSRK6lq7zlN2lJKuoYMnp7Qo2OLzD7xawL3s", c => c.charCodeAt(0)),
    pubKeyCredParams: [
      // An array of objects describing what public key types are acceptable to a server.
      {
        "type": "public-key",
        "alg": -7 // EC P256
      },
      {
        "type": "public-key",
        "alg": -257 // RSA
      }
    ],
    excludeCredentials: [
      // Array of credential IDs for existing passkeys tied to the user account.
      // This avoids creating a new passkey in an authenticator that already has 
      // a passkey tied to the user account.
      {
        // Example only.
        type: "public-key",
        id: new Uint8Array([21, 31, 56, ...]).buffer
      },
      {
        // Example only.
        type: "public-key",
        id: new Uint8Array([21, 31, 56, ...]).buffer
      }
    ],
    authenticatorSelection: {
      // Tells the authenticator to create a passkey.
      residentKey: "required",
      // Tells the client/authenticator to request user verification where possible;
      // for example, a biometric or a device PIN.
      userVerification: "preferred"
    },
    "extensions": {
      // Returns details about the passkey.
      "credProps": true
    }
  }
})

Hinweis

Es wird empfohlen, dass die meisten vertrauenden Parteien (RPs) nicht den Parameter für die Nachweisvermittlung attestation angeben (daher standardmäßig keine), oder verwenden Sie stattdessen explizit den Wert indirect. Dies garantiert die optimierte Benutzererfahrung (Plattformen erhalten wahrscheinlich die Zustimmung des Benutzers für andere Arten von Nachweisvermittlungen, was wahrscheinlich zu einem größeren Bruchteil der erfolglosen Erstellung von Anmeldeinformationen führt, weil Benutzer die Erstellung abbrechen).

Wenn der WebAuthn-Aufruf aufgelöst wird, senden Sie die Antwort an Ihren Server, und ordnen Sie den zurückgegebenen öffentlichen Schlüssel und die Anmeldeinformations-ID dem zuvor authentifizierten Benutzerkonto zu.

Anwendungsfall 2: Erneute Authentifizierung

Die Verwendung von Schlüsseln für eine erneute Authentifizierung kann aus einem der folgenden Gründe erforderlich sein:

• Der Benutzer hat sich abgemeldet und möchte sich jetzt erneut anmelden.
• Die Benutzersitzung ist aufgrund von Inaktivität abgelaufen, und der Benutzer möchte sich erneut anmelden.
• Der Benutzer ist dabei, eine sensible Aktion auszuführen, und muss die Kontrolle über die Benutzersitzung erneut bestätigen.

Um den Benutzer in jedem dieser Situationen erneut zu authentifizieren, verwenden Sie passkeys, die Sie im vorherigen Anwendungsfall eingerichtet haben. Der WebAuthn-API-Aufruf ist in allen drei Fällen identisch, die von Ihnen bereitgestellte UI-Behandlung unterscheidet sich jedoch geringfügig. Da das bestimmte Konto von Ihnen angegeben wird, fordert die Plattform den Benutzer nicht auf, ein anderes Konto in Ihrem Dienst auszuwählen.

2.1: Vertrauliche Aktionen

Sehen wir uns die Benutzeroberfläche zunächst an – wenn es an der Zeit ist, eine vertrauliche Aktion erneut zu authentifizieren, überprüfen Sie, ob Sie über eine Anmeldeinformations-ID für mindestens einen Kennungsschlüssel für den Benutzer verfügen.

Wenn keine solche Anmeldeinformations-ID verfügbar ist, stellen Sie eine herkömmliche Anmeldeabfrage bereit, die für die erneute Authentifizierung geeignet ist, z. B.:

Tipp

Wir empfehlen, dass Benutzer auf dieser Anmeldeabfrageseite ihre Konto-ID nicht ändern können. Außerdem sollte die Anmeldeabfrage etwas sein, das ein nicht autorisierter Benutzer des Geräts nicht bestehen kann.

Wenn Sie andererseits mindestens eine Passkey-Anmeldeinformations-ID für den Benutzer finden, können Sie die Schlüssel für die erneute Authentifizierung verwenden:If, on the other, you do find at least one passkey credential ID for the user, then you can use passkeys for reauthentication:

Wenn der Benutzer bereit ist (im obigen Beispiel, wenn er auf die Schaltfläche "Los" klickt), rufen Sie navigator.credentials.get()auf, und übergeben Sie alle Passkey-Anmeldeinformationen des Benutzers:

navigator.credentials.get({
  publicKey: {
    challenge: ...,
    rpId: ...,
     allowCredentials: [{
      type: "public-key",      
      id: new UInt8Array([21, 31, 56, ...]).buffer,
    }, {
      type: "public-key",
      id: new UInt8Array([21, 31, 56, ...]).buffer,
    }, {
      ...
    }],
    // see note below
    userVerification: "preferred", 
  }
});

Hinweis

Lesen Sie unbedingt die Anleitungen zu userVerification aus dem vorherigen Anwendungsfall.

Wenn der Benutzer stattdessen auf "Try another way" klickt, sollten Sie ihm andere Anmeldemethoden (Kennwort usw.) anbieten, um sie erneut zu authentifizieren (vorausgesetzt, der Benutzer verfügt über solche anderen Anmeldemethoden, die ihnen zur Verfügung stehen).

2.2: Abgelaufene Sitzungen und Abmelden

Nun untersuchen wir den Fall, in dem die erneute Authentifizierung ausgelöst wird, da sich der Benutzer selbst abgemeldet hat oder die vertrauende Seite (RP) die Sitzung des Benutzers abgelaufen ist. Um dies zu erleichtern, müsste das RP eine Form des Sitzungszustands des Benutzers beibehalten, der sie an das Konto erinnert, das zuvor angemeldet war, auch wenn er den Benutzer abgemeldet betrachtet (dies mit Browserartefakten wie Cookies oder lokalem Speicher erreicht werden könnte).

Hinweis

Eine vertrauende Partei (RP) kann sich entscheiden, sich als umfassende Aktion abzumelden und somit alle Verweise auf die Identität des Benutzers zu löschen. Ein solches RP sollte eine nachfolgende Anmeldung wie ein Konto-Bootstrap behandeln und die zuvor erläuterten Schritte wiederholen.

Als RP können Sie dann wie folgt eine Anmeldeseite bereitstellen:

Wenn der Benutzer auf "Ein anderes Konto verwenden" klickt, sollten Sie einen Bootstrap-Fluss für das Konto eingeben, wie im vorherigen Anwendungsfall erläutert, indem Sie die dort beschriebenen Schritte wiederholen, wobei die Plattform dem Benutzer die Auswahl des kontos ermöglicht, das er verwenden möchte.

Hinweis

In diesem Fall sollten Sie dem Benutzer auch die Möglichkeit geben, das vorgeschlagene Konto vollständig aus der Anmeldeseite zu entfernen.

Wenn der Benutzer jedoch auf die Schaltfläche "Anmelden unter" klickt, überprüfen Sie, ob dem Benutzer mindestens eine Passkey-Anmeldeinformations-ID zugeordnet ist. Wenn keine Anmeldeinformations-ID verfügbar ist, stellen Sie eine herkömmliche Anmeldeabfrage bereit, die für die erneute Authentifizierung geeignet ist, z. B.:

Wenn Sie andererseits mindestens eine Passkey-Anmeldeinformations-ID für den Benutzer finden, können Sie die Schlüssel für die erneute Authentifizierung verwenden:If, on the other, you do find at least one passkey credential ID for the user, then you can use passkeys for reauthentication:

Wenn der Benutzer bereit ist (im obigen Beispiel, wenn er auf die Schaltfläche "Gehe zu" klickt), rufen Sie navigator.credentials.get()genau wie bereits gezeigt auf (d. h., indem Sie alle Passkey-IDs des Benutzers übergeben).

Wenn der Benutzer stattdessen auf "Try another way" klickt, sollten Sie ihm andere Anmeldemethoden (Kennwort usw.) anbieten, um sie erneut zu authentifizieren (vorausgesetzt, der Benutzer verfügt über solche anderen Anmeldemethoden, die ihnen zur Verfügung stehen).

Nächste Schritte

Weitere Informationen finden Sie unter Tools und Bibliotheken für Passkeys.

Weitere Informationen

• Einführung in Passkeys
• Passkeys.dev
• Erste Schritte auf Ihrer kennwortlosen Reise auf der FIDO Alliance-Website