비밀번호는 대부분의 애플리케이션에서 가장 많이 새어 나가는 부분입니다. 사용자는 재사용하고, 공격자는 피싱하고, 지원팀은 재설정에 시간을 씁니다. WebAuthn 표준 위에 구축된 패스키는 공유 비밀 대신 공개키 암호화를 사용해 Touch ID, Face ID, Windows Hello, 하드웨어 보안키처럼 빠르고 피싱에 강한 로그인을 제공합니다. 이 가이드는 패스키가 어떻게 동작하는지, 필요한 서버와 데이터 모델, 막다른 길을 피하는 UX 패턴, 사용자를 잠그지 않고 비밀번호에서 이전하는 방법, 그리고 현대적 웹 앱에서 안전하게 롤아웃하는 방법을 설명합니다.
패스키가 실제로 무엇인지
패스키는 탐색 가능한(discoverable) WebAuthn 자격 증명입니다. 등록 시 브라우저와 인증기(authenticator)가 귀하의 도메인(Relying Party ID)에 바인딩된 키 쌍을 만듭니다. 서버에는 공개키만 저장되고, 개인키는 사용자의 기기나 플랫폼 계정을 떠나지 않습니다. 로그인 시 서버는 챌린지를 보내고 인증기가 이를 서명하며, 서버는 저장된 공개키로 서명을 검증합니다. 자격 증명이 오리진에 묶여 있기 때문에 피싱 사이트에서는 사용할 수 없습니다.
구현해야 할 두 가지 절차
- 등록(자격 증명 생성): 사용자가 자신임을 증명(일반적으로 기존 세션, 인증된 이메일 또는 비밀번호)하면, 서버가 생성 챌린지를 반환하고, 인증기가 키 쌍을 만듭니다. 이후 자격 증명의 공개키와 메타데이터를 저장합니다.
- 인증(Assertion 가져오기): 사용자가 로그인을 시작하면 서버가 요청 챌린지를 반환하고, 인증기가 이를 서명합니다. 서버가 검증에 성공하면 세션 또는 토큰을 발급합니다.
알아두면 좋은 핵심 용어
- Relying Party(RP) ID: WebAuthn의 도메인 범위(예: example.com). 자격 증명은 여기에 바인딩됩니다.
- Credential ID: 특정 패스키를 나타내는 불투명 식별자. 서버에 저장하고 인증 시 반환합니다.
- Sign counter: 특정 복제(cloning) 시나리오를 탐지하기 위한 단조 증가 카운터(지원하는 인증기가 증가시킴).
- Transports: 인증기에 접근하는 방식(internal, usb, nfc, ble). 지원 및 휴리스틱에 유용합니다.
서버 아키텍처와 데이터 모델
패스키에서는 비밀을 저장하지 않습니다(공개키와 메타데이터만 저장). 하지만 흐름을 신뢰 가능하고 안전하게 만들기 위해 필요한 구성 요소가 몇 가지 있습니다.
제안 데이터 모델
{ users: { id, email, ... }, passkey_credentials: { id, // internal DB id user_id, // FK -> users credential_id, // base64url public_key, // base64url or binary cose_algorithm, // e.g., -7 (ES256), -257 (RS256) if present sign_count, // integer (last known) transports, // array/json ("internal", "usb", ...) attestation_format, // optional; store if you process attestation aaguid, // authenticator model id (optional but useful) created_at, last_used_at, revoked_at // nullable; supports credential revocation }, webauthn_challenges: { id, user_id, // nullable for usernameless flows type, // "registration" | "authentication" challenge, // random base64url created_at, expires_at, request_context // json: origin, rpId, options snapshot } }구현해야 할 엔드포인트
- POST /auth/passkeys/registration/start: 사용자가 등록할 수 있는지(예: 로그인 상태 또는 이메일 소유 검증) 확인하고 생성 챌린지를 발급하여 PublicKeyCredentialCreationOptions를 반환합니다.
- POST /auth/passkeys/registration/finish: 어테스테이션 응답을 검증하고 자격 증명을 저장한 뒤 성공을 반환합니다.
- POST /auth/passkeys/authentication/start: 요청 챌린지를 생성합니다. usernameless의 경우 allowCredentials를 비워 반환하고, username-first의 경우 사용자가 가진 Credential ID를 반환합니다.
- POST /auth/passkeys/authentication/finish: Assertion을 검증하고 sign_count와 last_used_at을 갱신한 뒤 세션 또는 토큰을 발급합니다.
서버 측에서는 잘 유지되는 WebAuthn 라이브러리를 사용해 저수준 암호화 실수를 피하고, 항상 origin, rpId, challenge를 검증하세요. 챌린지는 짧게(예: 5분) 저장하고, 성공한 Assertion 이후에는 사용됨(consumed)으로 표시해 재사용 위험을 줄이세요.
적절한 UX 선택: username-first, usernameless, 혹은 하이브리드
패스키는 비밀번호보다 부드러운 흐름을 가능하게 하지만, 대상 사용자와 배포 모델에 맞는 UX를 택했을 때만 그렇습니다. 의도적으로 선택하세요.
Username-first(이메일 입력 후 패스키)
- 먼저 이메일을 받습니다. 해당 계정에 패스키가 있으면 “패스키 사용”을 제공합니다.
- 장점: 익숙한 모델; 비밀번호와 SSO와 함께 병행하기 쉽습니다.
- 단점: “패스키로 계속” 같은 단일 단계보다 약간 느립니다.
Usernameless(탐색 가능한 자격 증명)
- 이메일을 묻기 전에 “패스키로 로그인”을 제공합니다. 인증기가 귀하의 RP에 해당하는 계정을 제안합니다.
- 장점: 매우 빠르고 단계가 적습니다. 개인 기기에서 탁월합니다.
- 단점: 일부 환경에서는 탐색 가능한 자격 증명을 비활성화합니다. 기기간 프롬프트는 플랫폼마다 다르고, 브라우저별 UI도 동일하지 않습니다.
스마트 폴백을 갖춘 하이브리드
- “패스키로 계속”과 “이메일로 계속”을 함께 보여줍니다. 이메일을 입력했고 해당 계정에 패스키가 있다면, 비밀번호나 매직 링크를 폴백으로 두되 패스키 흐름을 먼저 시도합니다.
- 항상 명확한 탈출구를 제공합니다: “다른 방법 시도”.
보안 속성과 주의할 함정
- 오리진 바인딩: 피싱 도메인에서는 자격 증명이 동작하지 않습니다. rpId가 정확하고 안정적인지 확인하세요.
- 재생 공격 방지: 서명된 챌린지가 재생을 막습니다. 재사용되었거나 만료된 챌린지는 절대 수락하지 마세요.
- Sign counter: 값을 업데이트하고 감소가 관측되면(복제 가능성) 조사하세요. 많은 인증기가 동기화되지만, 모두가 기기별 카운터를 유지하진 않습니다.
- 어테스테이션: 대부분의 컨슈머 앱에서는 선택 사항입니다. 필요한 경우가 아니라면 민감한 어테스테이션 정보를 거부하거나 제거해 프라이버시를 지키세요.
- 안전한 폴백: 주 인증 수단이 피싱에 강하더라도 폴백이 약하면 무력화됩니다. 강한 2차 요소, 짧은 TTL의 매직 링크, 백업 코드를 사용하세요.
멀티 테넌트와 커스텀 도메인 처리
WebAuthn 자격 증명은 보통 example.com 같은 등록 가능 도메인에 해당하는 RP ID에 바인딩됩니다. SaaS가 단일 공유 도메인(app.example.com)을 사용한다면 간단합니다. 커스텀 도메인(customer-a.com)을 쓰는 경우 app.example.com에서 등록한 패스키는 customer-a.com에서는 동작하지 않습니다.
- 도메인당 하나의 RP: 테넌트가 커스텀 도메인을 사용한다면, 해당 도메인을 rpId로 하여 등록과 인증을 수행하세요. 프런트엔드가 그 오리진에서 WebAuthn을 시작해야 합니다.
- 일관된 오리진: 한 도메인에서 등록하고 다른 도메인에서 인증하는 혼합 흐름을 피하세요. 자격 증명이 탐색 가능하지 않습니다.
- 화이트라벨링: BYOD(도메인) 지원 시, WebAuthn 범위를 해당 도메인으로 한정하고, 패스키가 도메인 간에 이동하지 않는다는 점을 명확히 알리세요.
등록: 더 안전한 시작 조건
공격자가 소유하지 않은 계정에 자격 증명을 바인딩하지 못하도록 하세요.
- 인증된 세션 또는 검증된 1회성 토큰(예: 매직 링크)을 패스키 등록 시작 전에 요구하세요.
- 사용자별 제한을 적용하세요(예: 최대 N개의 자격 증명). 분실·구형 패스키를 제거할 수 있는 관리 UI를 제공합니다.
- 메타데이터 저장: AAGUID와 transports 같은 정보를 지원 도구용으로 저장하되, 불필요한 수집은 피하세요.
인증: Assertion을 올바르게 검증하기
- 챌린지 조회: 저장된 챌린지를 가져와 응답과 일치하는지, 만료/사용 여부를 확인하세요.
- 오리진 확인: clientDataJSON의 origin이 기대한 오리진과 같은지 검증하세요. 다중 도메인 배포에서 특히 주의하세요.
- RP ID 해시: authenticatorData의 rpIdHash가 귀하의 rpId에 해당하는지 확인하세요.
- 서명 검증: 저장된 공개키와 알고리즘으로 결합된 데이터에 대한 서명을 검증하세요.
- 카운터 업데이트: 값이 있으면 새 sign counter를 저장하고, 회귀가 있으면 조사하세요.
복구와 폴백 방법
사용자가 기기나 플랫폼 계정에 계속 접근할 수 있다면 패스키는 훌륭합니다. 그래도 일부는 접근을 잃거나 호환되지 않는 기기를 사용할 수 있습니다. 다음을 제공하세요:
- 매직 링크: 만료가 짧고 1회용으로.
- 백업 코드: 오프라인 보관 가능. 사용 시 회전.
- 인증 앱(TOTP): 위험 모델상 필요하다면.
- 지원 채널: 계정 복구를 위한 검증 절차 포함.
비밀번호에서 패스키로 마이그레이션
빅뱅 방식은 필요 없습니다. 현재 방법과 나란히 패스키를 추가한 뒤, 사용자가 채택하도록 유도하세요.
실용적인 마이그레이션 단계
- 기존 사용자에게 추가 로그인 옵션으로 패스키를 제공하세요. 계정 보안에 “패스키 생성”을 제공합니다.
- 저스트 인 타임 프롬프트: 비밀번호 또는 SSO로 성공적으로 로그인한 직후 패스키 생성을 제안하세요. 클릭 한 번이면 되게 하세요.
- 재방문 시 패스키 우선: 사용자가 패스키를 보유했다면 “패스키로 계속”을 먼저 보여주세요. 다른 방법으로 가는 링크를 명확히 제공합니다.
- 고위험 작업을 점진적으로 제한: 결제 변경 등은 패스키 또는 강한 2차 요소로 세션 재인증을 요구하세요.
- 최종적으로 패스키를 기본값으로 설정하되, 최소 한 가지 안전한 폴백을 유지하세요.
혼란을 줄이는 UI 패턴
- 의도별 한 개의 버튼: “패스키 사용” vs “이메일 사용”. 사용자를 가두는 모달 스택을 피하세요.
- 무슨 일이 일어나는지 설명: “기기에서 프롬프트가 표시됩니다” 같은 한 줄이 오클릭을 줄입니다.
- 자격 증명 관리 UI: 등록된 각 패스키를 마지막 사용일과 함께 나열하고 제거 컨트롤을 제공합니다.
- 기기간 명확성: 시스템이 휴대폰을 요구하면 이유를 알려주세요. 일부 플랫폼은 근처 기기 사용을 허용합니다.
테스트 계획: 실패 모드를 지루하게 만들기
- 브라우저 커버리지: 주요 브라우저 최신 버전을 최소 두 플랫폼에서 테스트하세요.
- 시크릿/프라이빗 모드: 기대 동작이 다릅니다. 깔끔한 폴백을 보장하세요.
- 시간 불일치: 챌린지 만료는 클라이언트 시간에 의존하지 말아야 합니다.
- 동시 프롬프트: 두 챌린지를 시작하고 하나만 완료하면 나머지는 무효화되어야 합니다.
- 테넌트 도메인: 공유 도메인과 커스텀 도메인 모두에서 등록과 인증을 검증하세요.
- 애널리틱스: 시작, 성공, 폴백 비율을 추적해 문제 지점을 빠르게 찾아내세요.
운영 이슈: 가시성, 로그, 프라이버시
- 감사 추적: 등록 이벤트, Assertion 시도, 성공/실패 사유, 자격 증명 제거를 로깅하세요. 민감한 페이로드는 피하세요.
- PII 최소화: 필요 이상의 어테스테이션 데이터를 저장하지 마세요. 컨슈머 시나리오에서는 어테스테이션 제거를 고려하세요.
- 시크릿 관리: WebAuthn이 비밀번호 위험을 줄여도, 세션, CSRF 토큰 등 다른 시크릿은 여전히 관리해야 합니다.
- 피처 플래그: 테넌트/세그먼트별로 패스키를 게이팅해 안전하게 롤아웃하세요.
성능과 신뢰성 팁
- 단기 챌린지(예: 5분). 만료된 챌린지는 백그라운드 작업으로 정리하세요.
- 멱등한 완료: 등록 완료는 해당 사용자의 자격 증명이 이미 존재하면 성공을 반환해야 합니다.
- 엣지/세션 스토어: 엣지에서 동작한다면 챌린지를 빠른 복제형 KV에 저장하세요. 세션 ID로 태깅하세요.
- 백오프와 재시도: 절차 중 네트워크 끊김이 발생할 수 있습니다. UX는 “다시 시도”를 부드럽게 허용해야 합니다.
예시 플로우와 요청 형태
브라우저는 navigator.credentials.create()와 navigator.credentials.get()을 위한 특정 옵션 객체를 기대합니다. 서버는 그 옵션을 반환하며, 서명되어 있거나 최소한 저장된 챌린지와 추적 가능해야 합니다. 완료되면 클라이언트는 전체 응답을 서버로 보내어 검증합니다.
// Registration start response (simplified) { "publicKey": { "rp": { "name": "Acme", "id": "app.acme.com" }, "user": { "id": "base64url-user-id", "name": "user@example.com", "displayName": "User Name" }, "challenge": "base64url-challenge", "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }], "authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" }, "timeout": 60000, "attestation": "none" } }// Authentication start response (usernameless) { "publicKey": { "challenge": "base64url-challenge", "timeout": 60000, "rpId": "app.acme.com", "userVerification": "preferred", "allowCredentials": [] } }YeshBe로 구현하기
YeshBe는 AI로 소프트웨어를 만드는 플랫폼입니다. 원하는 것을 자연어로 설명하고 대화를 통해 정제할 수 있습니다. 필요한 엔드포인트, 데이터베이스 테이블, UI 플로우를 요청해 패스키를 구현하고, 보안·UX·애널리틱스를 반복 개선하세요. 아래는 실제로 만들 때 유용한 현실적 프롬프트입니다:
WebAuthn을 사용해 패스키 기반 인증을 만들어 주세요. 엔드포인트 추가:
POST /auth/passkeys/registration/start
POST /auth/passkeys/registration/finish
POST /auth/passkeys/authentication/start
POST /auth/passkeys/authentication/finish
당분간 relying party ID는 app.example.com을 사용합니다. 챌린지는 TTL 5분, 1회용으로 영속화하세요. 서버 측 검증은 표준 WebAuthn 라이브러리로 구현하세요.
passkey_credentials 테이블을 추가하고 필드는 다음과 같습니다: id, user_id, credential_id (base64url), public_key (base64url), cose_algorithm (int), sign_count (int), transports (json), aaguid (uuid, nullable), created_at, last_used_at, revoked_at. unique(user_id, credential_id)를 추가하세요.
Sign In 페이지에 버튼을 추가하세요: “패스키로 계속”과 “이메일로 계속”. 사용자가 이전에 패스키를 등록했다면 패스키 버튼을 먼저 보여주세요. 패스키 인증이 실패하면 메시지를 보여주고 이메일 + 매직 링크 폴백을 노출하세요. 계정에 비밀번호가 남아 있다면 비밀번호 사용 링크도 포함하세요.
계정 보안(Account Security)에 등록된 패스키 목록 섹션을 추가하세요. 가능하면 인증기 AAGUID로부터 유도한 표시 이름, 마지막 사용 일시, 제거(Remove) 버튼을 포함합니다. 기존 패스키를 제거하려면 최신 패스키 Assertion을 요구하세요.
패스키 흐름에 대한 애널리틱스를 추가하세요: registration_started, registration_success, registration_error_reason, auth_started, auth_success, auth_error_reason, fallback_to_magic_link. 7일 성공률과 상위 오류 사유를 보여주는 작은 대시보드를 제공합니다.
커스텀 도메인에 대한 테넌트 인식 기능을 추가하세요. 앱이 커스텀 도메인에서 제공될 때는 해당 도메인을 rpId로 사용합니다. 검증 시 오리진을 그에 맞게 확인하세요. 서로 다른 도메인 간에는 자격 증명이 사용 불가함을 확인하는 테스트를 포함하세요.
자주 발생하는 문제 해결
- create/get에서 “NotAllowedError”: 대개 사용자가 취소했거나 브라우저가 모달을 차단했습니다. 재시도 버튼을 제공하고 OS 프롬프트 확인 안내를 짧게 표시하세요.
- create에서 “InvalidStateError”: 해당 사용자에 이미 존재하는 자격 증명입니다. 성공으로 처리하거나 이름 변경을 제안하세요.
- 계정 선택기가 비어 있음: usernameless 흐름에서 탐색 가능한 자격 증명이 없을 수 있습니다. 이메일 먼저 경로를 제공하세요.
- 검증이 간헐적으로 실패: 저장한 챌린지를 정확히 되돌려주고, 올바른 오리진을 검증하며, 챌린지 1회용을 강제하는지 확인하세요.
최소 위험 롤아웃 전략
- 1단계: 내부 – 팀에만 활성화합니다. UX와 검증 이슈를 털어냅니다.
- 2단계: 옵트인 베타 – 피처 플래그로 게이팅합니다. 성공/실패 지표와 일반적인 폴백을 추적합니다.
- 3단계: 기본 표시 – 패스키가 있는 모든 사용자에게 “패스키로 계속”을 보여줍니다. 다른 방법도 눈에 띄게 유지합니다.
- 4단계: 정책 강화 – 민감한 작업에는 최근 패스키 Assertion 또는 강한 폴백을 요구합니다.
접근성과 포용성
- 키보드와 스크린 리더: 패스키 버튼은 포커스 가능하고 레이블이 있어야 합니다. 기기 프롬프트가 예상될 때 이를 표시하세요.
- 국제화: OS의 수동 프롬프트와 폴백 단계를 설명하는 카피를 현지화하세요.
- 막다른 길 금지: 항상 대체 방법을 제시하세요.
언제 어테스테이션을 요구할까
대부분의 소비자 대상 앱은 어테스테이션을 “none”으로 설정할 수 있습니다. 규제 환경처럼 특정 인증기에 대한 보증이 필요한 위험 모델인 경우에만 고려하세요. 처리 시 무엇을 왜 저장하는지 명확히 하세요.
정리
패스키는 일상 사용자에게 마찰을 늘리지 않으면서 비밀번호보다 빠르고 안전한 경로를 제공합니다. 핵심은 대상에 맞는 올바른 UX를 고르고, 견고한 서버 검증을 구현하며, 강력하고 명확히 안내된 폴백과 함께 점진적으로 롤아웃하는 것입니다. 먼저 로그인된 사용자에게 패스키를 추가하고 성공률을 추적한 뒤, 지표가 견고해지면 기본값으로 승격하세요.
YeshBe로 빌드한다면 원하는 엔드포인트, 데이터 모델, 플로우를 설명하고, 오류 처리·애널리틱스·멀티 테넌트 도메인 규칙을 AI와 함께 반복 개선할 수 있습니다. YeshBe는 소프트웨어를 만드는 플랫폼이므로, 아키텍처와 롤아웃 정책의 주도권은 유지하면서 구현 속도를 높일 수 있습니다.