Using @capgo/capacitor-passkey

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

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로 요청을 전달하고 브라우저와 같은 자격 증명 객체를 앱에 반환합니다.

native 프로젝트를 설치하고 동기화하세요

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
domainsshim과 직접 __CAPGO_KEEP_0__에 사용되는 기본 HTTPS 의존성 원본
autoShim: true 동기화 중에 native 설정에 패치할 추가 의존성 호스트 이름 cap sync .: 기본값입니다. native 설정에 영향을 주며 호스트 앱의 자동 구성 Hook을 제어합니다.

Run sync again after changing the config:

bunx cap sync

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

Import the plugin from the standard package entrypoint, then install the shim during app bootstrap:

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

await CapacitorPasskey.autoShimWebAuthn();

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

만약 shim을 강제로 호출하거나 runtime에서 구성된 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,
});

Capgo가 동기화 패치하는 것들

설치 중 bunx cap sync, plugin은 생성된 네이티브 호스트 프로젝트를 업데이트합니다:

iOS: 필요할 때 associated domains 권한과 Xcode 권한을 연결합니다
Android: asset_statements manifest에 사용되는 메타데이터와 생성된 리소스

자연스러운 설정은 웹사이트의 신뢰 파일이 필요합니다

플러그인은 앱 측의 작업을 줄이지만, 의존하는 파티 도메인에 대한 웹사이트의 신뢰 파일에依종속합니다. 여전히 다음을 호스팅해야합니다:

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

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

다른 공개 메서드

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

await CapacitorPasskey.getConfiguration() 해당하는 것을 반환합니다 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가 구성된 경우 웹사이트와 동일한 Relying Party와 Passkey를 공유할 수 있지만, 네이티브 어설션 원본은 브라우저 원본과 동일하지 않습니다. 백엔드가 엄격하게 원본을 검증하는 경우 clientDataJSON.origin백엔드가 Android 앱 원본을 포함하여 웹사이트 원본과 함께 수락하도록 하십시오.

전체 참조

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

Passkey

Passkey에 대한 __CAPGO_KEEP_0__