@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: Capgo shim과 직접 API
domains: native config에 동기화하는 동안 추가로 패치할 Relying-Party 호스트 이름
autoShim: 기본값 true native config cap sync 자동 구성 Hook

설정 변경 후 다시 동기화 하세요:

bunx cap sync

설치 중에 shim을 설치하세요

플러그인을 표준 패키지 진입점에서 import한 후 앱 부트스트랩 중에 shim을 설치하세요

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

await CapacitorPasskey.autoShimWebAuthn();

그 후에, 기존 브라우저 스타일의 패스키 code는 여전히 그대로 유지할 수 있습니다.

런타임에서 shim을 강제하거나 구성된 원본을 오버라이드하려면 다음을 호출하세요:

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: 필요할 때 Xcode 권한과 관련된 도메인 권한을 설정합니다.
Android: asset_statements 메타데이터 및 생성된 리소스 사용하는 매니페스트

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

플러그인은 앱 쪽 작업을 줄이지만 패스키는 여전히 웹사이트 신뢰 파일에 의존합니다. 따라서 신뢰할 수 있는 파티 도메인에 대한 웹사이트 신뢰 파일을 호스팅해야 합니다.

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

플러그인은 동기화 중에 생성된 네이티브 프로젝트를 패치할 수 있지만 패스키를 생성하거나 호스팅할 수는 없습니다.

다른 공개 메서드

Capacitor 플러그인 API도 API에서 정의된 직접 도우미를 공개합니다. src/definitions.ts:

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

플랫폼 가이드

중요한 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_KEEP_0__/__CAPGO_KEEP_1__-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

Passkey

Capgo npm 보기