Passkey

Passkey는 WebAuthn 및 FIDO2 표준을 지원하는 웹 브라우저에서 암호화 키 쌍을 사용하는 안전한 비밀번호 없는 인증 방법입니다. 고유한 키 쌍으로 비밀번호를 대체합니다: 사용자의 기기에 저장되는 개인 키와 웹사이트와 공유되는 공개 키. 사용자는 생체 인식, PIN 또는 보안 키를 사용하여 로그인할 수 있으며, 기존 비밀번호 없이 피싱에 강한 강력한 인증을 제공합니다.

passkey 플러그인 구현은 SimpleWebAuthn을 기반으로 합니다.

설치

import { betterAuth } from "better-auth"
import { passkey } from "better-auth/plugins/passkey"

export const auth = betterAuth({
    plugins: [ 
        passkey(), 
    ], 
})

npx @better-auth/cli migrate

npx @better-auth/cli generate

import { createAuthClient } from "better-auth/client"
import { passkeyClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [ 
        passkeyClient() 
    ] 
})

사용법

Passkey 추가/등록

passkey를 추가하거나 등록하려면 사용자가 인증되었는지 확인한 다음 클라이언트에서 제공하는 passkey.addPasskey 함수를 호출합니다.

const { data, error } = await authClient.passkey.addPasskey({    name: "example-passkey-name",    authenticatorAttachment: "cross-platform",});

const data = await auth.api.addPasskey({    body: {        name: "example-passkey-name",        authenticatorAttachment: "cross-platform",    },});

Passkey로 로그인

passkey로 로그인하려면 signIn.passkey 메서드를 사용할 수 있습니다. 이렇게 하면 사용자에게 passkey로 로그인하라는 메시지가 표시됩니다.

const { data, error } = await authClient.signIn.passkey({    autoFill: true,});

const data = await auth.api.signInPasskey({    body: {        autoFill: true,    },});

사용 예제

// 인증 후 리디렉션 포함
await authClient.signIn.passkey({
    autoFill: true,
    fetchOptions: {
        onSuccess(context) {
            // 성공적인 인증 후 대시보드로 리디렉션
            window.location.href = "/dashboard";
        },
        onError(context) {
            // 인증 오류 처리
            console.error("인증 실패:", context.error.message);
        }
    }
});

Passkey 목록

passkey.listUserPasskeys를 호출하여 인증된 사용자의 모든 passkey를 나열할 수 있습니다:

const { data: passkeys, error } = await authClient.passkey.listUserPasskeys();

const passkeys = await auth.api.listPasskeys({    // This endpoint requires session cookies.    headers: await headers(),});

Passkey 삭제

passkey.delete를 호출하고 passkey ID를 제공하여 passkey를 삭제할 수 있습니다.

const { data, error } = await authClient.passkey.deletePasskey({    id: "some-passkey-id", // required});

const data = await auth.api.deletePasskey({    body: {        id: "some-passkey-id", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

Passkey 이름 업데이트

const { data, error } = await authClient.passkey.updatePasskey({    id: "passkey의 id", // required    name: "my-new-passkey-name", // required});

const data = await auth.api.updatePasskey({    body: {        id: "passkey의 id", // required        name: "my-new-passkey-name", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

조건부 UI

플러그인은 조건부 UI를 지원하므로 사용자가 이미 passkey를 등록한 경우 브라우저가 passkey를 자동으로 채울 수 있습니다.

조건부 UI가 작동하려면 두 가지 요구 사항이 있습니다:

<label for="name">사용자 이름:</label>
<input type="text" name="name" autocomplete="username webauthn">
<label for="password">비밀번호:</label>
<input type="password" name="password" autocomplete="current-password webauthn">

useEffect(() => {
   if (!PublicKeyCredential.isConditionalMediationAvailable ||
       !PublicKeyCredential.isConditionalMediationAvailable()) {
     return;
   }

  void authClient.signIn.passkey({ autoFill: true })
}, [])

브라우저에 따라 passkey를 자동으로 채우라는 프롬프트가 나타납니다. 사용자에게 여러 passkey가 있는 경우 사용하려는 passkey를 선택할 수 있습니다.

일부 브라우저는 자동 완성 프롬프트가 나타나기 전에 사용자가 먼저 입력 필드와 상호 작용해야 합니다.

디버깅

passkey 구현을 테스트하려면 에뮬레이트된 인증기를 사용할 수 있습니다. 이렇게 하면 물리적 기기를 소유하지 않고도 등록 및 로그인 프로세스를 테스트할 수 있습니다.

Schema

플러그인은 passkey 데이터를 저장하기 위해 데이터베이스에 새 테이블이 필요합니다.

테이블 이름: passkey

옵션

rpID: 웹사이트의 고유 식별자입니다. 로컬 개발의 경우 'localhost'도 괜찮습니다.

rpName: 웹사이트의 사람이 읽을 수 있는 제목입니다.

origin: 등록 및 인증이 발생해야 하는 URL입니다. http://localhost 및 http://localhost:PORT도 유효합니다. 후행 /를 포함하지 마세요.

authenticatorSelection: WebAuthn 인증기 선택 기준을 사용자 정의할 수 있습니다. 지정하지 않으면 residentKey 및 userVerification에 대해 preferred 설정으로 플랫폼 및 cross-platform 인증기가 모두 허용됩니다.

aaguid: (선택 사항) Authenticator Attestation GUID입니다. 이것은 passkey provider(기기 또는 인증기 유형)의 고유 식별자이며 등록 또는 인증 중에 사용된 passkey 기기 유형을 식별하는 데 사용할 수 있습니다.