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

Web sitelerinin, şifre yerine geçiş anahtarları kullanması, kullanıcı hesaplarını daha güvenli, basit, kullanımı kolay ve şifresiz hale getirmenin mükemmel bir yoludur. Geçiş anahtarı sayesinde kullanıcılar yalnızca parmak izlerini, yüzlerini veya cihaz PIN'lerini kullanarak bir web sitesinde ya da uygulamada oturum açabilir.

Kullanıcıların bu anahtarla oturum açabilmesi için bir geçiş anahtarı oluşturulması, bir kullanıcı hesabıyla ilişkilendirilmesi ve herkese açık anahtarının sunucunuzda depolanması gerekir.

İşleyiş şekli

Kullanıcıdan aşağıdaki durumlardan birinde 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ı: JavaScript'inizi çalıştıran kullanıcının tarayıcısı.
• Authenticator: Geçiş anahtarını oluşturan ve saklayan kullanıcının kimlik doğrulama aracı. Bu, tarayıcı ile aynı cihazdaki (ör. Windows Hello kullanılırken) veya telefon gibi başka bir cihazdaki şifre yöneticisini içerebilir.

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, ön uçta geçiş anahtarı oluşturmayı ister (ör. "Geçiş anahtarı oluştur" düğmesine basarak).
3. Kullanıcı arayüzü, geçiş anahtarı oluşturmak için arka uçtan kullanıcı bilgileri, istem ve hariç tutulacak kimlik bilgisi kimlikleri gibi bilgiler ister.
4. Kullanıcı arayüzü, geçiş anahtarı oluşturmak için navigator.credentials.create()'ü çağırır. Bu çağrı bir promise döndürür.
5. Kullanıcı, cihazın ekran kilidini kullanmaya izin verdikten sonra geçiş anahtarı oluşturulur. Söz çözülür ve ön uçta bir ortak anahtar kimlik bilgisi döndürülür.
6. Kullanıcı arayüzü, ortak anahtar kimlik bilgisini arka uca gönderir ve gelecekteki kimlik doğrulamaları için kimlik bilgisi kimliğini ve kullanıcı hesabıyla ilişkili 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 - 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 platform kimlik doğrulayıcıyı destekler (geçiş anahtarı oluşturabilir ve geçiş anahtarıyla kimlik doğrulayabilir).

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

Arka uçtan önemli bilgileri getirme

Kullanıcı düğmeyi tıkladığında, arka uçtan navigator.credentials.create() çağrısı yapmak için önemli bilgileri alın:

• challenge: Bu kayıt için sunucu tarafından oluşturulan ArrayBuffer'da bir istem. Bu alan zorunludur ancak onaylama yapılmadığı sürece kayıt sırasında kullanılmaz. Onaylama, burada ele alınmayan ileri düzey bir konudur.
• 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 rastgele oluşturulan 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, 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. Sağlandıysa transports üyesi, 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şimini bekleyen bir söz döndürür ve kalıcı iletişim kutusu gösterir.

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.example.com

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

• pubKeyCredParams: Bu alan, RP'nin desteklediği ortak anahtar algoritmalarını belirtir. [{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 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. Bulanıklanabilir 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. 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"'tür. 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önderme

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.

Taahhüt 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 saklanması gerekir.
• rawId: Kimlik bilgisi kimliğinin ArrayBuffer sürümü.
• response.clientDataJSON: ArrayBuffer olarak kodlanmış müşteri verileri.
• response.attestationObject: ArrayBuffer kodlu bir doğrulama nesnesi. Bu, 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" 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, kaydedebileceğiniz bazı tipik özellikler verilmiştir:

• Kimlik bilgisi kimliği (Birincil anahtar)
• Kullanıcı kimliği
• Herkese açık anahtar

Herkese açık 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şaretçisi: true Oluşturulan geçiş anahtarı gerçekten senkronize edilecek şekilde ayarlanmışsa.
• 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ı kaydetme
• Form otomatik doldurma özelliğiyle 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ıyla şifresiz giriş