Şifre Anahtarı Koşullu Oluşturma (Giriş Sonrası Tanıtım)

Web özellikleri: Web kimlik doğrulaması Web kimlik doğrulama sinyali yöntemleri

Bu kılavuzda, başarılı bir şifre tabanlı oturum açma işleminden hemen sonra bir kullanıcı için geçiş anahtarının otomatik ve sessiz bir şekilde nasıl kaydedileceği, zorlukların nasıl en aza indirileceği ve geçiş anahtarı kullanımının nasıl artırılacağı ayrıntılı olarak açıklanmaktadır.

Doğru Tetikleyici Anı

Otomatik geçiş anahtarı oluşturma (koşullu oluşturma veya sessiz giriş sonrası tanıtım olarak da bilinir) YALNIZCA şifre içeren başarılı ve tam bir oturum açma işleminden hemen sonra tetiklenmelidir.

  • Şifresiz akışlar (ör. sihirli bağlantılar, SMS OTP veya kimlik federasyonu) için koşullu oluşturma girişiminde bulunmayın.
  • Çok öğeli kimlik doğrulaması gerekiyorsa koşullu oluşturma işlemini başlatmadan önce tüm öğelerin başarılı olmasını beklemeniz GEREKİR.
  • Oluşturma uç noktalarına istek göndermeden önce geçerli ve kimliği doğrulanmış bir kullanıcı oturumunun etkin olduğundan emin olun.

Uygulama Adımları

1. Önceki Otomatik Doldurma İşlemlerini İptal Etme

Oturum açma sayfasında form otomatik doldurma (koşullu kullanıcı arayüzü/get) kullanılıyorsa tarayıcı çakışmalarını önlemek için etkin kimlik bilgisi alma çağrısı iptal edilmelidir.

  • navigator.credentials.create() yöntemini çağırmadan önce, bekleyen navigator.credentials.get() otomatik doldurma isteğine ekli AbortController üzerinde abortController.abort() yöntemini çağırın.

2. Özellik Algılama

PublicKeyCredential.getClientCapabilities() ile conditionalCreate öğesini kontrol ederek koşullu oluşturma özelliğinin kullanılıp kullanılamayacağını belirleyin.

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

3. Koşullu oluşturma ile geçiş anahtarı oluşturma

  • navigator.credentials.create() seçenekleri içinde mediation: 'conditional' değerini iletin. Bu, tarayıcıya geçiş anahtarı oluşturma akışını arka planda sessizce veya bağlamsal olarak, rahatsız edici kalıcı iletişim kutuları göstermeden işlemesini bildirir.
  • Yinelenen anahtarların kaydedilmesini önlemek için excludeCredentials alanını kullanıcının mevcut geçiş anahtarı kimlik bilgileriyle doldurun.

4. Sessiz Hata İşleme

  • Geçiş anahtarı oluşturma istemini (navigator.credentials.create) bir try/catch bloğuna sarmalayın. Kullanıcıya herhangi bir hata kullanıcı arayüzü göstermeden, kullanıcılara yönelik tipik istisnaları (InvalidStateError, NotAllowedError, AbortError) yakalamanız ve sessizce yok saymanız GEREKİR.

5. Sunucu Tarafı Kullanıcı Varlığı Doğrulaması

  • Sunucu tarafı doğrulama uç noktası, YALNIZCA koşullu oluşturma tetikleyicisi tarafından üretilen kimlik bilgilerini doğrularken Kullanıcı Varlığı (UP) şartını (requireUserPresence: false) esnetmelidir. Standart müstehcen içerik üretimi için katı varlık doğrulama etkin kalmalıdır.

6. Başarısız sunucu doğrulamasını düzgün bir şekilde işleme

  • navigator.credentials.create() başarılı olur ancak sunucu doğrulama getirme işlemi hatalı bir yanıt döndürürse (ör. imza doğrulama başarısız olursa) artık kimlik bilgilerinin geçiş anahtarı sağlayıcısında kalmasını önlemek için PublicKeyCredential.signalUnknownCredential() yöntemini çağırın.

Kod Örneği

// 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
      });
    }
  }
}

Yedek Stratejiler

Geçiş anahtarı özelliği algılama yedeği

"webauthn-polyfills"i her zaman yükleyin ve bağlama aktarın. PublicKeyCredential desteklendiği sürece PublicKeyCredential.getClientCapabilities de desteklenir. 

import 'webauthn-polyfills';

Signal API Senkronizasyonu Yedeklemesi

WebAuthn Signal API (webauthn-signals), şifre yöneticilerini sunucu kimlik bilgisi durumuyla senkronize tutmak için kullanılan aşamalı bir optimizasyondur.

  • Yedek Deneyim: if (PublicKeyCredential.signalUnknownCredential) üzerinden erişim kısıtlaması uygulanır. Desteklenmiyorsa arka plan doğrulama senkronizasyonu, tarayıcı istisnaları oluşturmadan sorunsuz bir şekilde atlanır.

Kolay JSON Serileştirme Yedeklemesi

"webauthn-polyfills"i her zaman yükleyin ve bağlama aktarın. PublicKeyCredential desteklendiği sürece PublicKeyCredential.parseCreationOptionsFromJSON ve PublicKeyCredential.prototype.toJSON de desteklenir. 

import 'webauthn-polyfills';