Voorwaardelijk maken van toegangssleutel (promotie na inloggen)

In deze handleiding wordt uitgelegd hoe je automatisch en op de achtergrond een toegangssleutel voor een gebruiker registreert onmiddellijk nadat deze is ingelogd met een wachtwoord. Zo minimaliseer je de frictie en stimuleer je de acceptatie van toegangssleutels.

Het juiste triggermoment

Automatisch een toegangssleutel maken (ook wel voorwaardelijk maken of stille promotie na inloggen genoemd) MAG alleen onmiddellijk na een geslaagde, volledige inlogpoging met een wachtwoord worden geactiveerd.

• Probeer geen voorwaardelijke accounts te maken voor wachtwoordloze processen (zoals magic links, sms-OTP of identiteitsfederatie).
• Als multifactorauthenticatie is vereist, MOET u wachten tot alle factoren zijn geslaagd voordat u voorwaardelijk maken start.
• Zorg dat er een geldige, geverifieerde gebruikerssessie actief is voordat je verzoeken indient bij eindpunten voor maken.

Stapsgewijze implementatie

1. Eerdere acties voor automatisch invullen afbreken

Als de inlogpagina gebruikmaakt van automatisch invullen van formulieren (voorwaardelijke UI/Get), moet de actieve aanroep voor het ophalen van inloggegevens worden afgebroken om browserconflicten te voorkomen.

• Roep abortController.abort() aan op de AbortController die is gekoppeld aan het openstaande verzoek voor automatisch invullen van navigator.credentials.get() voordat je navigator.credentials.create() aanroept.

2. Functiedetectie

Bepaal of Voorwaardelijk maken beschikbaar is door conditionalCreate te controleren met PublicKeyCredential.getClientCapabilities().

const capabilities = await PublicKeyCredential.getClientCapabilities();
if (capabilities.conditionalCreate) {
  // Conditional create is available
}

3. Een toegangssleutel maken met Voorwaardelijk maken

• Geef mediation: 'conditional' door in de opties voor navigator.credentials.create(). Dit geeft de browser een signaal om het proces voor het maken van de toegangssleutel op de achtergrond of contextueel af te handelen zonder opdringerige modale dialoogvensters te tonen.
• Vul excludeCredentials in met de bestaande inloggegevens-ID's van de toegangssleutel van de gebruiker om te voorkomen dat dubbele sleutels worden geregistreerd.

4. Stille foutafhandeling

• Plaats de prompt voor het maken van een toegangssleutel (navigator.credentials.create) in een try/catch-blok. U MOET typische uitzonderingen voor gebruikers (InvalidStateError, NotAllowedError, AbortError) opvangen en negeren zonder een fout-UI aan de gebruiker te tonen.

5. Verificatie van gebruikersaanwezigheid aan de serverzijde

• Het eindpunt voor verificatie aan de serverzijde MOET de vereiste voor gebruikersaanwezigheid (UP) (requireUserPresence: false) ALLEEN versoepelen als inloggegevens worden geverifieerd die zijn geproduceerd door een trigger voor voorwaardelijk maken. Strenge aanwezigheidsverificatie moet actief blijven voor standaard expliciete creaties.

6. Ga op een goede manier om met mislukte serververificatie

• Als navigator.credentials.create() slaagt, maar de serververificatie een slechte reactie retourneert (bijvoorbeeld als de handtekeningverificatie mislukt), roep je PublicKeyCredential.signalUnknownCredential() aan om te voorkomen dat verweesde inloggegevens in de toegangssleutelprovider blijven hangen.

Codevoorbeeld

// optionsFetch and registerVerifyFetch are app-defined server endpoint requests
import { optionsFetch, registerVerifyFetch } from './api.js';

async function triggerConditionalCreate(loginAbortController) {
  const capabilities = await PublicKeyCredential.getClientCapabilities();
  if (capabilities.conditionalCreate !== true) {
    return; // Platform does not support conditional creation
  }

  // 1. Abort any active autofill conditional-get controllers to clear the WebAuthn pipeline
  loginAbortController.abort();

  // 2. Fetch creation options signaling the backend that this is a conditional request
  const creationOptionsJSON = await optionsFetch({ conditional: true });
  const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(creationOptionsJSON);

  let credential;
  try {
    // 3. Invoke silent credentials creation prompt
    credential = await navigator.credentials.create({ 
      publicKey,
      mediation: 'conditional' // Silent background creation mediation
    });
  } catch (e) {
    // 4. Silently swallow common WebAuthn browser exceptions
    if (['InvalidStateError', 'NotAllowedError', 'AbortError'].includes(e.name)) {
      return; 
    }
    console.error('Unexpected conditional create error:', e);
    return;
  }

  // 5. Server verification step using dedicated Try/Catch block
  let encodedResponse = credential.toJSON();
  try {
    const response = await registerVerifyFetch(encodedResponse);
    if (!response.ok) {
      // If the server verification fails, clean up using Signal API
      if (PublicKeyCredential.signalUnknownCredential) {
        await PublicKeyCredential.signalUnknownCredential({
          rpId, // RP ID must match the one defined on the server
          credentialId: encodedResponse.id
        });
      }
    }
  } catch (serverErr) {
    console.error('Verification network failure:', serverErr);
    if (PublicKeyCredential.signalUnknownCredential) {
      await PublicKeyCredential.signalUnknownCredential({
        rpId, // RP ID must match the one defined on the server
        credentialId: encodedResponse.id
      });
    }
  }
}

Reservestrategieën

Terugvaloptie voor detectie van toegangssleutelfunctie

Installeer altijd 'webauthn-polyfills' en importeer dit in de context. Zolang PublicKeyCredential wordt ondersteund, wordt PublicKeyCredential.getClientCapabilities ook ondersteund.

import 'webauthn-polyfills';

Terugvaloptie voor synchronisatie van Signal API

De WebAuthn Signal API (webauthn-signals) is een progressieve optimalisatie die wordt gebruikt om wachtwoordmanagers gesynchroniseerd te houden met de status van de servergegevens.

• Fallback Experience: Gated via if (PublicKeyCredential.signalUnknownCredential). Als dit niet wordt ondersteund, wordt de synchronisatie van de achtergrondverificatie overgeslagen zonder browseruitzonderingen te genereren.

Easy JSON Serialization Fallback

Installeer altijd 'webauthn-polyfills' en importeer dit in de context. Zolang PublicKeyCredential wordt ondersteund, worden PublicKeyCredential.parseCreationOptionsFromJSON en PublicKeyCredential.prototype.toJSON ook ondersteund.

import 'webauthn-polyfills';