Şifresiz girişler için geçiş anahtarı oluşturma

Geçiş anahtarları, kullanıcı hesaplarını daha güvenli, basit ve kullanımı kolay hale getirir.

Eiji Kitamura

Şifre yerine geçiş anahtarı kullanmak, web sitelerinin kullanıcı hesaplarını daha güvenli, daha basit, kullanımı kolay ve şifresiz hale getirmelerinin mükemmel bir yoludur. Geçiş anahtarı sayesinde kullanıcılar yalnızca parmak izi, yüz veya cihaz PIN'ini kullanarak bir web sitesinde veya uygulamada oturum açabilir.

Kullanıcının oturum açabilmesi için bir kullanıcı hesabıyla ilişkilendirilmiş geçiş anahtarı oluşturulması ve ortak anahtarının sunucunuzda saklanması gerekir.

İşleyiş şekli

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

  • Kullanıcı şifre kullanarak oturum açtığında.
  • Bir kullanıcı başka bir cihazdan (yani authenticatorAttachment değeri cross-platform olan) geçiş anahtarını kullanarak oturum açtığında.
  • 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ırsınız.

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: Kullanıcının geçiş anahtarını oluşturup depolayan kimlik doğrulayıcısı. Bu kod, 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 süreci aşağıdaki gibidir:

  1. Kullanıcı, web sitesinde oturum açar.
  2. Kullanıcı oturum açtıktan sonra "Geçiş anahtarı oluştur" düğmesine basarak ön uçta geçiş anahtarı oluşturmak ister.
  3. Ön uç; kullanıcı bilgileri, sorgulama ve hariç tutulacak kimlik bilgisi kimlikleri gibi geçiş anahtarı oluşturmak için arka uçtan bilgi ister.
  4. Kullanıcı arabirimi, geçiş anahtarı oluşturmak için navigator.credentials.create() yöntemini çağırır. Bu çağrı, bir söz veriyor.
  5. Geçiş anahtarı, kullanıcı cihazın ekran kilidini kullanarak izin verdikten sonra oluşturulur. Sözü çözüme ulaştırılır ve ortak anahtar kimlik bilgisi ön uca döndürülür.
  6. Ön uç, ortak anahtar kimlik bilgisini arka uca gönderir ve gelecekteki kimlik doğrulamalar 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. Geçiş anahtarı oluşturmayı hangi tarayıcı ve işletim sistemi kombinasyonlarının desteklediğini öğrenmek için Cihaz Desteği - passkeys.dev sayfasına bakın.

Yeni geçiş anahtarı oluşturun

Yeni bir geçiş anahtarı oluşturma isteği üzerinde bir ön uç aşağıdaki gibi çalışmalıdır.

Özellik algılama

"Yeni geçiş anahtarı oluştur" düğmesini görüntülemeden önce şunları kontrol edin:

  • Tarayıcı WebAuthn'u destekler.
  • 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. "Yeni geçiş anahtarı oluştur" düğmesi o zamana kadar görüntülenmeyecektir.

Önemli bilgileri arka uçtan alın

Kullanıcı düğmeyi tıkladığında arka uçtan navigator.credentials.create() çağrısı yapılacak önemli bilgileri getirin:

  • challenge: Bu kayıt için ArrayBuffer'da sunucu tarafından oluşturulan bir sorgulama. Bu bilgi zorunludur ancak burada ele alınmayan ileri düzey bir konu olan onay yapılmadığı sürece kayıt sırasında kullanılmaz.
  • 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 bir 16 baytlık değer işe yarayacaktır.
  • user.name: Bu alanda, kullanıcının tanıyacağı hesaba ait benzersiz bir tanımlayıcı (ör. e-posta adresi veya kullanıcı adı) bulunmalıdır. Bu, hesap seçicide gösterilir. (Kullanıcı adı kullanıyorsanız şifreli kimlik doğrulamasındakiyle aynı değeri kullanın.)
  • user.displayName: Bu alan, hesap için zorunlu ve daha kullanıcı dostu bir addır. Bu adın benzersiz olması gerekmez ve kullanıcının seçtiği ad olabilir. Siteniz buraya eklenecek uygun bir değere sahip değilse boş bir dize iletin. Bu, tarayıcıya bağlı olarak hesap seçicide 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ğırma

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östermesini bekleyerek bir söz döndürür.

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: Kısıtlanmış taraf kimliği bir alandır ve web sitesi, alan adını veya kaydedilebilir bir son eki belirtebilir. Örneğin, bir kısıtlanmış tarafın kaynağı https://login.example.com:1337 ise Kısıtlanmış Taraf kimliği login.example.com veya example.com olabilir. RP kimliği example.com olarak belirtilirse kullanıcı login.example.com veya example.com üzerindeki herhangi bir alt alanda kimlik doğrulaması yapabilir.

  • rp.name: Kısıtlanmış tarafın adı.

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

  • authenticatorSelection.authenticatorAttachment: Geçiş anahtarı oluşturma işlemi bir şifrenin yükseltmesiyse (ör. oturum açtıktan sonra bir promosyonda) bunu "platform" olarak ayarlayın. "platform", RP'nin bir platform kimlik doğrulayıcı (platform cihazına yerleştirilmiş bir kimlik doğrulayıcı) istediğini gösterir. Bu kimlik doğrulayıcı, USB güvenlik anahtarı gibi bir kişinin takılmasını istemez. Kullanıcılar daha basit bir seçenek kullanarak geçiş anahtarı oluşturabilir.

  • authenticatorSelection.requireResidentKey: "true" boole değeri olarak ayarlayın. Bulunabilir kimlik bilgisi (yerleşik anahtar), kullanıcı bilgilerini geçiş anahtarında depolar ve kimlik doğrulama sonrasında kullanıcıların hesabı seçebilmesini sağlar.

  • authenticatorSelection.userVerification: Cihaz ekran kilidini kullanan bir kullanıcı doğrulamasının "required", "preferred" veya "discouraged" arasından hangisi 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 bilgisini arka uca gönder

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

Söz konusu vaat farklı nedenlerle reddedilebilir. Error nesnesinin name özelliğini kontrol ederek bu hataları düzeltebilirsiniz:

  • InvalidStateError: Cihazda zaten bir geçiş anahtarı vardır. Kullanıcıya herhangi bir hata iletişim kutusu gösterilmez ve sitenin bu durumu bir hata olarak değerlendirmemesi gerekir. Kullanıcı, yerel cihazın kaydedilmesini istemiştir ve bu, kaydedilmiştir.
  • NotAllowedError: Kullanıcı, işlemi iptal etti.
  • Diğer istisnalar: Beklenmeyen bir hata oluştu. 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 ArrayBuffer sürümü.
  • response.clientDataJSON: ArrayBuffer kodlamalı istemci verileri.
  • response.attestationObject: ArrayBuffer kodlamalı bir onay nesnesidir. Bu, RP kimliği, bayraklar ve ortak anahtar gibi önemli bilgileri 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çta ortak anahtar kimlik bilgisi nesnesini işlemek için bir kitaplık kullanıyorsanız nesnenin tamamını, kısmen base64url ile kodladıktan sonra arka uca göndermenizi öneririz.

Kimlik bilgisini kaydedin

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

Daha sonra, kimlik bilgisinden aldığınız bilgileri ileride kullanmak üzere veritabanında saklayabilirsiniz. Aşağıdaki listede, kaydedilecek bazı genel özellikler yer almaktadı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 Formu otomatik doldurma aracılığıyla geçiş anahtarıyla oturum açma başlıklı makaleyi inceleyin.

Kaynaklar