Şifresiz girişler için şifre anahtarı oluşturun

Geçiş anahtarları, kullanıcı hesaplarının daha güvenli, basit ve kullanımı kolay olmasını sağlar.

Eiji Kitamura

Şifreler yerine geçiş anahtarlarını kullanmak, web sitelerinin kullanıcı hesaplarını daha güvenli, basit, kullanımı kolay ve şifresiz hale getirmesi için harika bir yoldur. Geçiş anahtarı sayesinde kullanıcılar parmak izi, yüz veya cihaz PIN'ini kullanarak bir web sitesinde veya uygulamada oturum açabilir.

Geçiş anahtarı oluşturulması, kullanıcı hesabıyla ilişkilendirilmiş olması ve kullanıcının oturum açmadan önce ortak anahtarının sunucunuzda saklanması gerekir.

İşleyiş şekli

Aşağıdaki durumlarda kullanıcıdan geçiş anahtarı oluşturması istenebilir:

  • Kullanıcı bir şifre kullanarak oturum açtığında.
  • Kullanıcı başka bir cihazdan geçiş anahtarı kullanarak oturum açtığında (authenticatorAttachment, cross-platform olur).
  • Kullanıcıların geçiş anahtarlarını yönetebileceği özel bir sayfada

Geçiş anahtarı oluşturmak için WebAuthn API'yi kullanın.

Geçiş anahtarı kayıt akışının dört bileşeni şunlardır:

  • Arka uç: Ortak anahtarı ve geçiş anahtarıyla ilgili diğer meta verileri depolayan hesap veritabanını barındıran arka uç sunucunuz.
  • Ön uç: Tarayıcıyla iletişim kuran ve getirme isteklerini arka uca gönderen ön ucunuz.
  • Tarayıcı: Kullanıcının JavaScript'inizi çalıştıran tarayıcısı.
  • Authenticator: Geçiş anahtarını oluşturup saklayan kullanıcının kimlik doğrulayıcısı. Bu işlem, tarayıcıyla aynı cihazda (örneğin, Windows Hello'yu kullanırken) veya telefon gibi başka bir cihazda olabilir.
Geçiş anahtarı kayıt şeması

Mevcut bir kullanıcı hesabına yeni geçiş anahtarı ekleme yolculuğu aşağıdaki gibidir:

  1. Kullanıcı, web sitesinde oturum açar.
  2. Kullanıcı oturum açtıktan sonra ön uçta geçiş anahtarı oluşturmak ister. Örneğin, "Geçiş anahtarı oluştur" düğmesine basarak.
  3. Ön uç; geçiş anahtarı oluşturmak için arka uçtan kullanıcı bilgileri, giriş sorgulaması ve hariç tutulacak kimlik bilgisi kimlikleri gibi bilgileri ister.
  4. Ön uç, geçiş anahtarı oluşturmak için navigator.credentials.create() işlevini çağırır. Bu çağrı bir söz döndürür.
  5. Kullanıcı cihazın ekran kilidini kullanarak izin verdikten sonra geçiş anahtarı oluşturulur. Vaat çözümlenir ve ön uca bir ortak anahtar kimlik bilgisi döndürülür.
  6. Ön uç, ortak anahtar kimlik bilgisini arka uca gönderir ve gelecekteki kimlik doğrulama işlemleri için kullanıcı hesabıyla ilişkili kimlik bilgisi kimliğini ve ortak anahtarı depolar.

Uyumluluk

WebAuthn çoğu tarayıcı tarafından desteklenir, ancak küçük boşluklar vardır. Hangi tarayıcı ve işletim sistemi kombinasyonunun geçiş anahtarı oluşturmayı desteklediğini öğrenmek için Cihaz Desteği - geçişs.dev bölümüne bakın.

Yeni geçiş anahtarı oluşturun

Aşağıda bir ön ucun yeni geçiş anahtarı oluşturma isteği üzerine nasıl çalışması gerektiği açıklanmıştır.

Özellik algılama

"Yeni bir geçiş anahtarı oluşturun" düğmesi göstermeden önce şunları kontrol edin:

  • Tarayıcı WebAuthn'u destekliyor.
  • Cihaz, bir platform kimlik doğrulayıcıyı destekler (geçiş anahtarı oluşturabilir ve geçiş anahtarıyla kimlik doğrulayabilir).
  • Tarayıcı WebAuthn koşullu kullanıcı arayüzünü destekler.
// Availability of `window.PublicKeyCredential` means WebAuthn is usable.  
// `isUserVerifyingPlatformAuthenticatorAvailable` means the feature detection is usable.  
// `​​isConditionalMediationAvailable` means the feature detection is usable.  
if (window.PublicKeyCredential &&  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable &&  
    PublicKeyCredential.​​isConditionalMediationAvailable) {  
  // Check if user verifying platform authenticator is available.  
  Promise.all([  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),  
    PublicKeyCredential.​​isConditionalMediationAvailable(),  
  ]).then(results => {  
    if (results.every(r => r === true)) {  
      // Display "Create a new passkey" button  
    }  
  });  
}

Tüm koşullar karşılanana kadar geçiş anahtarları bu tarayıcıda desteklenmez. O zamana kadar "Yeni geçiş anahtarı oluştur" düğmesi görüntülenmemelidir.

Arka uçtan önemli bilgileri getirme

Kullanıcı düğmeyi tıkladığında navigator.credentials.create() numaralı telefonu aramak için önemli bilgileri arka uçtan getirin:

  • challenge: Bu kayıt için ArrayBuffer'da sunucu tarafından oluşturulan bir sorgulama. Bu kısım gereklidir ancak onay verilmediği sürece kayıt sırasında kullanılmaz. Bu konuda ileri düzeyde bir konu ele alınmamıştır.
  • user.id: Kullanıcının benzersiz kimliği. Bu değer, e-posta adresleri veya kullanıcı adları gibi kişisel verileri ifşa edici bilgiler içermeyen bir ArrayBuffer olmalıdır. Hesap başına oluşturulan rastgele 16 baytlık bir değer işe yarayacaktır.
  • user.name: Bu alanda, kullanıcının tanıyacağı hesap için benzersiz bir tanımlayıcı (e-posta adresi veya kullanıcı adı gibi) bulunmalıdır. Bu bilgi, hesap seçicide gösterilir. (Kullanıcı adı kullanıyorsanız şifre doğrulamasındakiyle aynı değeri kullanın.)
  • user.displayName: Bu alan, hesap için zorunlu ve daha kullanıcı dostu bir addır. Benzersiz olması gerekmez ve kullanıcının seçtiği ad olabilir. Siteniz buraya dahil edilecek uygun bir değere sahip değilse boş bir dize iletin. Tarayıcıya bağlı olarak, hesap seçicide bu gösterilebilir.
  • excludeCredentials: Halihazırda kayıtlı kimlik bilgisi kimliklerinin listesini sağlayarak aynı cihazın kaydedilmesini engeller. transports üyesi (sağlanmışsa), her kimlik bilgisinin kaydı sırasında getTransports() çağrısının sonucunu içermelidir.

Geçiş anahtarı oluşturmak için WebAuthn API'yi çağırın

Yeni bir geçiş anahtarı oluşturmak için navigator.credentials.create() numaralı telefonu arayın. API, kullanıcının etkileşiminin kalıcı bir iletişim kutusu görüntülemesini bekleyerek bir söz verir.

const publicKeyCredentialCreationOptions = {
  challenge: *****,
  rp: {
    name: "Example",
    id: "example.com",
  },
  user: {
    id: *****,
    name: "john78",
    displayName: "John",
  },
  pubKeyCredParams: [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}],
  excludeCredentials: [{
    id: *****,
    type: 'public-key',
    transports: ['internal'],
  }],
  authenticatorSelection: {
    authenticatorAttachment: "platform",
    requireResidentKey: true,
  }
};

const credential = await navigator.credentials.create({
  publicKey: publicKeyCredentialCreationOptions
});

// Encode and send the credential to the server for verification.

Yukarıda açıklanmayan parametreler şunlardır:

  • rp.id: RP kimliği bir alandır. Web sitesi, kendi alanını veya kaydedilebilir bir son eki belirtebilir. Örneğin, RP'nin kaynağı https://login.example.com:1337 ise RP kimliği login.example.com veya example.com olabilir. RP kimliği example.com olarak belirtilirse kullanıcı login.example.com üzerinde veya example.com üzerindeki herhangi bir alt alanda kimlik doğrulaması yapabilir.

  • rp.name: RP'nin adı.

  • pubKeyCredParams: Bu alan, RP'nin desteklediği ortak anahtar algoritmalarını belirtir. Bunu [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}] olarak ayarlamanızı öneririz. Bu, P-256 ve RSA PKCS#1 ile ECDSA desteğini belirtir ve bunların desteklenmesi, tam kapsamlı bir kapsam sağlar.

  • authenticatorSelection.authenticatorAttachment: Bu geçiş anahtarı oluşturma işlemi, bir şifreden yükseltmeyse (ör. oturum açma işleminden sonra promosyonda) bunu "platform" olarak ayarlayın. "platform", RP'nin bir platform kimlik doğrulayıcısı (platform cihazına yerleştirilmiş bir kimlik doğrulayıcı) istediğini belirtir. Bu kimlik doğrulayıcı, örneğin USB güvenlik anahtarı yerleştirilmesini istemeyecektir. Kullanıcıya geçiş anahtarı oluşturmak için daha basit bir seçenek sunulur.

  • authenticatorSelection.requireResidentKey: boole'yi "true" olarak ayarlayın. Bulunabilir kimlik bilgisi (yerleşik anahtar), kullanıcı bilgilerini geçiş anahtarında depolar ve kullanıcıların kimlik doğrulamasından sonra hesabı seçmesine olanak tanır.

  • authenticatorSelection.userVerification: Cihaz ekran kilidini kullanarak yapılan kullanıcı doğrulama işleminin "required", "preferred" veya "discouraged" olduğunu belirtir. Varsayılan değer "preferred" şeklindedir. Bu, kimlik doğrulayıcının kullanıcı doğrulamasını atlayabileceği anlamına gelir. Bunu "preferred" olarak ayarlayın veya özelliği atlayın.

Döndürülen ortak anahtar kimlik bilgilerini arka uca gönder

Kullanıcı, cihazın ekran kilidini kullanarak izin verdikten sonra bir geçiş anahtarı oluşturulur ve ön uca bir PublicKeyCredential nesnesi döndürme sözü çözümlenir.

Vaat farklı nedenlerle reddedilebilir. Error nesnesinin name özelliğini kontrol ederek bu hataları giderebilirsiniz:

  • InvalidStateError: Cihazda bir geçiş anahtarı zaten mevcut. Kullanıcıya hata iletişim kutusu gösterilmez ve sitenin bunu bir hata olarak değerlendirmemesi gerekir. Kullanıcı, yerel cihazın kaydedilmesini istemiştir ve kayıtlıdır.
  • NotAllowedError: Kullanıcı, işlemi iptal etti.
  • Diğer istisnalar: Beklenmedik bir şey oldu. Tarayıcı, kullanıcıya bir hata iletişim kutusu gösterir.

Ortak anahtar kimlik bilgisi nesnesi aşağıdaki özellikleri içerir:

  • id: Oluşturulan geçiş anahtarının Base64URL kodlamalı kimliği. Bu kimlik, tarayıcının kimlik doğrulama sonrasında cihazda eşleşen bir geçiş anahtarı olup olmadığını belirlemesine yardımcı olur. Bu değerin arka uçtaki veritabanında depolanması gerekir.
  • rawId: Kimlik bilgisi kimliğinin bir ArrayBuffer sürümü.
  • response.clientDataJSON: ArrayBuffer kodlamalı istemci verileri.
  • response.attestationObject: ArrayBuffer kodlamalı onay nesnesi. Bu dosya RP kimliği, işaretler ve ortak anahtar gibi önemli bilgiler içerir.
  • authenticatorAttachment: Bu kimlik bilgisi, geçiş anahtarı özellikli bir cihazda oluşturulduğunda "platform" değerini döndürür.
  • type: Bu alan her zaman "public-key" olarak ayarlanır.

Arka uçtaki ortak anahtar kimlik bilgisi nesnesini işlemek için bir kitaplık kullanıyorsanız nesneyi base64url ile kısmen kodladıktan sonra nesnenin tamamını arka uca göndermenizi öneririz.

Kimlik bilgisini kaydet

Arka uçta ortak anahtar kimlik bilgisini aldıktan sonra, nesneyi işlemek için FIDO kitaplığına geçirin.

Daha sonra, kimlik bilgisinden alınan bilgileri gelecekte kullanmak için veritabanında saklayabilirsiniz. Aşağıdaki listede kaydedilebilecek bazı tipik özellikler bulunmaktadır:

  • Kimlik bilgisi kimliği (Birincil anahtar)
  • Kullanıcı kimliği
  • Ortak anahtar

Ortak anahtar kimlik bilgisi, veritabanına kaydetmek isteyebileceğiniz aşağıdaki bilgileri de içerir:

Kullanıcının kimliğini doğrulamak için Form otomatik doldurma özelliğini kullanarak geçiş anahtarıyla oturum açma başlıklı makaleyi okuyun.

Kaynaklar