Passkey

Using @capgo/capacitor-passkey

브라우저 스타일의 WebAuthn code을 Capacitor 앱에 유지하고 플러그인은 네이티브 패스키 호출 및 네이티브 호스트 패칭을 처리합니다.

브라우저 스타일의 API

@capgo/capacitor-passkey __CAPGO_KEEP_0__은 웹에서 이미 사용하는 것과 같은 WebAuthn 흐름을 유지합니다:

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

네이티브 빌드에서 플러그인은 navigator.credentials.create() 그리고 navigator.credentials.get(), iOS 및 Android 패스키 API로 요청을 전달하고 브라우저와 같은 자격 증명 객체를 앱에 반환합니다.

네이티브 프로젝트 설치 및 동기화

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: primary HTTPS relying-party origin used by the shim and direct API
• domains기본 HTTPS 의존성 제공자 원본을 shim 및 직접 __CAPGO_KEEP_0__
• autoShim: true native config 에서 sync 중에 패치할 추가 의존성 제공자 호스트 이름 cap sync :

기본값

bunx cap sync

native config

자동 구성 hook

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

await CapacitorPasskey.autoShimWebAuthn();

After that, your existing browser-style passkey code can stay the same.

If you need to force the shim or override the configured origin at runtime, call:

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

CapacitorPasskey.shimWebAuthn({
  origin: 'https://signin.example.com',
});

Keep your normal WebAuthn flow

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

const assertion = await navigator.credentials.get({
  publicKey: requestOptions,
});

What sync patches for you

During __CAPGO_KEEP_0__, the plugin updates the generated native host projects: bunx cap synciOS: associated domains entitlements and Xcode entitlements wiring when needed

• Android:
• metadata and the generated resource used by the manifest asset_statements Native setup still needs website trust files

The plugin reduces app-side work, but passkeys still depend on the website trust files for your relying-party domain. You still need to host:

The plugin can patch the generated native projects during sync, but it cannot create or host those website trust files for you.

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

__CAPGO_KEEP_0__

다른 공개 메서드

공개 플러그인 API 또한 WebAuthn payload에서 정의된 직접 도우미를 노출합니다. src/definitions.ts:

• await CapacitorPasskey.getConfiguration() __CAPGO_KEEP_0__이 반환하는 해결된 origin, domains, autoShim, 현재 platform.
• await CapacitorPasskey.createCredential(...) JSON-안전한 WebAuthn payload에서 등록된 패스 키를 반환합니다.
• await CapacitorPasskey.getCredential(...) 기존 패스 키로 JSON-안전한 WebAuthn payload와 인증합니다.
• await CapacitorPasskey.isSupported() 현재 런타임이 패스 키를 지원하는지 여부를 보고합니다.
• await CapacitorPasskey.getPluginVersion() 현재 네이티브 구현 버전 마커를 반환합니다.

플랫폼 가이드

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

중요한 iOS 주의

iOS 17.4 이상 버전에서 플러그인은 브라우저 스타일의 client-data API을 사용하여 구성된 HTTPS 원본이 반영됩니다. clientDataJSON.

중요한 Android 주의

Android Credential Manager는 Digital Asset Links가 구성된 경우 웹사이트와 동일한 의존성 파트너와 패스키를 공유할 수 있지만, 네이티브 어설션 원본은 브라우저 원본과 동일하지 않습니다. 백엔드가 엄격하게 유효성을 검사하는 경우 clientDataJSON.origin백엔드가 엄격하게 유효성을 검사하는 경우, Android 앱 원본을 포함하여 웹사이트 원본과 함께 유효성을 검사하도록 백엔드가 허용하는지 확인하십시오.

전체 참조

• GitHub: https://github.com/Cap-go/capacitor-passkey/
• 문서: /docs/plugins/passkey/

Using @capgo/capacitor-passkey

이미 사용 중이라면 @capgo/capacitor-passkey 인증 및 계정 흐름을 계획하고 연결하기 위해 사용하는 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-passkey @capgo/capacitor-passkey @capgo/capacitor-passkey Getting Started Getting Started @capgo/capacitor-social-login @capgo/capacitor-social-login @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric Two-factor authentication Two-factor authentication