가이드
Capacitor에서 Passkey를 사용하는 방법
@capgo/capacitor-passkey 사용하기
플러그인이 네이티브 passkey 호출과 네이티브 호스트 패칭을 처리하는 동안, Capacitor 앱에서 브라우저 방식의 WebAuthn code를 유지하세요.
브라우저 방식의 API
@capgo/capacitor-passkey 웹에서 사용하던 WebAuthn 흐름을 그대로 유지합니다:
await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });
네이티브 빌드에서는 이 플러그인이 shim을 설치하고 navigator.credentials.create() 및 navigator.credentials.get()요청을 iOS 및 Android passkey API로 전달한 뒤, 브라우저와 유사한 credential 객체를 앱에 반환합니다.
네이티브 프로젝트 설치 및 동기화
bun add @capgo/capacitor-passkey
bunx cap sync
호스트 앱은 한 번만 설정
플러그인 설정을 다음 위치에 추가: capacitor.config.ts 또는 capacitor.config.json:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'app.capgo.passkey.example',
appName: 'My App',
webDir: 'dist',
plugins: {
CapacitorPasskey: {
origin: 'https://signin.example.com',
autoShim: true,
domains: ['signin.example.com'],
},
},
};
export default config;
플러그인 설정의 역할
설정은 다음에서 읽습니다 plugins.CapacitorPasskey 에서 capacitor.config.*.
origin: shim 및 직접 API 호출에 사용되는 기본 HTTPS relying-party origindomains: 동기화 시 native config에 패치할 추가 relying-party hostnameautoShim: 기본값은true그리고 native 제어cap sync자동 구성 hook
설정 변경 후 다시 동기화 실행:
bunx cap sync
부트스트랩 시 shim 설치
플러그인을 표준 패키지 엔트리포인트에서 가져온 후, 앱 부팅 시 shim을 설치하세요:
import { CapacitorPasskey } from '@capgo/capacitor-passkey';
await CapacitorPasskey.autoShimWebAuthn();
이후 기존 브라우저 스타일 passkey code는 그대로 유지할 수 있습니다.
shim을 강제하거나 런타임에 설정된 origin을 오버라이드해야 하는 경우, 다음을 호출하세요:
import { CapacitorPasskey } from '@capgo/capacitor-passkey';
CapacitorPasskey.shimWebAuthn({
origin: 'https://signin.example.com',
});
기존 WebAuthn 흐름 유지
const credential = await navigator.credentials.create({
publicKey: registrationOptions,
});
const assertion = await navigator.credentials.get({
publicKey: requestOptions,
});
동기화 패치가 대신 처리하는 것
동안 bunx cap sync, 플러그인은 생성된 네이티브 호스트 프로젝트를 업데이트합니다:
- iOS: 필요 시 associated domains entitlements 및 Xcode entitlements 연결
- Android:
asset_statements메타데이터와 manifest에서 사용하는 생성된 리소스
네이티브 설정에는 여전히 웹사이트 신뢰 파일이 필요합니다
플러그인은 앱 측 작업을 줄여주지만, passkey는 여전히 relying-party 도메인의 웹사이트 신뢰 파일에 의존합니다. 다음을 호스팅해야 합니다:
https://your-domain/.well-known/apple-app-site-associationhttps://your-domain/.well-known/assetlinks.json
플러그인은 sync 중에 생성된 네이티브 프로젝트를 패치할 수 있지만, 웹사이트 신뢰 파일을 대신 생성하거나 호스팅할 수는 없습니다.
기타 공개 메서드
공개 플러그인 API 은 또한 다음에 정의된 직접 헬퍼를 노출합니다 src/definitions.ts:
await CapacitorPasskey.getConfiguration()는 해결된origin,domains,autoShim, 그리고 현재platform.await CapacitorPasskey.createCredential(...)JSON-safe WebAuthn 페이로드에서 passkey를 등록합니다.await CapacitorPasskey.getCredential(...)JSON-safe WebAuthn 페이로드의 기존 패스키로 인증합니다.await CapacitorPasskey.isSupported()현재 런타임이 패스키를 지원하는지 보고합니다.await CapacitorPasskey.getPluginVersion()현재 네이티브 구현 버전 마커를 반환합니다.
플랫폼 가이드
iOS 중요 참고 사항
iOS 17.4 이상에서 플러그인은 브라우저 방식의 client-data API를 사용하므로 설정된 HTTPS origin이 반영됩니다. clientDataJSON.
Android 중요 주의 사항
Digital Asset Links가 설정되어 있으면 Android Credential Manager가 웹사이트와 동일한 relying party 및 패스키를 공유할 수 있지만, 네이티브 assertion origin은 브라우저 origin과 동일하지 않습니다. 백엔드가 엄격하게 검증하는 경우 clientDataJSON.origin, 웹사이트 origin뿐만 아니라 Android 앱 origin도 허용하는지 확인하세요.
전체 레퍼런스
- GitHub: https://github.com/Cap-go/capacitor-passkey/
- 문서: /docs/plugins/passkey/
@capgo/capacitor-passkey 사용하기에서 계속하기
사용 중이라면 @capgo/capacitor-passkey 사용하기 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 시작하기 Getting Started의 구현 상세 내용은 @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증의 구현 세부 사항에 대해서는