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

Geçiş anahtarları, kullanıcı hesaplarını daha güvenli, daha basit ve daha 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
• Kullanıcı başka bir cihazdaki geçiş anahtarını kullanarak oturum açtığında (yani authenticatorAttachment cross-platform ise).
• Kullanıcıların şifre 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ı ile iletişim kuran ve arka uca getirme istekleri gönderen ön uçunuz.
• Tarayıcı: Kullanıcının JavaScript'inizi çalıştıran tarayıcısı.
• Authenticator: Geçiş anahtarını oluşturan ve saklayan kullanıcının kimlik doğrulama aracı. Tarayıcı ile aynı cihazdaki (ör. Windows Hello kullanılırken) veya telefon gibi başka bir cihazdaki şifre yöneticisi bu kapsamda olabilir.

Mevcut bir kullanıcı hesabına yeni geçiş anahtarı ekleme adımları şunlardır:

1. Kullanıcı web sitesinde oturum açar.
2. Kullanıcı oturum açtıktan sonra, örneğin "Geçiş anahtarı oluştur" düğmesine basarak kullanıcı arayüzünde geçiş anahtarı oluşturma isteğinde bulunur.
3. Kullanıcı bilgileri, istem ve hariç tutulacak kimlik bilgisi kimlikleri gibi geçiş anahtarı oluşturmak için ön uç, arka uçtan bilgi ister.
4. Kullanıcı arayüzü, geçiş anahtarı oluşturmak için navigator.credentials.create()'ü çağırır. Bu çağrı, bir söz veriyor.
5. Kullanıcı, cihazın ekran kilidini kullanmaya izin verdikten sonra geçiş anahtarı 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ı destekleyen tarayıcı ve işletim sistemi kombinasyonlarını öğrenmek için Cihaz Desteği - passkeys.dev sayfasına bakın.

Yeni geçiş anahtarı oluşturma

Yeni geçiş anahtarı oluşturma isteği üzerine ön uç nasıl çalışmalıdır?

Özellik algılama

"Yeni geçiş anahtarı oluştur" düğmesini göstermeden önce aşağıdakileri kontrol edin:

• Tarayıcı, PublicKeyCredential ile WebAuthn'u desteklemelidir.

• Cihaz, PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() ile bir platform kimlik doğrulayıcısını (geçiş anahtarı oluşturabilir ve geçiş anahtarıyla kimlik doğrulaması yapabilir) destekler.

• Tarayıcı, PublicKeyCredenital.isConditionalMediationAvailable() ile 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. Bu süre dolana kadar "Yeni geçiş anahtarı oluştur" düğmesi gösterilmez.

Ö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 kimliği tanımlayabilecek 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 şifre kimlik doğrulamasında kullanılanla 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. Sitenizde buraya dahil edilecek uygun bir değer yoksa boş bir dize gönderin. Bu mesaj, tarayıcıya bağlı olarak hesap seçicide gösterilebilir.
• excludeCredentials: Zaten 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: RP kimliği bir alandır ve web siteleri kendi alanlarını veya kaydedilebilir bir son eki belirtebilir. Örneğin, bir 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'da veya login.example.com'daki herhangi bir alt alan adında 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ğini belirtir ve bunların desteklenmesi tam kapsam sağlar.

• authenticatorSelection.authenticatorAttachment: Geçiş anahtarı oluşturma işlemi, şifre yükseltme işlemiyse (ör. oturum açtıktan sonra bir promosyonda) bu değeri "platform" olarak ayarlayın. "platform", RP'nin USB güvenlik anahtarı gibi bir cihaz takmayı gerektirmeyen bir platform kimlik doğrulayıcı (platform cihazına yerleştirilmiş bir kimlik doğrulayıcı) istediğini gösterir. Kullanıcının geçiş anahtarı oluşturmak için daha basit bir seçeneği vardır.

• authenticatorSelection.requireResidentKey: Boole "true" 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. Bulunabilir kimlik bilgileri hakkında ayrıntılı bilgi başlıklı makalede bulunabilir kimlik bilgileri hakkında daha fazla bilgi edinin.

• authenticatorSelection.userVerification: Cihaz ekran kilidinin kullanıldığı kullanıcı doğrulamasının "required", "preferred" veya "discouraged" olup olmadığını belirtir. Varsayılan değer "preferred" şeklindedir. Bu, kimlik doğrulayıcının kullanıcı doğrulamasını atlayabileceği anlamına gelir. Bu değeri "preferred" olarak ayarlayın veya mülkü çıkarın.

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

Kullanıcı cihazın ekran kilidini kullanmaya izin verdikten sonra bir geçiş anahtarı oluşturulur ve söz, ön uçta bir PublicKeyCredential nesnesi döndürerek çözülür.

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

• InvalidStateError: Cihazda zaten bir geçiş anahtarı var. Kullanıcıya hata iletişim kutusu gösterilmez ve site bunu hata olarak değerlendirmemelidir. Kullanıcı yerel cihazın kaydedilmesini istedi ve cihaz kaydedildi.
• 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 olarak kodlanmış kimliği. Bu kimlik, tarayıcıya kimlik doğrulamasından sonra 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 kodlu bir doğrulama nesnesi. 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" döndürülü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ı, base64url ile kısmen kodladıktan sonra arka uca göndermenizi öneririz.

Kimlik bilgisini kaydetme

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

Ardından, kimlik bilgisinden alınan bilgileri gelecekte 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:

• Yedekleme Uygunluğu işareti: true Cihaz, geçiş anahtarı senkronizasyonu için uygunsa.
• Yedekleme Durumu işareti: Oluşturulan geçiş anahtarı gerçekten senkronize edilecek şekilde ayarlanmışsa true.
• Aktarımlar: Cihazın desteklediği aktarımların listesi: "internal", cihazın geçiş anahtarını desteklediği anlamına gelir. "hybrid", başka bir cihazda kimlik doğrulamayı da desteklediği anlamına gelir.

Sunucu tarafı geçiş anahtarı kaydıyla ilgili daha ayrıntılı talimatları uygulayın.

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

Kaynaklar

• Sunucu tarafı geçiş anahtarı kaydı
• Formları otomatik doldurma aracılığıyla geçiş anahtarıyla oturum açma
• Geçiş anahtarları
• Apple dokümanı: Web Hizmeti Aracılığıyla Kullanıcı Kimliğini Doğrulama
• Google dokümanı: Geçiş anahtarları ile şifresiz giriş