FIDO2/WebAuthn passkey uç noktaları, kullanıcıların biyometrik veya güvenlik anahtarları kullanarak kayıt olmasına ve kimlik doğrulaması yapmasına olanak tanır.

Genel Bakış

Passkey akışları, her biri iki aşamalı bir challenge-response protokolü kullanır:

Kayıt Akışı

Kullanıcılar passkey kaydetmek için giriş yapmış olmalıdır (mevcut hesaplarına bağlanır).

Adım 1: Kaydı Başlat

POST /api/auth/passkey/register/begin

Başlıklar: Authorization: Bearer <accessToken>

Yanıt (200):

{
  "publicKey": {
    "challenge": "base64url-encoded-challenge",
    "rp": {
      "name": "Bedrud",
      "id": "meet.example.com"
    },
    "user": {
      "id": "base64url-encoded-user-id",
      "name": "user@example.com",
      "displayName": "John Doe"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "userVerification": "preferred"
    }
  }
}

Bunu tarayıcının WebAuthn API’sine iletin:

const credential = await navigator.credentials.create({
  publicKey: response.publicKey
});

Adım 2: Kaydı Tamamla

POST /api/auth/passkey/register/finish

Başlıklar: Authorization: Bearer <accessToken>

İstek Gövdesi: Tarayıcıdan gelen credential yanıtı, base64url ile kodlanmış:

{
  "id": "credential-id",
  "rawId": "base64url-raw-id",
  "response": {
    "attestationObject": "base64url-attestation",
    "clientDataJSON": "base64url-client-data"
  },
  "type": "public-key"
}

Yanıt (200):

{
  "message": "passkey registered"
}

Giriş Akışı

Adım 1: Girişi Başlat

POST /api/auth/passkey/login/begin

Kimlik doğrulaması gerekmez.

Yanıt (200):

{
  "publicKey": {
    "challenge": "base64url-encoded-challenge",
    "rpId": "meet.example.com",
    "userVerification": "preferred"
  }
}

Bunu tarayıcının WebAuthn API’sine iletin:

const assertion = await navigator.credentials.get({
  publicKey: response.publicKey
});

Adım 2: Girişi Tamamla

POST /api/auth/passkey/login/finish

İstek Gövdesi: Tarayıcıdan gelen assertion yanıtı:

{
  "id": "credential-id",
  "rawId": "base64url-raw-id",
  "response": {
    "authenticatorData": "base64url-auth-data",
    "clientDataJSON": "base64url-client-data",
    "signature": "base64url-signature"
  },
  "type": "public-key"
}

Yanıt (200):

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Güvenlik

Uygulama Detayları

• Backend: Saf Go WebAuthn doğrulaması için go-passkeys/go-passkeys kullanır
• Oturum Depolama: Challenge’lar Gorilla oturumlarında saklanır (gothic.Store üzerinden)
• Veritabanı: Passkey kimlik bilgileri Passkey modelinde saklanır (credential ID, açık anahtar, sayaç)
• Frontend (Web): src/lib/auth.ts içindeki base64url yardımcıları ile navigator.credentials API’si
• Android: Yerel passkey desteği için Credentials API
• iOS: Passkey desteği için ASAuthorizationController

Nasıl Test Edilir

1. Mevcut bir hesapla giriş yapın
2. Passkey kayıt düğmesine tıklayın (başlık/kontrol panelindeki parmak izi simgesi)
3. Biyometrik istemi tamamlayın
4. Çıkış yapın
5. Giriş sayfasında “Passkey ile Giriş Yap”a tıklayın
6. Kimlik doğrulaması için biyometrik istemi tamamlayın

Ayrıca bakınız

• Kimlik Doğrulama Akışı - passkey kayıt/giriş seremonilerinin açıklaması
• Kimlik Doğrulama API’si - tüm kimlik doğrulama uç noktaları