소프트웨어 및 오픈 소스

Passkeys와 WebAuthn: 2026년 웹 개발자를 위한 실용적인 구현 가이드

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

패스키는 비밀번호 비밀을 저장하지 않고도 비밀번호 없는 로그인을 보장하지만, WebAuthn를 올바르게 구현하려면 브라우저 API를 호출하는 것만으로는 부족합니다. 패스키 등록, 인증, 서버 측 검증, 검색 가능한 자격 증명, 계정 복구가 보안 웹 애플리케이션에서 어떻게 함께 작동하는지 알아보세요.

2026년의 패스키와 WebAuthn: 웹 개발자를 위한 실용적 구현 가이드

비밀번호는 수십 년 동안 웹 애플리케이션의 기본 인증 메커니즘으로 사용되어 왔습니다. 하지만 보안 문제의 지속적인 원천이기도 합니다.

사용자는 비밀번호를 재사용합니다. 공격자는 피싱을 통해 비밀번호를 도용합니다. 서버는 비밀번호 해시를 보관하고, 재설정을 관리하며, 자격 증명 공격(c stuffing)을 방어해야 합니다.

패스키는 본질적으로 다른 접근 방식을 제시합니다.

사용자가 공유된 비밀을 기억할 필요가 없으며, 패스키는 공개 키 암호학과 사용자가 제어하는 인증기를 사용합니다. 브라우저는 WebAuthn을 통해 표준 인터페이스를 제공하고, 서버는 올바른 자격 증명이 사용되었는지 암호학적 증거를 검증합니다.

이 기술은 실험적이지 않습니다. WebAuthn은 현대 브라우저에서 널리 사용 가능하며, JSON 편의 메서드를 통해 통합이 greatly 단순화되었습니다.

하지만 안전한 패스키 로그인을 구축하려면 여전히 신중한 백엔드 설계가 필요합니다.

본 가이드는 아키텍처를 설명하고, 브라우저 측 흐름을 보여주며, 개발자가 놓치지 말아야 할 서버 측 검사점을 식별합니다.

1. 패스키란 정확히 무엇인가?

패스키는 공개 키 암호학을 통해 사용자를 인증하는 discoverable FIDO 자격 증명입니다.

등록 과정에서 인증기는 암호학적 키 쌍을 생성합니다.

개인 키는 인증기 또는 자격 증명 관리 생태계에 의해 보호됩니다. 웹 사이트는 해당 공개 키를 수신하고 사용자 계정과 연결합니다.

인증 과정에서 서버는 새로운 챌린지를 발급합니다. 인증기는 해당 챌린지와 관련된 데이터에 서명하고, 서버는 저장된 공개 키를 사용하여 서명을 검증합니다.

웹 사이트로 재사용 가능한 비밀번호는 전송되지 않습니다.

인증기로는 스마트폰, Windows Hello를 사용하는 PC, 하드웨어 보안 키, 또는 동기화된 패스키를 지원하는 자격 증명 관리자가 될 수 있습니다.

모든 패스키가 장치 간 동기화되는 것은 아닙니다. 일부 자격 증명은 장치 고정이며, 다른 것은 안전하게 백업하고 자격 증명 제공자를 통해 사용할 수 있습니다.

FIDO 사양은 자격 증명을 relying party의 도메인과 연결하여 피싱에 저항하도록 설계되었습니다. 생체 정보는 사용 시에 장치에서 로컬로 처리되고 웹 사이트로 전송되지 않습니다.

2. WebAuthn은 패스키 뒤에 있는 브라우저 API이다

WebAuthn은 웹 플랫폼 API로, 웹 사이트가 공개 키 자격 증명을 생성하고 사용할 수 있게 합니다.

두 가지 브라우저 메서드가 기반을 이룹니다:

navigator.credentials.create()
navigator.credentials.get()

첫 번째는 자격 증명을 생성합니다. 두 번째는 기존 자격 증명을 사용하여 인증을 요청합니다.

두 메서드 모두 publicKey 옵션과 함께 작동하며, 일반적으로 HTTPS와 같은 안전한 컨텍스트가 필요합니다.

중요한 점은 브라우저가 사용자가 인증되었는지를 결정하지 않는다는 것입니다. 브라우저는 백엔드가 검증해야 할 데이터를 반환합니다.

성공적인 브라우저 프롬프트는 로그인을 승인해야 한다는 증거가 아닙니다.

서버는 챌린지, 오리진, relying party 식별자, 암호학적 증거를 검증하는 책임을집니다.

3. 전체 아키텍처 이해하기

일반적인 구성에는 네 가지 구성 요소가 있습니다:

  • 웹 애플리케이션 프론트엔드, WebAuthn을 조용합니다.
  • 애플리케이션 백엔드, 챌린지를 생성하고 응답을 검증합니다.
  • 인증기 또는 패스키 제공자, 개인 키를 보호합니다.
  • 데이터베이스, 자격 증명 메타데이터와 공개 키를 저장합니다.

등록 흐름은 다음과 같습니다: 웹 애플리케이션 등록 옵션을 요청합니다; 백엔드는 챌린지와 사용자 데이터를 생성합니다; 브라우저와 인증기가 자격 증명과 키 쌍을 생성합니다; 그리고 백엔드는 결과를 검증하고 공개 키를 저장합니다.

서버는 브라우저에서 반환된 등록 데이터를 blindly 신용해서는 안 됩니다.

악의 클라이언트는 예상된 프론트엔드를 사용하지 않고 임의의 HTTP 요청을 제출할 수 있습니다.

따라서 검증은 서버에서 수행되어야 합니다.

4. 서버에서 등록 옵션 생성하기

WebAuthn을 호출하기 전에, 백엔드는 등록 챌린지와 옵션을 생성합니다.

대표적인 옵션 개체는 다음과 같습니다:

{
  "rp": {
    "name": "Example Application",
    "id": "example.com"
  },
  "user": {
    "id": "dXNlci0xMjM",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  },
  "attestation": "none",
  "timeout": 300000
}

이는 illustrative JSON이며, 완전한 프로덕션 응답은 아닙니다.

여러 필드가 중요합니다.

rp.id 은 relying party를 식별합니다. 예를 들어, example.com 은 해당 서브도메인에 사용할 수 있으며, WebAuthn의 RP ID 검증 규칙에 subject합니다.

user.id 은 JSON 전송을 위해 base64url로 인코딩된 안정적이고 불투명한 계정 식별자여야 합니다. 불필요한 개인 정보를 노출하지 않아야 합니다.

challenge 은 서버에서 암호학적으로 안전한 무작위 소스를 사용하여 생성되어야 합니다.

residentKey: "required" 은 패스키 경험에 필요한 discoverable 자격 증명을 요청합니다.

userVerification: "required" 은 로컬 사용자 검증(예: 장치 PIN 또는 생체 인증)을 요청합니다. 백엔드는 나중에 검증이 실제로 발생했는지 확인해야 합니다.

Google의 서버 측 등록 가이드는 이 필드들을 설명하며, 등록 데이터 생성 및 검증을 위해 유지 관리되는 WebAuthn 라이브러리 사용을 권장합니다.

5. JavaScript에서 패스키 생성하기

현대 브라우저는 유용한 메서드를 제공합니다:

PublicKeyCredential.parseCreationOptionsFromJSON()

이는 base64url로 인코딩된 이진 필드를 포함하는 JSON 표현을 WebAuthn이 기대하는 구조로 변환합니다.

이로 인해 각 필드에 대한 커스텀 base64url-to-ArrayBuffer 변환 로직을 작성할 필요가 없습니다.

간단한 브라우저 측 등록 함수는 다음과 같습니다:

async function registerPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/register/options',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            }
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start registration');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseCreationOptionsFromJSON(
            optionsJson
        );

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

    if (!credential) {
        throw new Error('No credential was created');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/register/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Registration verification failed');
    }

    return await verifyResponse.json();
}

csrfToken 변수는 애플리케이션 제공 anti-CSRF 토큰을 나타내며, 서버는 이를 검증해야 합니다. 예는 이미 안전하게 인증된 사용자와 연결된 页面라고 가정합니다.

credential.toJSON() 을는 반환된 자격 증명에 대한 JSON 친화적 표현을 제공하여 다른 레이어의 수동 이진 직렬화를 피합니다.

이 편의 기능은 현재 브라우저에서 사용 가능하며, 오래된 브라우저 버전을 지원하는 애플리케이션은 호환성 처리를 제공해야 합니다.

위 코드는 브라우저 측만이며, 완전한 인증 구현은 아닙니다.

6. 서버가 등록 시 검증해야 할 사항

브라우저가 새로운 자격 증명을 반환하면, 백엔드는 저장하기 전에 이를 검증해야 합니다.

최소한 검증 과정은 다음을 확립해야 합니다:

  1. 반환된 챌린지가 해당 등록 시도에 생성된 챌린지와 일치합니다.
  2. 챌린지가 최신이며尚未 사용되지 않았습니다.
  3. 보고된 오리진이 명시적으로 신뢰 가능한 애플리케이션 오리진과 일치합니다.
  4. 인증기 데이터가 예상된 RP ID와 일치합니다.
  5. 필요한 사용자 존재 및 사용자 검증 조건이 충족되었습니다.
  6. 자격 증명의 공개 키 및 식별자를 추출하고 검증할 수 있습니다.
  7. 등록이 올바른 인증된 계정과 연결되었습니다.

응용 정책에 따라 추가 검사(지원 알고리즘, 자격 증명 고유성, attestation 요구사항 등)를 포함할 수 있습니다.

성공적인 등록은 일반적으로 다음과 같은 필드를 저장합니다:

Field Purpose
credential_id 자격 증명을 식별
user_id 계정과 연결
public_key 향후 서명 검증
sign_count 인증기 카운터 데이터 추적
transports 선택적 인증기 전송 힌트
created_at 등록 타임스탬프
last_used_at 계정 관리 및 감사
backup_eligible / backup_state 선택적 백업 관련 메타데이터

정확한 데이터베이스 표현은 검증 라이브러리와 애플리케이션에 따라 다릅니다.

CBOR 구문 분석, attestation 검증, 암호학적 서명 검증을 직접 구현하지 마세요. 유지 관리가 필요한 전문 지식이 필요할 수 있습니다.

W3C 사양은 등록 및 인증 검증 절차를 정의합니다.

7. 기존 사용자 인증하기

인증은 유사한 구조를 따르지만, 새로운 키 쌍을 생성하지는 않습니다.

서버는 새로운 챌린지를 생성하고 브라우저에 인증 옵션을 보냅니다.

discoverable 패스키 로그인의 경우, 옵션은 다음과 같이 포함될 수 있습니다:

{
  "challenge": "NEW_SERVER_GENERATED_CHALLENGE",
  "rpId": "example.com",
  "userVerification": "required",
  "timeout": 300000
}

그러면 브라우저가 자격 증명을 요청할 수 있습니다:

async function authenticateWithPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/login/options',
        {
            credentials: 'same-origin'
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start authentication');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseRequestOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.get({
        publicKey
    });

    if (!credential) {
        throw new Error('Authentication was cancelled');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/login/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Authentication failed');
    }

    return await verifyResponse.json();
}

이 예는 백엔드가 발급된 챌린지를 단-lived, 익명 로그인 트랜젝션과 연결하고, 적절한 레이트 리미팅을 적용하며, 성공적인 검증 후에만 새로운 인증된 세션을 설정한다고 가정합니다.

서버는 자격 증명 ID를查找, 저장된 공개 키로 서명된 어설레이션을 검증, 챌린지와 오리진을 확인, 사용자 검증 정책을 적용해야 합니다.

그 후에만 사용자 세션을 설정해야 합니다.

parseRequestOptionsFromJSON() 은 현대 WebAuthn API의 일부이며, 일반적인 브라우저 측 통합에서 이진 필드를 수동으로 디코딩할 필요를 제거합니다.

8. 조건부 중개를 통해 기존 로그인 양식에 패스키 추가하기

WebAuthn의 가장 유용한 기능 중 하나는 조건부 중개(conditional mediation)입니다. 때로는 패스키 자동 채우기라고 불립니다.

즉각적인 별도의 패스키 대화 상자를 표시하는 대신, 브라우저는 사용자가 로그인 필드와 상호작용할 때 저장된 다른 자격 증명과 함께 사용 가능한 패스키를 제시할 수 있습니다.

HTML 입력은 다음과 같이 사용할 수 있습니다:

<input
    type="text"
    name="username"
    autocomplete="username webauthn"
>

응용 프로그램은 지원 여부를 확인할 수 있습니다:

const supported =
    await PublicKeyCredential.isConditionalMediationAvailable();

if (supported) {
    // Request authentication with mediation: 'conditional'.
}

navigator.credentials.get() 을 호출할 때, 응용 프로그램은 다음과 같이 사용합니다:

{
    publicKey,
    mediation: 'conditional'
}

discoverable 자격 증명 자동 채우기 위해서는 서버 옵션은 특정 자격 증명 ID 목록으로 요청을 제한하지 않아야 합니다.

조건부 중개는 비밀번호에서 점진적으로 마이그레이션하는 동안 특히 유용합니다. 사용자는 특정 계정에 패스키가 있는지를 기억할 필요가 없습니다.

브라우저는 친숙한 로그인 경험에서 적절한 옵션을 제시할 수 있습니다.

9. 왜 챌린지와 오리진 검증이 필수적인가?

패스키는 피싱 저항성(ac)을 가지고 있지만, 응용 프로그램이 인증 프로토COL을 무시할 수 있다는 것은 아닙니다.

Challenge는 재생 공격(replay attack)을 보호합니다.

예측 가능한 최신 챌린지가 없으면 공격자는 이전 세션의 인증 데이터를 재사용할 수 있습니다.

오리진 및 RP ID 검증은 자격 증명이 의도된 웹 사이트 맥락에서 사용되고 있음을 보장합니다.

예를 들어, example.com 에 대해 생성된 패스키는 examp1e.com 과 같은 모방 피싱 사이트에서 단순히 재사용할 수 없습니다.

브라우저와 인증기는 이 도메인 바인딩의 중요한 부분을 강제하며, 백엔드는 결과 증거를 독립적으로 검증합니다.

좋은 구현은 단-lived 챌린지를 사용하고, 각 챌린지를 한 번씩 소모하며, familiar-looking 호스트네임을 공유하는 임의의 오리점을 수용하지 않습니다.

MDN은 신뢰할 수 있는 환경에서 챌린지를 생성하고, 최대 10분 정도의 짧은 기간 후 무효화하라고 권장합니다.

10. 서명 카운터를 오해하지 마시오

WebAuthn 인증기는 서명 카운터를 포함할 수 있습니다.

역사적으로, 카운터는 클론된 인증기를 감지하는 데 도움이 되었습니다. 카운터가 예상치 못하게 증가하지 않으면 relying party는 위험 신호로 간주할 수 있습니다.

하지만 모든 인증기가 의미 있는 카운터를 유지하지는 않습니다.

일부 자격 증명은 항상 0으로 보고합니다. 동기화된 자격 증명은 여러 장치가 동일한 자격 증명의 복사본을 사용할 수 있으므로 카운터 해석을 복잡하게 만들 수 있습니다.

W3C 사양은 예상치 못한 카운터 동작을 클론 증명의 확정적인 증거가 아닌 가능한 신호로 처리합니다.

따라서 개발자는 카운터가 0이거나 변경되지 않은 모든 로그인을盲目 거부하지 않아야 합니다.

인증기 동작, WebAuthn 검증 라이브러리의 지침, 애플리케이션의 보안 정책에 따라 카운터를 사용하세요.

11. 계정 복구는 패스키 보안의 일부입니다

패스키 구현은 복구 전략이 없으면 불완전합니다.

사용자가 장치를 잃어버렸을 때 어떻게 될까요?

자신의 유일한 패스키를 删除했다면?

자격 증명 제공자를 변경했거나, 동기화된 자격 증명에 접근할 수 없게 된 경우?

신중한 설계는 사용자가 계정 설정에서 여러 패스키를 등록하고 관리할 수 있도록 합니다.

관리 인터페이스는 recognizable 자격 증명 이름, 생성 날짜, 사용 가능한 경우 최신 사용 정보를 표시해야 합니다.

사용자는 더 이상 신뢰하지 않는 자격 증명을 폐기할 수 있어야 합니다.

하지만 복구 메커니즘은 특히 주의를 기울여야 합니다.

공격자가 약한 이메일 복구 프로세스를 통해 패스키 인증을 우회할 수 있다면, 전체 계정은 그 복구 경로만큼만 안전합니다.

높은 위험 계정의 경우, 강화된 복구 검증, 복구 코드, 추가 등록 인증기, 민감한 계정 변경에 대한 알림 등을 고려하세요.

Google의 패스키 UX 가이드는 복구 방법을 설정하고, 적절한 경우 여러 패스키를 지원하라고 권장합니다.

12. 일반적인 구현 오류

다음과 같은 오류는 아니지만, 잠재적인 패스키 통합을 반복적으로 손상시킵니다.

브라우저 성공을 서버 인증으로 간주. 해결된 navigator.credentials.get() 프라미스는 서버 측 암호학적 검증을 대체하지 않습니다.

JavaScript에서 챌린지 생성. 챌린지는 신뢰할 수 있는 서버에서 생성되어야 하며, 해당 인증 트랜젝션에 바인딩되어야 합니다.

잘못된 RP ID 사용. 도메인 스코핑은 보안 기능이므로 장식적 설정이 아닙니다. 프로덕션, 스테이징, 로컬 개발 환경은 의도적인 구성이 필요합니다.

모든 패스키가 동기화된다고 가정. 장치 고정 자격 증명은 생태계의 중요한 부분입니다.

자격 증명 폐기 누락. 사용자는 분실하거나 위험에 놓인 인증기를 계정에서 제거할 수 있어야 합니다.

약한 폴백 생성. 피싱 저반성 로그인은 복구 경로가 쉽게 악용될 경우 많은 가치를 잃습니다.

오래된 브라우저 무시. 현대 JSON 편의 메서드는 복잡성을 줄이지만, 오래된 브라우저 요구사항이 있는 애플리케이션은 여전히 호환성 코드가 필요할 수 있습니다.

CSRF 및 세션 보호 누락. 등록 및 자격 증명 관리 작업은 민감한 계정 변경 사항입니다. 다른 고영향 계정 작업과 동일한 보호가 필요합니다.

불필요한 커스텀 암호학적 검증 작성. 유지 관리되는 WebAuthn 서버 라이브러리는 사양을 직접 구현하는 것보다 일반적으로 더 안전한 선택입니다.

13. 모든 웹 사이트가 즉시 비밀번호를 교체해야 할까?

반드시 아닙니다.

패스키는 사용성과 보안을 모두 개선할 수 있지만, 마이그레이션 전략이 중요합니다.

새로운 애플리케이션의 경우, 복구 흐름이 잘 설계되고 대상 플랫폼을 지원하는 경우 비밀번호 없는 등록은 합리적인 기본값이 될 수 있습니다.

수천 명의 사용자를 가진 기존 애플리케이션의 경우, 점진적 도입이 더 안전합니다.

먼저 인증된 사용자가 계정 설정에서 패스키를 등록할 수 있도록 합니다.

그 후 기존 인증 시스템과 함께 패스키 로그인을 추가합니다.

조건부 중개를 지원하는 곳에서 도입합니다.

등록 성공률, 인증 실패, 장치 호환성, 복구 요청을 측정합니다.

사용자 경험과 복구 메커니즘 충분히 성숙하면, 패스키를 기본 인증 방법으로 만들기를 고려하세요.

단계별 출시는 브라우저별 문제를 식별하기도 하며, 합법적인 사용자를 차단하지 않도록 해줍니다.

14. 프로덕션 준비 체크리스트

패스키를 프로덕션으로 활성화하기 전에, 다음 사항을 확인하세요:

  • 모든 WebAuthn 작업이 적절한 안전한 컨텍스트에서 실행됩니다.
  • RP ID 및 신뢰할 수 있는 오리진이 명시적으로 구성됩니다.
  • 챌린지는 암호학적으로 무작위이며, 단-lived 및 단일 사용입니다.
  • 등록은 적절한 계정 권한이 필요합니다.
  • 서버 측 검증이 WebAuthn 사양을 따릅니다.
  • 공개 키 및 자격 증명 식별자가 안전하게 저장됩니다.
  • 로그인은 성공적인 검증 후에만 세션을 설정합니다.
  • 사용자 검증 요구사항이 서버에서 강제됩니다.
  • 자격 증명 제거 및 계정 복구가 보호됩니다.
  • 각 계정에 여러 자격 증명이 적절한 경우 지원됩니다.
  • 인증 실패 및 보안 민감한 계정 변경이 모니터링됩니다.
  • 모바일, 데스크탑, 크로스 디바이스, 하드웨어 키 시나리오가 테스트됩니다.

이 검사들은 프론트엔드가 환상적인 생체 인증 로그인 프롬프트를 표시할 수 있는지만 확인하는 것보다 더 중요합니다.

결론: 패스키는 브라우저 기능이 아닌 인증 아키텍처이다

WebAuthn은 일반적인 웹 애플리케이션에서 공개 키 인증을 가능하게 합니다.

현대 브라우저 API는 이전에 패스키 통합을 귀찮게 만들던 직렬화 작업을 대거 제거했습니다.

하지만 브라우저는 시스템의 일부에 불과합니다.

실제 구현 작업은 챌린지 관리, 서버 측 검증, 자격 증명 저장, 도메인 구성, 계정 복구, 안전한 사용자 흐름에 있습니다.

PHP, JavaScript, Python 등 백엔드 환경에서 현대 애플리케이션을 개발하는 개발자들에게, 패스키는 전통적인 비밀번호에 대한 실용적 대안으로 점점 더 고려될 만한 값이 있습니다.

가장 좋은 시작점은 전체 인증 시스템을 밤새로 교체하는 것이 아니라, 하나의 완전하고 올바르게 검증된 등록 및 로그인 흐름을 구현하고, 이를 안전한 마이그레이션 전략으로 둘러싸는 것입니다.