@capgo/capacitor-passkey 사용

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

브라우저 스타일의 API

@capgo/capacitor-passkey 웹에서 이미 사용하는 것과 같은 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();

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

runtime에서 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,
});

Capgo가 동기화 패치로 도와줍니다

동기화 bunx cap sync, 플러그인은 생성된 네이티브 호스트 프로젝트를 업데이트합니다.

iOS: 필요 시 Xcode 권한과 관련된 도메인 연관성 권한을 설정합니다.
Android: asset_statements Android 매니페스트에 사용되는 리소스와 메타데이터를 생성합니다.

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

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

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

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

다른 공개 메서드

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

await CapacitorPasskey.getConfiguration() 해당 플러그인은 __CAPGO_KEEP_0__라는 이름으로 __CAPGO_KEEP_1__를 반환합니다. origin, domains, autoShim__CAPGO_KEEP_1__는 __CAPGO_KEEP_2__와 __CAPGO_KEEP_3__를 포함합니다. platform.
await CapacitorPasskey.createCredential(...) __CAPGO_KEEP_1__는 __CAPGO_KEEP_2__와 __CAPGO_KEEP_3__를 포함합니다.
await CapacitorPasskey.getCredential(...) __CAPGO_KEEP_1__는 __CAPGO_KEEP_2__와 __CAPGO_KEEP_3__를 포함합니다.
await CapacitorPasskey.isSupported() __CAPGO_KEEP_1__는 __CAPGO_KEEP_2__와 __CAPGO_KEEP_3__를 포함합니다.
await CapacitorPasskey.getPluginVersion() __CAPGO_KEEP_1__는 __CAPGO_KEEP_2__와 __CAPGO_KEEP_3__를 포함합니다.

__CAPGO_KEEP_1는 CAPGO_KEEP_2와 CAPGO_KEEP_3__를 포함합니다.

중요한 iOS 주의

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

중요한 Android 주의

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

Full Reference

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

Using @capgo/capacitor-passkey에서 계속 진행하십시오.

Cloudflare, Capacitor, GitHub, Capgo, API, SDK, CLI, npm, bun을 사용 중이라면 @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

Passkey에 대한 튜토리얼