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

호스트 앱을 한번만 구성하세요

__CAPGO_KEEP_1__ 앱에 플러그인 구성 추가 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 HTTPS 주소 capacitor.config.*.

origin: primary HTTPS 의존 주소로 shim 및 직접 API
domains: 추가 의존 주소로 native config 에 patch 하기
autoShim: 기본값 true native config 에서 제어하는 자동 구성 hook cap sync 설정 변경 후 다시 sync 를 실행하세요:

설치 중에 shim 을 설치하세요

bunx cap sync

standard package entrypoint 에서 플러그인을 임포트한 후 앱 부트스트랩 중에 shim 을 설치하세요:

그 후에, 브라우저 스타일의 passkey __CAPGO_KEEP_0__ 는 여전히 그대로 유지될 수 있습니다.

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

await CapacitorPasskey.autoShimWebAuthn();

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

WebAuthn 흐름을 유지하세요

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

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

protectedTokens

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

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

다른 공개 메서드

공개 플러그인 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가 구성된 경우 웹 사이트와 동일한 의존성 제공자와 패스 키를 공유할 수 있지만 네이티브 진술 기원은 브라우저 기원과 동일하지 않습니다. 백엔드가 엄격하게 clientDataJSON.originFull Reference

__CAPGO_KEEP_0__

https://GitHub.com/Cap-go/__CAPGO_KEEP_1__-passkey/ https://github.com/Cap-go/capacitor-passkey/
__CAPGO_KEEP_0__ 앱을 구동하기 위해

Passkey

Passkey에 대한 튜토리얼