Geçiş anahtarları, kullanıcı hesaplarını daha güvenli, basit ve kullanımı kolay hale getirir.
Ş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ğericross-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ı. Buna, tarayıcıyla aynı cihazdaki (örneğin, Windows Hello'yu kullanırken) veya başka bir cihazdaki (ör. bir telefon) şifre yöneticisi de dahil olabilir.
![Geçiş anahtarı kayıt şeması](https://web.dev/static/articles/passkey-registration/image/passkey-registration-diagram.png?authuser=6&hl=tr)
Mevcut bir kullanıcı hesabına yeni geçiş anahtarı ekleme süreci aşağıdaki gibidir:
- Kullanıcı, web sitesinde oturum açar.
- Kullanıcı oturum açtıktan sonra "Geçiş anahtarı oluştur" düğmesine basarak ön uçta geçiş anahtarı oluşturmak ister.
- Ö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.
- 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. - 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.
- Ö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ı,
PublicKeyCredential
ile WebAuthn'u destekler.
- 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. "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 bilgi, 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ındagetTransports()
ç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ğilogin.example.com
veyaexample.com
olabilir. RP kimliğiexample.com
olarak belirtilirse kullanıcılogin.example.com
veyaexample.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. Bulunabilir kimlik bilgileri hakkında daha fazla bilgiye Keşfedilebilir kimlik bilgileri ayrıntılı incelemesi bölümünden ulaşabilirsiniz.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:
- Yedekleme Uygunluğu işareti:
Cihaz, geçiş anahtarı senkronizasyonuna uygunsa
true
. - 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 bir geçiş anahtarını desteklediğini,"hybrid"
ise başka bir cihazda kimlik doğrulamayı desteklediğini gösterir.
Sunucu tarafı geçiş anahtarı kaydı bölümünde daha ayrıntılı talimatları uygulayın.
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.