Geçiş anahtarları için kullanım senaryoları

Bu konuda geçiş anahtarları için bazı kullanım örnekleri açıklanmaktadır.

Kullanım örneği 1: Önyükleme

Web'de bir hesabı önyükleme.

1.1: Kullanıcının kimliğini doğrulama

Bu bölüm, bağlı olan taraf (RP) istemci cihazını kimin denetlediği konusunda henüz bilgi sahibi olmadığında geçerlidir. RP için kullanılabilir bir tarayıcı yapıtı (yerel depolamadaki tanımlama bilgisi veya kimlik bilgisi kimliği gibi) yoktur, ancak şimdilik kullanıcının RP ile mevcut bir hesabına sahip olduğunu varsayıyoruz.

Hesabı önyüklemek için kullanıcıya bir oturum açma sayfası verin.

Kullanıcıdan hesap tanımlayıcısını isteyerek başlayın; genellikle bir kullanıcı adı veya e-posta adresidir.

Oturum Aç

Geçiş anahtarları için kullanıcı arabirimini otomatik doldurmayı desteklemek için şunları yaptığınızdan emin olun:

username ve webauthn değerini, kullanıcı adı giriş alanındaki mevcut otomatik tamamlama açıklamalarına ekleyin.

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

Sayfa yüklemede, otomatik doldurma kullanıcı arabiriminin (koşullu arayüz kontrolü) kullanılabilir olup olmadığını denetlemek için bir if ifadesi kullanın, ardından navigator.credentials.get() ve mediation: "conditional" ile userVerification: "preferred" işlevini çağırın.

  <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>

Yukarıdakiler aşağıdakilerin gerçekleşmesine neden olur:

Sunucunuzdan kimlik doğrulama seçeneklerini alın. Bu kimlik doğrulama isteğiyle ilişkilendirilecek en azından rastgele bir challenge ve rpId döndür.
Kullanıcı kullanıcı adı alanınızla etkileşime geçtiğinde, tarayıcı ve platform bağlı olan tarafla birlikte kullanılabilecek bir geçiş anahtarının (platform kimlik doğrulayıcısında) mevcut olup olmadığını denetler.
Böyle bir durumda, geçiş anahtarı kullanıcıya seçme seçeneği olarak sunulur (tarayıcının parola yöneticisinde depolanan kullanıcı adları gibi otomatik olarak doldurulabilen diğer kimlik bilgileriyle birlikte). Tarayıcı/platform, aşağıda gösterilen kullanıcı arabirimine benzer bir görünüm oluşturabilir. Ancak, tam görünüm ve his bir platform veya form faktöründen diğerine farklılık gösterir:

Geçiş anahtarıyla oturum açma

Kullanıcı geçiş anahtarını seçerse platform kullanıcı arabirimi kullanıcıya (genellikle biyometrik tabanlı) bir kullanıcı doğrulama denetiminde yol gösterir.
Kullanıcı kullanıcı doğrulamasını başarıyla geçerse, navigator.credentials.get() çağrı başarılı olur ve bir WebAuthn yanıtı döndürür.
Kullanıcı geçiş anahtarı dışında bir kimlik bilgisi seçerse tarayıcı/platform farklı bir uygun eylem seçer (kullanıcı adını otomatik olarak doldurma gibi) ve navigator.credentials.get() çağrı çözümlenemez.
Kullanıcı "Başka bir cihazdan geçiş anahtarı" seçeneğini seçerse (tam metin platforma göre biraz değişiklik gösterir), tarayıcı/platform kullanıcıya bir FIDO2 güvenlik anahtarı veya Cihazlar Arası Kimlik Doğrulaması (CDA) akışını kullanarak akıllı telefonundan veya tabletinden çağrıya WebAuthn yanıtı navigator.credentials.get() sağlamak için bir geçiş anahtarı kullanma konusunda yol gösterir.
Doğrulama ve ek güvenlik denetimleri için WebAuthn yanıtını sunucunuza gönderin. Tüm denetimler başarılı olursa, bu kullanıcı için kimliği doğrulanmış bir oturum başlatın.

Bu nedenle, webauthn'un koşullu kullanıcı arabirimi (veya daha yaygın olarak otomatik doldurma kullanıcı arabirimi) modu olarak adlandırılır. Bu, doğrulama sırasında veya telefonunu kullanarak kullanıcıya yol gösteren platform kimlik doğrulayıcı kullanıcı arabirimi, yalnızca kullanıcının bu cihazda bir geçiş anahtarı varsa (veya "başka bir cihaz" seçeneğini seçerse) gösterilir.

Gördüğünüz gibi, bu modda navigator.credentials.get() çağrı başarılı olur veya hiçbir zaman çözümlenemediği için başarısız olur. Başarılı olursa, çağrının sonucu hem kullanıcı kimliğini hem de bağlı olan tarafın (RP) kullanıcının kimliğini doğrulamak için kullanacağı imzalı bir WebAuthn onayını gösterir.

Çağrı başarılı olmazsa eski bir kullanıcı kimlik doğrulaması gerçekleştirmeniz gerekir. Bu ilk sayfadan bir kullanıcı adı edineceksiniz ve sonraki sayfalarda kullanıcıya uygun diğer oturum açma zorluklarına (parolalar, SMS sınamalarına yanıt verme vb.) hizmet veriyorsunuz. Bunlar, kullanıcının parolasını unutması veya normal oturum açma sınamalarını geçememesi durumunda hesap kurtarma adımlarını içerebilir. Kullanıcı tüm oturum açma sınamalarını geçtikten sonra kimliği doğrulanmış ve oturum açmış olarak kabul edilir.

Kullanıcının bağlı olan tarafa (RP) sahip bir hesabı yoksa, genellikle kullanıcıya oturum açma sayfasında hesap oluşturma seçeneğini verirsiniz. Kullanıcı bu seçeneği belirlerse, yeni bir hesap açmak için onlardan gerekli bilgileri toplarsınız. Yeni bir hesabı başarıyla açarlarsa, kimliği doğrulanmış ve oturum açmış olarak da kabul edilirler.

Kullanıcı oturum açtıktan sonra, bu kullanıcı için yeni bir geçiş anahtarı ayarlamanın zamanı geldi olabilir. Aşağıdaki durumlardan herhangi biri için bunu yapın:

Kullanıcı, parola kullanma gibi geçiş anahtarı gerektirmeyen oturum açma sınamalarını geçerek cihazda hesabını kurdu.
Kullanıcı, güvenilen tarafta (RP) yeni bir hesap oluşturdu ve bu yüzden oturum açmış sayılır.
Kullanıcı bir geçiş anahtarı kullanıyordu, ancak şu anda kullanmakta olduğu cihazdan farklı bir cihaz kullandı (yukarıdaki örnekte gösterilen "başka bir cihaz" öğesini seçerek). Bu, döndürülen PublicKeyCredential nesnesindeki authenticatorAttachment özniteliği incelenerek doğrulanabilir.

1.2: Cihazlar arası kimlik doğrulaması

Kullanıcı başka bir cihazdan (telefon, tablet veya FIDO2 güvenlik anahtarı gibi) bir geçiş anahtarı kullandıysa, kimlik doğrulama yanıtında (getAssertion) authenticatorAttachment özelliği değerine cross-platformsahip olur.

Bu senaryoda, kullanıcıya yerel cihazında bir geçiş anahtarı oluşturma seçeneği sunun. Bu, gelecekte kullanıcının diğer cihazını kullanması gerekmeyeceği için daha sorunsuz bir kullanıcı deneyimine neden olur.

Bu cihazda bir geçiş anahtarı ayarlayın!

1.3: Kullanıcı doğrulaması hakkında bir not

Bu kılavuz userVerification değerini olarak preferredayarlar. Bu, mümkün olduğunda kullanıcı doğrulamasının deneneceği anlamına gelir.

Masaüstü bilgisayarlar ve eski dizüstü bilgisayarlar gibi bazı cihazlarda biyometrik algılayıcılar olmayabilir. Bu cihazlarda userVerification olarak ayarlanırsa required, kullanıcıdan bir geçiş anahtarı kullanarak her oturum açma işlemi için sistem oturum açma parolasını girmesi istenebilir. Ve bu onlar için sinir bozucu olabilir.

preferred Kullanıldığında, bazı platform kimlik doğrulayıcıları cihazda biyometrik algılayıcılar olduğunda her zaman kullanıcı doğrulama denetimi gerektirir, ancak bunlar olmadan cihazlarda kullanıcı doğrulamayı atlayabilir.

Kullanıcı doğrulama sonucu (kimlik doğrulayıcı veri bayraklarıyla iletilir) gerçek kullanıcı doğrulama sonucunu yansıtır ve her zaman sunucudaki gereksinimlerinize göre doğrulanmalıdır.

1.4: Kullanıcıyı geçiş anahtarlarına dahil etme

İlk olarak, çok faktörlü kimlik doğrulaması dahil olmak üzere diğer oturum açma yöntemleri kullanılarak kullanıcının kimliğinin yeterince güçlü bir şekilde doğrulandığını doğrulayın.

İkinci olarak, kullanıcının cihazının ve işletim sisteminin (OS) birleşiminin şu çağrıları yaparak geçiş tuşlarını desteklediğinden emin olun:

PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()

Geçiş anahtarları destekleniyorsa, true değerini döndürür. Bunlar desteklenmiyorsa, false döndürülecek ve siz geçiş anahtarı kayıt sürecini durdurmalısınız.

Anahtar oluşturmak için kullanıcılara isteğe bağlı veya satış artırma modal/ara ekran veya sayfa sunma.

Geçiş tuşlarıyla daha hızlı ve daha güvenli oturum açma!

Tavsiye

Kullanıcının tam olarak bilgilendirilmiş onay vermesini sağlamak için, geçerli cihazın kilidini açabilen tüm kullanıcıların bağlı olan taraf (RP) üzerinden hesaba erişebileceklerini açıklayan daha uzun açıklamalar göstermeyi (veya bağlantı oluşturmayı) göz önünde bulundurun.

Kullanıcı onay verirse, aşağıdaki örnekte gösterilen seçeneklerle çağrısı navigator.credentials.create() yapın:

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

Uyarı

Çoğu bağlı olan tarafın (RP) kanıtlama iletme parametresini attestation belirtmemesi (dolayısıyla varsayılan olarak 'yok' kalır) veya bunun yerine açıkça indirect değerini kullanması tavsiye edilir. Bu, en kolay kullanıcı deneyimini garanti eder (platformlar büyük olasılıkla diğer kanıtlama aktarım türleri için kullanıcıdan onay alabilir ve bu da kullanıcıların oluşturma işlemini iptal etmesinden dolayı başarısız kimlik bilgileri oluşturma işleminin daha büyük bir bölümüne neden olur).

WebAuthn çağrısı çözümlendiğinde, yanıtı sunucunuza gönderin ve döndürülen ortak anahtarı ve kimlik bilgisi kimliğini daha önce kimliği doğrulanmış kullanıcı hesabıyla ilişkilendirin.

Kullanım örneği 2: Yeniden kimlik doğrulaması

Yeniden kimlik doğrulaması için geçiş anahtarları kullanmak aşağıdaki nedenlerden herhangi biri için gerekli olabilir:

Kullanıcı oturum kapattı ve şimdi tekrar oturum açmak istiyor.
Etkinlik dışı kalma nedeniyle kullanıcı oturumunun süresi doldu ve kullanıcı yeniden oturum açmak istiyor.
Kullanıcı hassas bir eylem gerçekleştirmek üzere ve kullanıcı oturumu üzerindeki denetimi yeniden onaylaması gerekiyor.

Bu durumların her birinde kullanıcıyı yeniden kimlik doğrulaması yapmak için, önceki kullanım örneğinde ayarladığınız anahtarları kullanacaksınız. WebAuthn API çağrısı üç durumda da aynıdır, ancak sağladığınız kullanıcı arabirimi işlemi biraz farklıdır. Belirli bir hesap sizin tarafınızdan belirtildiğinden platform, kullanıcıdan hizmetinizde farklı bir hesap seçmesini istemez.

2.1: Hassas eylemler

Önce üçüncü nedenden dolayı kullanıcı arabirimine bakalım. Hassas bir eylem için yeniden kimlik doğrulama zamanı geldiğinde, kullanıcı için en az bir geçiş anahtarı için kimlik bilgisi kimliğiniz olup olmadığını kontrol edin.

Böyle bir kimlik bilgisi kimliği yoksa, yeniden kimlik doğrulamasına uygun geleneksel bir oturum açma sınaması yapın, örneğin:

Siz olduğunuzdan emin olalım 1

Tavsiye

Bu oturum açma sınaması sayfasında kullanıcıların hesap tanımlayıcılarını değiştirememelerini öneririz. Ayrıca, oturum açma sınaması, cihazın yetkisiz bir kullanıcısının geçemeyeceği bir şey olmalıdır.

Diğer taraftan, kullanıcı için en az bir geçiş anahtarı kimlik bilgisi bulursanız, yeniden kimlik doğrulaması için geçiş anahtarlarını kullanabilirsiniz.

Şimdi siz olduğunuzdan emin olalım 2

Kullanıcı hazır olduğunda (yukarıdaki örnekte,"Git" düğmesine tıkladığında) çağrısı navigator.credentials.get()yapın ve kullanıcının tüm geçiş anahtarı kimlik bilgilerini geçirin:

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", 
  }
});

Uyarı

Önceki kullanım örneğinden userVerification ile ilgili yönergeleri okuduğunuzdan emin olun.

Kullanıcı bunun yerine "Başka bir yöntem dene" seçeneğine tıklarsa, yeniden kimlik doğrulaması için (kullanıcının kullanabileceği başka oturum açma yöntemleri olduğu varsayılarak) başka oturum açma yöntemleri (parola vb.) sunmanız gerekir.

2.2: Süresi dolan oturumlar ve oturumu kapatma

Şimdi kullanıcı oturumunu kapattığı veya bağlı olan tarafın (RP) kullanıcının oturumunun süresi dolduğu için yeniden kimlik doğrulamanın tetiklendiği durumu inceleyeceğiz. Bunu kolaylaştırmak için RP'nin, kullanıcının oturumunu kapattığı düşünülse bile, daha önce oturum açılmış olan hesabı hatırlatan bir kullanıcı oturumu durumu tutması gerekir. Bu, tarayıcı tarafından sağlanan çerezler veya yerel depolama gibi araçlar kullanılarak elde edilebilir.

Uyarı

Güvenen taraf (RP), oturumu kapatmayı kapsamlı bir işlem olarak değerlendirerek, bu nedenle kullanıcının kimliğine yapılan tüm başvuruları silmeyi seçebilir. Böyle bir RP, sonraki oturum açma işlemlerini hesap önyüklemesi gibi değerlendirmeli ve daha önce açıklanan adımları yinelemelidir.

RP olarak aşağıdaki gibi bir oturum açma sayfası açabilirsiniz:

Tekrar hoş geldiniz! 1

Kullanıcı "Farklı bir hesap kullan" seçeneğine tıklarsa, önceki kullanım örneğinde açıklandığı gibi, platformun kullanıcının kullanmak istediği hesabı seçmesine izin vermesi için buradaki adımları yineleyerek bir hesap önyükleme akışı girmeniz gerekir.

Uyarı

Bu durumda, kullanıcıya önerilen hesabın oturum açma sayfasında listelenmesini tamamen kaldırma olanağı da vermelisiniz.

Ancak kullanıcı "Farklı Oturum Aç" düğmesine tıklarsa, kullanıcıyla ilişkilendirilmiş en az bir geçiş anahtarı kimlik bilgisi ID'si olup olmadığını kontrol edin. Kullanılabilir kimlik bilgisi kimliği yoksa, yeniden kimlik doğrulaması için uygun geleneksel bir oturum açma sınaması yapın, örneğin:

Tekrar hoş geldiniz! 2

Diğer taraftan, kullanıcı için en az bir geçiş anahtarı kimlik bilgisi bulursanız, yeniden kimlik doğrulaması için geçiş anahtarlarını kullanabilirsiniz.

Tekrar hoş geldiniz! 3

Kullanıcı hazır olduğunda (yukarıdaki örnekte"Git" düğmesine tıkladığında), tam olarak gösterildiği gibi (kullanıcının tüm geçiş anahtarı kimlik bilgilerini geçirerek) çağrısı navigator.credentials.get()yapın.

Sonraki Adımlar

Ardından geçiş anahtarları için kullanılan araçlar ve kütüphaneler'e bakınız.

Daha fazla bilgi

Geçiş anahtarlarına giriş
Passkeys.dev
FIDO Alliance web sitesinde Parolasız Yolculuğunuza Başlayın

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-06-10

Aracılığıyla paylaş

Geçiş anahtarları için kullanım senaryoları

Kullanım örneği 1: Önyükleme

1.1: Kullanıcının kimliğini doğrulama

1.2: Cihazlar arası kimlik doğrulaması

1.3: Kullanıcı doğrulaması hakkında bir not

1.4: Kullanıcıyı geçiş anahtarlarına dahil etme

Kullanım örneği 2: Yeniden kimlik doğrulaması

2.1: Hassas eylemler

2.2: Süresi dolan oturumlar ve oturumu kapatma

Sonraki Adımlar

Daha fazla bilgi

Geri Bildirim

Ek kaynaklar