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

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

Eiji Kitamura

Yayınlanma tarihi: 12 Ekim 2022, Son güncelleme tarihi: 9 Nisan 2026

Geçiş anahtarları kullanmak güvenliği artırır, oturum açma işlemlerini basitleştirir ve şifrelerin yerini alır. Kullanıcıların hatırlaması ve manuel olarak girmesi gereken normal şifrelerin aksine, geçiş anahtarları cihazın biyometri veya PIN gibi ekran kilidi mekanizmalarını kullanır ve kimlik avı risklerini ve kimlik bilgisi hırsızlığını azaltır.

Geçiş anahtarları, Google Şifre Yöneticisi ve iCloud Anahtar Zinciri gibi geçiş anahtarı sağlayıcılar kullanılarak cihazlar arasında senkronize edilir.

Geçiş anahtarı oluşturulmalı, özel anahtar gerekli meta verilerle birlikte geçiş anahtarı sağlayıcısında güvenli bir şekilde saklanmalı ve kimlik doğrulama için ortak anahtarı sunucunuzda depolanmalıdır. Özel anahtar, kullanıcının geçerli alanda doğrulanmasının ardından bir imza oluşturur. Bu sayede geçiş anahtarları kimlik avına karşı dirençli hale gelir. Ortak anahtar, hassas kimlik bilgilerini depolamadan imzayı doğrular. Bu sayede geçiş anahtarları, kimlik bilgilerinin çalınmasına karşı dirençli olur.

Geçiş anahtarı oluşturmanın işleyiş şekli

Kullanıcıların geçiş anahtarıyla oturum açabilmesi için geçiş anahtarını oluşturmanız, bir kullanıcı hesabıyla ilişkilendirmeniz ve herkese açık anahtarını sunucunuzda saklamanız gerekir.

Kullanıcılardan aşağıdaki durumlardan birinde geçiş anahtarı oluşturmalarını isteyebilirsiniz:

• Kayıt sırasında veya sonrasında
• Oturum açtıktan sonra
• Başka bir cihazdaki geçiş anahtarını kullanarak oturum açtıktan sonra (yani authenticatorAttachment cross-platform).
• 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ç: Genel anahtar dahil olmak üzere kullanıcı hesabı ayrıntılarını depolar.
• Ön uç: Tarayıcıyla iletişim kurar ve arka uçtan gerekli verileri getirir.
• Tarayıcı: JavaScript'inizi çalıştırır ve WebAuthn API ile etkileşimde bulunur.
• Geçiş anahtarı sağlayıcı: Geçiş anahtarını oluşturur ve saklar. Bu genellikle Google Şifre Yöneticisi gibi bir şifre yöneticisi veya güvenlik anahtarıdır.

Geçiş anahtarı oluşturmadan önce sistemin aşağıdaki ön koşulları karşıladığından emin olun:

• Kullanıcı hesabı, anlamlı bir şekilde kısa süre içinde güvenli bir yöntemle (ör. e-posta, telefon doğrulaması veya kimlik federasyonu) doğrulanır.

• Ön uç ve arka uç, kimlik bilgisi verilerini güvenli bir şekilde paylaşmak için iletişim kurabilir.

• Tarayıcı, WebAuthn'u ve geçiş anahtarı oluşturmayı desteklemelidir.

Çoğunu nasıl kontrol edeceğinizi aşağıdaki bölümlerde gösterebiliriz.

Sistem bu koşulları karşıladığında geçiş anahtarı oluşturmak için aşağıdaki süreç gerçekleşir:

1. Kullanıcı işlemi başlattığında (ör. geçiş anahtarı yönetim sayfasında veya kaydını tamamladıktan sonra "Geçiş Anahtarı Oluştur" düğmesini tıkladığında) sistem geçiş anahtarı oluşturma sürecini tetikler.
2. Ön uç, kullanıcı bilgileri, bir sorgu ve kimlik bilgilerinin kimlikleri dahil olmak üzere gerekli kimlik bilgisi verilerini arka uçtan ister. Bu veriler, kimlik bilgilerinin yinelenmesini önlemek için kullanılır.
3. Ön uç, navigator.credentials.create() işlevini çağırarak cihazın geçiş anahtarı sağlayıcısından arka uçtaki bilgileri kullanarak geçiş anahtarı oluşturmasını ister. Bu işlevin bir söz döndürdüğünü unutmayın.
4. Kullanıcının cihazı, geçiş anahtarı oluşturmak için biyometrik yöntem, PIN veya desen kullanarak kullanıcının kimliğini doğrular.
5. Geçiş anahtarı sağlayıcı, bir geçiş anahtarı oluşturur ve ön uca bir ortak anahtar kimlik bilgisi döndürerek sözü yerine getirir.
6. Ön uç, oluşturulan ortak anahtar kimlik bilgisini arka uca gönderir.
7. Arka uç, gelecekteki kimlik doğrulama için ortak anahtarı ve diğer önemli verileri depolar.
8. Arka uç, kullanıcının geçiş anahtarı oluşturma işlemini onaylaması ve olası yetkisiz erişimi tespit etmesi için kullanıcıyı (ör. e-posta kullanarak) bilgilendirir.

Bu süreç, kullanıcılar için güvenli ve sorunsuz bir geçiş anahtarı kayıt süreci sağlar.

Uyumluluk

Çoğu tarayıcı, küçük boşluklar olsa da WebAuthn'yi destekler. Tarayıcı ve işletim sistemi uyumluluğu ayrıntıları için passkeys.dev adresini ziyaret edin.

Yeni geçiş anahtarı oluşturma

Yeni bir geçiş anahtarı oluşturmak için ön ucun izlemesi gereken süreç şöyledir:

1. Uyumluluğu kontrol edin.
2. Arka uçtan bilgi getirme
3. Geçiş anahtarı oluşturmak için WebAuth API'yi çağırın.
4. Döndürülen ortak anahtarı arka uca gönderin.
5. Kimlik bilgisini kaydedin.

Aşağıdaki bölümlerde bu işlemi nasıl yapabileceğiniz gösterilmektedir.

Uyumluluğu kontrol etme

Ön uç, "Yeni geçiş anahtarı oluştur" düğmesini göstermeden önce aşağıdakileri kontrol etmelidir:

• Tarayıcı, PublicKeyCredential ile WebAuthn'u destekliyor olmalıdır.

• Tarayıcı, PublicKeyCredential.getClientCapabilities() ile özellik algılamayı destekler.

• Tarayıcı, conditionalGet ile WebAuthn koşullu kullanıcı arayüzünü destekliyor.

• Cihaz, passkeyPlatformAuthenticator ile platform kimlik doğrulayıcısını (cihazda geçiş anahtarı oluşturabilir ve kimlik doğrulama yapabilir) destekliyor.

Aşağıdaki kod snippet'inde, geçiş anahtarıyla ilgili seçenekleri göstermeden önce uyumluluğu nasıl kontrol edebileceğiniz gösterilmektedir.

if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
  const capabilities = await PublicKeyCredential.getClientCapabilities();
  if (capabilities.conditionalGet === true &&
      capabilities.passkeyPlatformAuthenticator === true) {
    // The browser supports passkeys and the conditional UI.
  }
}

Bu örnekte, Yeni geçiş anahtarı oluştur düğmesi yalnızca tüm koşullar karşılandığında gösterilmelidir.

Arka uçtan bilgi getirme

Kullanıcı düğmeyi tıkladığında, navigator.credentials.create() işlevini çağırmak için arka uçtan gerekli bilgileri getirin.

Aşağıdaki kod snippet'inde, navigator.credentials.create() işlevini çağırmak için gereken bilgileri içeren bir JSON nesnesi gösterilmektedir:

// Example `PublicKeyCredentialCreationOptions` contents
{
  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,
  }
}

Nesnedeki anahtar/değer çiftleri aşağıdaki bilgileri içerir:

• challenge: Bu kayıt için ArrayBuffer'da sunucu tarafından oluşturulan bir sorgu.
• rp.id: Bir RP kimliği (Relying Party ID), alan adı ve web sitesi kendi alan adını veya kayıt edilebilir bir soneki 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 üzerinde veya example.com üzerindeki herhangi bir alt alanda kimlik doğrulaması yapabilir. Bu konu hakkında daha fazla bilgi için İlişkili Kaynak İstekleri ile sitelerinizde geçiş anahtarı yeniden kullanımına izin verme başlıklı makaleyi inceleyin.
• rp.name: RP'nin (Relying Party) adı. Bu özellik, WebAuthn L3'te kullanımdan kaldırılmıştır ancak uyumluluk nedeniyle dahil edilmiştir.
• user.id: Hesap oluşturulduğunda oluşturulan ArrayBuffer'daki benzersiz kullanıcı kimliği. Düzenlenebilir bir kullanıcı adının aksine kalıcı olmalıdır. Kullanıcı kimliği bir hesabı tanımlar ancak kimliği tanımlayabilecek bilgiler (PII) içermemelidir. Sisteminizde muhtemelen zaten bir kullanıcı kimliği vardır ancak gerekirse kişisel olarak tanımlanabilecek bilgiler içermemesi için geçiş anahtarları için özel olarak bir kullanıcı kimliği oluşturun.
• user.name: Kullanıcının tanıyacağı, hesaba ait benzersiz bir tanımlayıcı (ör. e-posta adresi veya kullanıcı adı). Bu ad, hesap seçicide gösterilir.
• user.displayName: Hesap için zorunlu olan ve kullanıcı dostu bir ad. Benzersiz olması gerekmez ve kullanıcının seçtiği ad olabilir. Sitenizde buraya eklenecek uygun bir değer yoksa boş bir dize iletin. Bu bilgi, tarayıcıya bağlı olarak hesap seçicide gösterilebilir.
• pubKeyCredParams: RP (güvenen taraf) tarafından desteklenen ortak anahtar algoritmalarını belirtir. [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}] olarak ayarlamanızı öneririz. Bu, P-256 ile ECDSA ve RSA PKCS#1 için desteği belirtir. Bunları desteklemek tam kapsam sağlar.
• excludeCredentials: Daha önce kaydedilmiş kimlik bilgisi kimliklerinin listesi. Zaten kayıtlı kimliklerin listesini sağlayarak aynı cihazın iki kez kaydedilmesini önler. Sağlanıyorsa transports üyesi, her kimlik bilgisinin kaydı sırasında getTransports() çağrısının sonucunu içermelidir.
• authenticatorSelection.authenticatorAttachment: Bu geçiş anahtarı oluşturma işlemi, örneğin oturum açtıktan sonraki bir promosyonda şifreden yükseltme ise bunu hint: ['client-device'] ile birlikte "platform" olarak ayarlayın. "platform", RP'nin, örneğin USB güvenlik anahtarı takma istemi göstermeyen bir platform kimlik doğrulayıcısı (platform cihazına yerleştirilmiş bir kimlik doğrulayıcı) istediğini gösterir. Kullanıcı, geçiş anahtarı oluşturmak için daha basit bir seçeneğe sahiptir.
• authenticatorSelection.requireResidentKey: Boole true olarak ayarlayın. Keşfedilebilir kimlik bilgisi (yerleşik anahtar), kullanıcı bilgilerini geçiş anahtarına kaydeder ve kullanıcıların kimlik doğrulama sırasında hesabı seçmesine olanak tanır.

• authenticatorSelection.userVerification: Cihaz ekran kilidi kullanılarak yapılan kullanıcı doğrulamasının "required", "preferred" veya "discouraged" olup olmadığını gösterir. Varsayılan değer "preferred"'dır. 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.

Nesneyi sunucuda oluşturmanızı, ArrayBuffer'ı Base64URL ile kodlamanızı ve ön uçtan getirmenizi öneririz. Bu şekilde, PublicKeyCredential.parseCreationOptionsFromJSON() kullanarak yükü çözebilir ve doğrudan navigator.credentials.create()'ye iletebilirsiniz.

Aşağıdaki kod snippet'inde, geçiş anahtarı oluşturmak için gereken bilgilerin nasıl alınacağı ve kodunun nasıl çözüleceği gösterilmektedir.

// Fetch an encoded `PubicKeyCredentialCreationOptions` from the server.
const _options = await fetch('/webauthn/registerRequest');

// Deserialize and decode the `PublicKeyCredentialCreationOptions`.
const decoded_options = JSON.parse(_options);
const options = PublicKeyCredential.parseCreationOptionsFromJSON(decoded_options);
...

Geçiş anahtarı oluşturmak için WebAuthn API'yi çağırma

Yeni bir geçiş anahtarı oluşturmak için navigator.credentials.create() işlevini çağırın. API, kullanıcı etkileşimini beklerken modal iletişim kutusu gösteren bir söz döndürür.

// Invoke WebAuthn to create a passkey.
const credential = await navigator.credentials.create({
  publicKey: options
});

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

Kullanıcı, cihazın ekran kilidi kullanılarak doğrulandıktan sonra bir geçiş anahtarı oluşturulur ve promise çözülerek ön uca bir PublicKeyCredential nesnesi döndürülür.

Söz farklı nedenlerle reddedilebilir. Bu hataları, Error nesnesinin name özelliğini kontrol ederek giderebilirsiniz:

• InvalidStateError: Cihazda zaten bir geçiş anahtarı var. Kullanıcıya hata iletişim kutusu gösterilmez. Site bunu hata olarak değerlendirmemelidir. Kullanıcı, yerel cihazın kaydedilmesini istedi ve cihaz kaydedildi.
• NotAllowedError: Kullanıcı işlemi iptal etti.
• AbortError: İşlem iptal edildi.
• 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ının kimlik doğrulama sırasında cihazda eşleşen bir geçiş anahtarı olup olmadığını belirlemesine yardımcı olur. Bu değer, arka uçtaki veritabanında depolanmalıdır.
• rawId: Kimlik bilgisinin ArrayBuffer sürümü.
• response.clientDataJSON: ArrayBuffer kodlu istemci verileri.
• response.attestationObject: Bir ArrayBuffer kodlu onay nesnesi. Bu, RP kimliği, işaretler ve ortak anahtar gibi önemli bilgileri içerir.
• authenticatorAttachment: Bu kimlik bilgisi, geçiş anahtarı oluşturmaya uygun bir cihazda oluşturulduğunda "platform" değerini döndürür.
• type: Bu alan her zaman "public-key" olarak ayarlanır.

Nesneyi .toJSON() yöntemiyle kodlayın, JSON.stringify() ile serileştirin ve sunucuya gönderin.

...

// Encode and serialize the `PublicKeyCredential`.
const _result = credential.toJSON();
const result = JSON.stringify(_result);

// Encode and send the credential to the server for verification.  
const response = await fetch('/webauthn/registerResponse', {
  method: 'post',
  credentials: 'same-origin',
  body: result
});
...

Kimlik bilgisini kaydetme

Arka uçta ortak anahtar kimlik bilgisi alındıktan sonra, ortak anahtar kimlik bilgisini işlemek için kendi kodunuzu yazmak yerine sunucu tarafı kitaplığı veya çözüm kullanmanızı öneririz.

Daha sonra, kimlik bilgisinden alınan bilgileri gelecekte kullanmak üzere veritabanında saklayabilirsiniz.

Aşağıdaki listede, kaydedilmesi önerilen özellikler yer almaktadır:

• Kimlik bilgisi kimliği: Ortak anahtar kimlik bilgisiyle döndürülen kimlik bilgisi kimliği.
• Kimlik bilgisi adı: Kimlik bilgisinin adı. AAGUID'ye göre belirlenebilen, oluşturulduğu geçiş anahtarı sağlayıcısının adını verin.
• Kullanıcı kimliği: Geçiş anahtarını oluşturmak için kullanılan kullanıcı kimliği.
• Ortak anahtar: Ortak anahtar kimlik bilgisiyle döndürülen ortak anahtar. Bu, geçiş anahtarı onayını doğrulamak için gereklidir.
• Oluşturulma tarihi ve saati: Geçiş anahtarının oluşturulma tarihini ve saatini kaydeder. Bu, geçiş anahtarını tanımlamak için kullanışlıdır.
• Son kullanıldığı tarih ve saat: Kullanıcının oturum açmak için geçiş anahtarını kullandığı son tarih ve saati kaydeder. Bu, kullanıcının hangi geçiş anahtarını kullandığını (veya kullanmadığını) belirlemek için yararlıdır.
• AAGUID: Geçiş anahtarı sağlayıcısının benzersiz tanımlayıcısı.
• Yedekleme uygunluğu işareti: Cihaz geçiş anahtarı senkronizasyonuna uygunsa true. Bu bilgiler, kullanıcıların geçiş anahtarı yönetim sayfasında senkronize edilebilir geçiş anahtarlarını ve cihaza bağlı (senkronize edilemeyen) geçiş anahtarlarını belirlemelerine yardımcı olur.

Daha ayrıntılı talimatlar için Sunucu tarafında geçiş anahtarı kaydı başlıklı makaleyi inceleyin.

Kayıt başarısız olursa sinyal verin.

Geçiş anahtarı kaydı başarısız olursa kullanıcı kafa karışıklığı yaşayabilir. Geçiş anahtarı sağlayıcısında geçiş anahtarı varsa ve kullanıcı tarafından kullanılabilirse ancak ilişkili ortak anahtar sunucu tarafında depolanmamışsa geçiş anahtarı kullanılarak yapılan oturum açma girişimleri hiçbir zaman başarılı olmaz ve sorun giderme işlemi zorlaşır. Bu durumda kullanıcıyı bilgilendirin.

Bu durumu önlemek için Signal API'yi kullanarak geçiş anahtarı sağlayıcıya bilinmeyen bir geçiş anahtarı sinyali gönderebilirsiniz. RP, bir RP kimliği ve kimlik bilgisi kimliği ile PublicKeyCredential.signalUnknownCredential() işlevini çağırarak geçiş anahtarı sağlayıcıya belirtilen kimlik bilgisinin kaldırıldığını veya mevcut olmadığını bildirebilir. Bu sinyalin nasıl ele alınacağı geçiş anahtarı sağlayıcısına bağlıdır. Ancak destekleniyorsa ilişkili geçiş anahtarının kaldırılması beklenir.

// Detect authentication failure due to lack of the credential
if (response.status === 404) {
  // Feature detection
  if (PublicKeyCredential.signalUnknownCredential) {
    await PublicKeyCredential.signalUnknownCredential({
      rpId: "example.com",
      credentialId: "vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA" // base64url encoded credential ID
    });
  } else {
    // Encourage the user to delete the passkey from the password manager nevertheless.
    ...
  }
}

Signal API hakkında daha fazla bilgi edinmek için Signal API ile geçiş anahtarlarını sunucunuzdaki kimlik bilgileriyle tutarlı tutma başlıklı makaleyi inceleyin.

Kullanıcıya bildirim gönderme

Geçiş anahtarı kaydedildiğinde bildirim (ör. e-posta) gönderilmesi, kullanıcıların yetkisiz hesap erişimini tespit etmesine yardımcı olur. Saldırgan, kullanıcının bilgisi olmadan geçiş anahtarı oluşturursa şifre değiştirildikten sonra bile geçiş anahtarı kötüye kullanıma açık kalır. Bildirim, kullanıcıyı uyarır ve bu durumu önlemeye yardımcı olur.

Yapılacaklar listesi

• Kullanıcının geçiş anahtarı oluşturmasına izin vermeden önce kullanıcıyı doğrulayın (tercihen e-posta veya güvenli bir yöntem kullanarak).
• excludeCredentials kullanarak aynı geçiş anahtarı sağlayıcısı için yinelenen geçiş anahtarları oluşturulmasını önleyin.
• Geçiş anahtarı sağlayıcıyı tanımlamak ve kullanıcı için kimlik bilgilerini adlandırmak üzere AAGUID'yi kaydedin.
• Geçiş anahtarı kaydetme girişimi PublicKeyCredential.signalUnknownCredential() ile başarısız olursa sinyal verilir.
• Hesabı için geçiş anahtarı oluşturup kaydettikten sonra kullanıcıya bildirim gönderin.

Kaynaklar

• Sunucu tarafında geçiş anahtarı kaydı
• Apple belgesi: Authenticating a User Through a Web Service (Bir Kullanıcının Kimliğini Web Hizmeti Üzerinden Doğrulama)
• Google dokümanı: Geçiş anahtarlarıyla şifresiz giriş

Sonraki adım: Form otomatik doldurma özelliğiyle geçiş anahtarıyla oturum açma.