Passkey 플러그인 @capgo/capacitor 사용

브라우저 스타일의 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: native 구성에 동기화하는 동안 추가 Relying-Party 호스트 이름
autoShim: 기본값 true native 구성 cap sync 자동 구성 Hook

설정 변경 후 다시 동기화 하십시오:

bunx cap sync

설치 중에 shim을 설치하십시오

standard package entrypoint에서 플러그인을 임포트한 후 앱 부트스트랩 중에 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

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

다른 공개 메서드

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

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

플랫폼 가이드

iOS 중요 참고사항

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

Android 중요 주의사항

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

전체 참조

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

Using @capgo/capacitor-passkey

iOS 17.4 이상 버전에서 플러그인은 브라우저 스타일의 client-data __CAPGO_KEEP_0__을 사용하여 구성된 HTTPS 원본이 반영됩니다. Using @capgo/capacitor-passkey 인증 및 계정 흐름을 계획하고 @__CAPGO_KEEP_0__-passkey과 연결 @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, 시작하기 시작하기의 구현 세부 정보 @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, and 2단계 인증 2단계 인증의 구현 세부 정보

Passkey

Passkey 튜토리얼