패스키 방향

웹 기능: 웹 인증

이 가이드에서는 최신 웹 애플리케이션에서 프레임워크에 구애받지 않는 안전한 패스키 인증 및 사용자 인증 정보 관리를 구현하기 위한 밀도 높고 행동 지향적인 오리엔테이션을 제공합니다.

1. 패스키의 핵심 기본 요건

패스키는 Web Authentication API (WebAuthn)를 사용합니다. 이 API는 구현을 시도하기 전에 충족해야 하는 엄격한 교차 보안 제약 조건을 적용합니다.

  • 보안 컨텍스트: WebAuthn 메서드 (navigator.credentials.create 및 navigator.credentials.get)는 보안 컨텍스트 뒤에서 엄격하게 제어됩니다. 애플리케이션은 프로덕션 환경의 https:// 또는 로컬 개발 환경의 http://localhost에서 실행되어야 합니다(MUST).
  • 신뢰 당사자 (RP) ID: 모든 사용자 인증 정보는 RP ID (기본적으로 애플리케이션의 도메인 이름)에 연결됩니다. 서버 측 옵션에 전달된 RP ID는 현재 출처의 도메인 이름과 일치하거나 유효한 서픽스여야 합니다 (예: example.com는 login.example.com에 유효함). 일치하지 않으면 클라이언트 측에서 SecurityError 예외가 발생합니다.

2. AAGUID UX 주의사항

인증자 증명 전역 고유 식별자 (AAGUID)는 등록 증명 데이터에서 반환되는 128비트 식별자로, 인증자의 모델/제공업체 (예: Google 비밀번호 관리자, iCloud 키체인, 1Password)를 나타냅니다.

  • UX 힌트만: 신뢰 당사자는 UX 힌트(예: 사용자를 돕기 위해 관리 목록에 패스키 제공업체 이름과 아이콘을 렌더링)에만 AAGUID를 사용해야 합니다(MUST).
  • 보안 종속 항목 없음: 애플리케이션은 암호화 보안 또는 액세스 결정에 AAGUID를 사용하면 안 됩니다(MUST NOT). 플랫폼 패스키는 현재 AAGUID에 대한 암호화 증명을 제공하지 않으므로 사용자 에이전트가 이를 변경하거나 시뮬레이션할 수 있습니다.

3. 분리된 라이브러리 추천

백엔드 FIDO2/WebAuthn 옵션 생성 및 서명 확인의 경우 개발자는 암호화를 직접 구현하는 대신 언어별로 검증된 오픈소스 라이브러리를 사용해야 합니다(MUST).

  • JavaScript/TypeScript: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python: py_webauthn (github.com/duo-labs/py_webauthn)
  • Java: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET: FIDO2용 .NET 라이브러리 (github.com/abergs/fido2-net-lib)
  • Go: WebAuthn Go 라이브러리 (github.com/go-webauthn/webauthn)
  • Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP: WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. 사용 사례 참조 매트릭스

아래에서 일치하는 사용 사례를 확인하고 전체 구현 가이드를 가져옵니다. 모든 사용 사례에는 사용 사례별 가이드에만 문서화된 중요한 API (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, 조건부 조정, AAGUID 처리 등)가 있습니다. 이 검색 단계를 건너뛰지 말고 클라이언트에서 서드 파티 라이브러리 래퍼 (예: SimpleWebAuthn의 startAuthentication/startRegistration)를 대체하지 마세요. 네이티브 WebAuthn 브라우저 API를 직접 호출하세요. 섹션 3의 라이브러리 권장사항은 서버 측 (백엔드 FIDO2 인증)에만 적용됩니다.

구체적인 패스키 및 WebAuthn 구현 세부정보는 다음 가이드에 매핑됩니다.