kullanma geçiş anahtarları şifreler yerine, web sitelerinin kullanıcı hesaplarını daha güvenli, daha basit, kullanımı daha kolay ve şifresiz hale getirmeleri için harika bir yoldur. Parola ile kullanıcı, yalnızca parmak izini, yüzünü veya cihaz PIN’ini kullanarak bir web sitesinde veya uygulamada oturum açabilir.
Bir kullanıcı hesabıyla ilişkilendirilmiş bir geçiş anahtarı oluşturulmalı ve bir kullanıcının onunla oturum açabilmesi için ortak anahtarının sunucunuzda saklanması gerekir.
Nasıl çalışır #
Bir kullanıcıdan aşağıdaki durumlardan birinde geçiş anahtarı oluşturması istenebilir:
- Bir kullanıcı bir parola veya başka bir aygıttan bir geçiş anahtarı kullanarak oturum açtığında (yani,
authenticatorAttachmentdır-dircross-platform). - Kullanıcıların geçiş anahtarlarını yönetebilecekleri özel bir sayfada.
Bir geçiş anahtarı oluşturmak için, WebAuthn API’si.
Geçiş anahtarı kayıt akışının dört bileşeni şunlardır:
- arka uç: Genel anahtarı ve geçiş anahtarıyla ilgili diğer meta verileri depolayan hesap veritabanını tutan arka uç sunucunuz.
- Başlangıç aşaması: Tarayıcı ile iletişim kuran ve arka uca getirme isteklerini gönderen ön yüzünüz.
- Tarayıcı: Javascript’inizi çalıştıran kullanıcının tarayıcısı.
- Doğrulayıcı: Geçiş anahtarını oluşturan ve depolayan kullanıcının kimlik doğrulayıcısı. Bu, tarayıcıyla aynı cihazda (örneğin, Windows Hello kullanırken) veya telefon gibi başka bir cihazda olabilir.
Mevcut bir kullanıcı hesabına yeni bir geçiş anahtarı ekleme yolculuğu aşağıdaki gibidir:
- Bir kullanıcı web sitesinde oturum açar.
- Kullanıcı oturum açtıktan sonra, örneğin bir “Geçiş anahtarı oluştur” düğmesine basarak ön uçta bir geçiş anahtarı oluşturmayı talep eder.
- Ön uç, bir geçiş anahtarı oluşturmak için arka uçtan kullanıcı bilgileri, bir meydan okuma ve hariç tutulacak kimlik bilgileri gibi bilgiler ister.
- ön uç çağrıları
navigator.credentials.create()geçiş anahtarı oluşturmak için. Bu çağrı bir söz verir. - Kullanıcı, cihazın ekran kilidini kullanmaya izin verdikten sonra bir geçiş anahtarı oluşturulur. Taahhüt çözümlenir ve ön uca bir ortak anahtar kimlik bilgisi döndürülür.
- Ön uç, ortak anahtar kimlik bilgisini arka uca gönderir ve kimlik bilgisi kimliğini ve gelecekteki kimlik doğrulamaları için kullanıcı hesabıyla ilişkili genel anahtarı depolar.
uyumluluklar #
WebAuthn çoğu tarayıcı tarafından desteklenir, ancak küçük boşluklar vardır. bakın Cihaz Desteği – passkeys.dev hangi tarayıcı ve işletim sistemi kombinasyonunun geçiş anahtarı oluşturmayı desteklediğini öğrenmek için.
Yeni bir geçiş anahtarı oluştur #
Yeni bir geçiş anahtarı oluşturma isteği üzerine bir ön ucun nasıl çalışması gerektiği aşağıda açıklanmıştı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 (bir geçiş anahtarı oluşturabilir ve geçiş anahtarıyla kimlik doğrulaması yapabilir).
- Tarayıcı, WebAuthn koşullu kullanıcı arabirimini 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 desteklenmeyecektir. “Yeni bir geçiş anahtarı oluştur” düğmesi o zamana kadar görüntülenmemelidir.
Arka uçtan önemli bilgileri alın #
Kullanıcı düğmeyi tıkladığında, aranacak önemli bilgileri getir navigator.credentials.create() arka uçtan:
challenge: Bu kayıt için ArrayBuffer’da sunucu tarafından oluşturulan bir meydan okuma. Bu gereklidir, ancak yapılmadığı sürece kayıt sırasında kullanılmaz. tasdik—burada ele alınmayan ileri düzey bir konu.user.id: Bir kullanıcının benzersiz kimliği. Bu değer, e-posta adresleri veya kullanıcı adları gibi kişisel olarak tanımlayıcı bilgileri içermeyen bir ArrayBuffer olmalıdır. Hesap başına oluşturulan rastgele, 16 baytlık bir değer iyi çalışır.user.name: Bu alan, e-posta adresi veya kullanıcı adı gibi, kullanıcının tanıyacağı hesap için benzersiz bir tanımlayıcı içermelidir. Bu, hesap seçicide görüntülenecektir. (Kullanıcı adı kullanılıyorsa, parola kimlik doğrulamasındakiyle aynı değeri kullanın.)user.displayName: Bu alan, hesap için isteğe bağlı, daha kullanıcı dostu bir addır. Benzersiz olması gerekmez ve kullanıcının seçtiği ad olabilir. Sitenizin buraya eklemek için uygun bir değeri yoksa boş bir dize iletin. Bu, tarayıcıya bağlı olarak hesap seçicide görüntülenebilir.excludeCredentials: Halihazırda kayıtlı kimlik bilgisi kimliklerinin bir listesini sağlayarak aynı cihazın kaydedilmesini önler. butransportsüye, sağlanmışsa, çağrının sonucunu içermelidirgetTransports()her kimlik bilgisinin kaydı sırasında.
Geçiş anahtarı oluşturmak için WebAuthn API’yi çağırın #
Arama navigator.credentials.create() Yeni bir geçiş anahtarı oluşturmak için. API, kalıcı bir iletişim kutusu görüntüleyen kullanıcının etkileşimini bekleyen 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: Bir RP Kimliği bir etki alanıdır ve bir web sitesi, etki alanını veya kaydedilebilir bir son eki belirtebilir. Örneğin, bir RP’nin menşeihttps://login.example.com:1337RP Kimliği şunlardan biri olabilir:login.example.comveyaexample.com. RP kimliği olarak belirtilirseexample.comkullanıcı üzerinde kimlik doğrulaması yapabilirlogin.example.comveya herhangi bir alt etki alanındaexample.com.rp.name: RP’nin adı.pubKeyCredParams: Bu alan, RP’nin desteklenen açık anahtar algoritmalarını belirtir. olarak ayarlamanızı öneririz.[{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}]. Bu, P-256 ve RSA PKCS#1 ile ECDSA desteğini belirtir ve bunları desteklemek tam kapsam sağlar.authenticatorSelection.authenticatorAttachment: Ayarla"platform". Bu, platform aygıtına gömülü bir kimlik doğrulayıcı istediğimizi gösterir ve kullanıcıdan örneğin bir USB güvenlik anahtarı girmesi istenmez.authenticatorSelection.requireResidentKey: Bir boole “true” olarak ayarlayın. Keşfedilebilir bir kimlik bilgisi (yerleşik anahtar), kullanıcı bilgilerini geçiş anahtarında saklar ve kullanıcıların kimlik doğrulama sonrasında hesabı seçmesine olanak tanır.authenticatorSelection.userVerification: Cihaz ekran kilidini kullanan bir kullanıcı doğrulamasının yapılıp yapılmadığını gösterir."required","preferred"veya"discouraged". varsayılan"preferred", bu, kimlik doğrulayıcının kullanıcı doğrulamasını atlayabileceği anlamına gelir. Bunu şuna ayarla:"preferred"veya özelliği atlayın.
Döndürülen ortak anahtar kimlik bilgisini arka uca gönderin #
Kullanıcı, cihazın ekran kilidinin kullanılmasına izin verdikten sonra, bir geçiş anahtarı oluşturulur ve bir parola döndürerek taahhüt çözülür. PublicKeyKimlik Bilgileri ön uca itiraz edin.
Söz farklı nedenlerle reddedilebilir. Kontrol ederek bu hataları halledebilirsiniz. Error nesnenin name mülk:
InvalidStateError: Cihazda zaten bir geçiş anahtarı var. Kullanıcıya hiçbir hata iletişim kutusu gösterilmez ve site bunu bir hata olarak değerlendirmemelidir; kullanıcı yerel aygıtın kaydedilmesini istedi ve öyle de oldu.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 kodlu 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 saklanması gerekir.rawId: Kimlik bilgisi kimliğinin bir ArrayBuffer sürümü.response.clientDataJSON: Bir ArrayBuffer kodlu müşteri verisi.response.attestationObject: Bir ArrayBuffer kodlu doğrulama nesnesi. Bu, RP kimliği, bayraklar ve genel anahtar gibi önemli bilgileri içerir.authenticatorAttachment: İadeler"platform"bu kimlik bilgisi geçiş anahtarı özellikli bir cihazda oluşturulduğunda.type: Bu alan her zaman"public-key".
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 bilgilerini kaydet #
Arka uçta ortak anahtar kimlik bilgisini aldıktan sonra, nesneyi işlemek için bunu FIDO kitaplığına iletin.
Daha sonra, kimlik bilgisinden alınan bilgileri ileride kullanmak üzere veritabanında saklayabilirsiniz. Aşağıdaki liste, kaydedilecek bazı tipik özellikleri içerir:
- Kimlik Bilgisi Kimliği (Birincil anahtar)
- Kullanıcı kimliği
- Genel 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 yoluyla geçiş anahtarıyla oturum açın bölümünü okuyun.