백엔드 참고 사항

일반적인 WebAuthn ceremony는 여전히 백엔드가 담당합니다:

• 등록 및 인증용 challenge 생성
• attestation 및 assertion 응답 검증
• relying-party ID와 challenge 검증 강제
• 브라우저 flow와 동일한 방식으로 credential 및 counter 저장

변경되지 않는 사항

이 플러그인은 기존 WebAuthn code의 프론트엔드 구조를 그대로 유지하도록 설계되었습니다.

• 웹 환경에서는 실제 브라우저의 WebAuthn API로 전달합니다.
• 네이티브 Capacitor 환경에서는 네이티브 passkey API를 기반으로 브라우저와 유사한 credential 객체를 반환합니다.
• 백엔드에서는 기존과 동일한 challenge 및 verification pipeline을 그대로 사용할 수 있습니다.

Android에서 변경되는 사항

Android 네이티브 passkey는 브라우저의 신뢰 모델과 완전히 동일하지 않습니다.

• Digital Asset Links를 통해 Android가 웹사이트와 동일한 relying party 및 credential 생태계를 공유할 수 있습니다.
• 리터럴 clientDataJSON.origin 값은 웹사이트 origin과 다를 수 있습니다.
• 서버가 다음을 제외한 모든 것을 거부한다면 https://your-domain, Android 네이티브 검증은 passkey가 유효하더라도 실패할 수 있습니다.

권장되는 백엔드 규칙

Android 네이티브 passkey를 지원하는 경우, 동일한 relying party에 대해 예상되는 브라우저 origin과 Android 앱 origin을 모두 허용하세요.

이를 통해 다음을 구현할 수 있습니다:

• 웹사이트 브라우저 지원
• Capacitor 앱 내 네이티브 passkey 지원
• 동일한 relying-party 도메인에 대한 단일 passkey 생태계

직접적인 JSON-safe 호출이 필요한 경우

백엔드에서 이미 다음을 반환하는 경우 PublicKeyCredentialCreationOptionsJSON 및 PublicKeyCredentialRequestOptionsJSON브라우저 방식의 shim 대신 API 플러그인을 직접 사용할 수도 있습니다:

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

const registration = await CapacitorPasskey.createCredential({
  origin: 'https://signin.example.com',
  publicKey: registrationOptionsFromBackend,
});

const authentication = await CapacitorPasskey.getCredential({
  origin: 'https://signin.example.com',
  publicKey: requestOptionsFromBackend,
});

Backend Notes로 계속하기

사용 중이라면 백엔드 참고 사항 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-passkey 사용하기 ‘@capgo/capacitor-passkey 사용하기’의 네이티브 기능에 대해서는, @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증의 구현 세부 사항에 대해서는