패스키 Capacitor 플러그인

@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 origin
• domains: 동기화 시 native config에 패치할 추가 relying-party hostname
• autoShim: 기본값은 true 그리고 native 제어 cap sync 자동 구성 hook

설정을 변경한 후 다시 sync를 실행하세요:

bunx cap sync

부트스트랩 시 shim 설치

표준 패키지 엔트리포인트에서 플러그인을 import한 다음, 앱 부트스트랩 단계에서 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에서 사용하는 생성된 리소스

네이티브 설정에 여전히 웹사이트 신뢰 파일이 필요합니다

플러그인이 앱 측의 작업량은 줄여주지만, 패스키는 여전히 Relying Party 도메인에 대한 웹사이트 신뢰 파일에 의존합니다. 다음 항목을 직접 호스팅해야 합니다:

• https://your-domain/.well-known/apple-app-site-association
• https://your-domain/.well-known/assetlinks.json

플러그인이 sync 중에 생성된 네이티브 프로젝트를 패치할 수는 있지만, 웹사이트 신뢰 파일을 대신 생성하거나 호스팅할 수는 없습니다.

기타 공개 메서드

공개 플러그인 API은 다음에서 정의된 직접 헬퍼 메서드도 제공합니다: src/definitions.ts:

• await CapacitorPasskey.getConfiguration() 해결된 값을 반환합니다 origin, domains, autoShim, 현재 platform.
• await CapacitorPasskey.createCredential(...) JSON-safe WebAuthn 페이로드로부터 패스키를 등록합니다.
• await CapacitorPasskey.getCredential(...) JSON-safe WebAuthn 페이로드를 사용하여 기존 passkey로 인증합니다.
• await CapacitorPasskey.isSupported() 현재 런타임이 passkey를 지원하는지 여부를 보고합니다.
• await CapacitorPasskey.getPluginVersion() 현재 네이티브 구현 버전 마커를 반환합니다.

플랫폼 가이드

• 시작하기
• iOS 설정
• Android 설정
• 백엔드 노트

iOS 주의 사항

iOS 17.4 이상에서 플러그인은 브라우저 방식의 client-data API를 사용하므로 설정된 HTTPS origin이 반영됩니다. clientDataJSON.

Android 주의 사항

Digital Asset Links가 설정된 경우 Android Credential Manager는 웹사이트와 동일한 relying party 및 passkey를 공유할 수 있지만, 네이티브 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단계 인증의 구현 세부 사항에 대해서는