@ capgo/ 电容器- passkey

在您的 Capacitor app 上添加密码而不重写您的网页登录: 插件可以shim navigator.credentials 并转发到iOS和Android上的本地密码API.

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/capacitor-passkey 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 加上@capgo/capor-passkey到我的Capacitor应用上,并把它接上。" 代理设置指南 • 妇女 主机磁共振

主要特点

• WebAuthn shim (英语)数字 : autoShimWebAuthn() 补丁 navigator.credentials.create 财务报告和审定财务报表 get 页:1 publicKey 请求.
• 直接 API数字 : createCredential() 财务报告和审定财务报表 getCredential() 从您的后端取 JSON 安全 WebAuthn 选项 .
• 本地 APIs: 认证 iOS和Android上的信用经理服务.
• 项目设置: 可以在 cap sync。 。 。 .
• 支持检查数字 : isSupported() 财务报告和审定财务报表 getConfiguration()。 。 。 .
• 平台: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 在网页上,插件使用浏览器WebAuthn API.

为什么这个插件

大多数 Capacitor apps 已经根据 :

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

此插件保持该形状为 Capacitor app :

• 它可以自动拍出 navigator.credentials.create/get 页:1 publicKey 请求.
• 它向iOS和Android上的本地密码API转发了呼叫.
• 它返回类似浏览器的认证对象,这样现有的代码就可以继续工作.
• 它可以在期间自动配置生成的iOS和Android主机项目 cap sync/update。 。 。 .
• 它也暴露出当您的后端已经返回了WebAuthn JSON时直接的JSON安全方法.

它没有做什么:

• 它不会给你带来后端挑战.
• 它不会消除您网站主机的需要 apple-app-site-association 财务报告和审定财务报表 assetlinks.json。 。 。 .
• 它不会让Android本地密码向服务器报告您网站的HTTPS来源. 在Android上,普通的应用程序使用该应用程序的出处(android:apk-key-hash:...) (中文(简体) ).

文档

这里有最完整的医生: https://capgo.app/docs/plugins/passkey/ (英语)

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的电容安装的版本 .

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-passkey` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

bun add @capgo/capacitor-passkey

浏览器- 类似设置

1. 配置插件一次进入 capacitor.config.ts 或者说 capacitor.config.json。 。 。 .
2. 从标准包入口导入插件 .
3. 打电话 CapacitorPasskey.autoShimWebAuthn() 一次在应用靴子.
4. 保留您已有的浏览器 navigator.credentials.create/get 代码不变.

1. 配置 capacitor.config.*

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;

配置密钥 :

• origin:该应用程序的主要HTTPS依赖方源.
• domains: 可选的额外依赖方主机名以本地方式在 cap sync/update。 。 。 .
• autoShim: 默认为 true。这只控制本地 cap sync/update 自动配置钩.

然后同步本地项目 :

bunx cap sync

期间 cap sync 编号 : cap update,插件自动补丁生成的主机应用程序 :

• iOS:更新应享权利文件和电线 CODE_SIGN_ENTITLEMENTS 如果需要的话.
• 安卓:注射剂 asset_statements 元数据并写入生成的字符串资源.

您不需要每次手动编辑主机项目文件 .

2. 在靴子上安装 " Shim "

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

await CapacitorPasskey.autoShimWebAuthn();

这个电话是 plugins.CapacitorPasskey 从本地 Capacitor 配置并明确安装 WebAuthn shim .

3. 保留现有的WebAuthn呼叫

之后,你的浏览器风格代码可以保持不变:

const registration = await navigator.credentials.create({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rp: {
      id: 'signin.example.com',
      name: 'Example Inc',
    },
    user: {
      id: crypto.getRandomValues(new Uint8Array(32)),
      name: '[email protected]',
      displayName: 'Ada Lovelace',
    },
    pubKeyCredParams: [
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 },
    ],
  },
});

const authentication = await navigator.credentials.get({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rpId: 'signin.example.com',
  },
});

钩子配置

插件钩子只补丁Capacitor生成的本地主机应用文件.

• 它不会碰你的应用程序源代码.
• 它不要求您永久手动编辑 Xcode 或 Android 项目文件 .
• 它不为您发布或生成网站关联文件.

直接 JSON 安全 API

如果后端已经返回 PublicKeyCredentialCreationOptionsJSON 或者说 PublicKeyCredentialRequestOptionsJSON,您可以直接调用插件 :

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

const registration = await CapacitorPasskey.createCredential({
  origin: 'https://signin.example.com',
  publicKey: registrationOptionsFromBackend,
});

const authentication = await CapacitorPasskey.getCredential({
  origin: 'https://signin.example.com',
  publicKey: requestOptionsFromBackend,
});

您仍然需要的网站文件

Passkey 只有在您的应用程序与您的网站相同的依赖方域关联时才会工作.

iOS 网站协会文件

主办单位a apple-app-site-association 在您的依赖方域上的文件 :

https://signin.example.com/.well-known/apple-app-site-association

示例

{
  "webcredentials": {
    "apps": [
      "ABCDE12345.app.capgo.passkey.example"
    ]
  }
}

注释:

• 文件必须使用 HTTP 服务 200。 。 。 .
• 不添加一个 .json 扩展名.
• 这个 webcredentials 域名必须匹配用于密码的依赖方id.
• 插件勾钩为您写入相关域名权限 cap sync/update。 。 。 .
• 在iOS 17.4和较新版本上,插件使用浏览器风格的客户端数据 API,所以配置的 HTTPS 来源在 clientDataJSON。 。 。 .

Android 网站协会文件

在 :

https://signin.example.com/.well-known/assetlinks.json

示例

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "app.capgo.passkey.example",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

• 使用与您的依赖方 ID 相同的域名 .
• 包含您需要的每个签名证书指纹, 包括测试时构建的调试 .
• 插件钩子写着 asset_statements 元数据及生成的字符串资源 cap sync/update。 。 。 .
• 您的网站仍然需要服务 assetlinks.json 文档.

后端注释

此插件保留了前端的WebAuthn API形状,但本地平台与浏览器后端合同并不相同.

• iOS 17.4+ 可以编码您为 shim 或直接 API 配置的 HTTPS 来源 .
• Android 证书管理器有 没有 动作像一个特权浏览器应用程序。 原生反应源与Android应用签名(android:apk-key-hash:...),而不是自动进入您的网站.
• 在配置了数字资产链接后,Android仍然可以使用与您网站相同的依赖方和密码. 不同的部分是字义 clientDataJSON.origin 绳子.
• 如果您的服务器严格验证 clientDataJSON.origin,允许Android应用软件与您的网络来源并行.
• 您的后端仍然需要正常的 WebAuthn 挑战生命周期和签名验证 .

网络行为

• 在网络上,插件转发到真实的浏览器WebAuthn API.
• 在原生Capacitor上,shim会返回由原生API支持的类似浏览器的认证对象.
• 打电话 CapacitorPasskey.autoShimWebAuthn() 在使用浏览器风格的WebAuthn调用之前,曾经在拖曳过程中.
• 有条件的调解目前回归 false。 。 。 .

示例应用

这个 example-app/ 文件夹显示自动shim流 :

• example-app/capacitor.config.json 配置插件.
• example-app/src/main.js 进口 CapacitorPasskey 从 @capgo/capacitor-passkey。 。 。 .
• example-app/src/main.js 电话 CapacitorPasskey.autoShimWebAuthn() 在靴子上.
• 实际的注册和认证仍然通过 navigator.credentials.create/get。 。 。 .

API 密码

• shimWebAuthn(...)
• getConfiguration()
• autoShimWebAuthn(...)
• createCredential(...)
• getCredential(...)
• isSupported()
• getPluginVersion()
• 接口
• 类型异名

电容Passkey插件.

使用 autoShimWebAuthn() 以保留 navigator.credentials.create/get 密码在一个电容软件内工作.

shimWebAuthn (...) (英语)

shimWebAuthn(options?: ShimWebAuthnOptions | undefined) => void

在本地插件上安装浏览器风格的 WebAuthn shim .

闪闪发光 navigator.credentials.create/get 页:1 publicKey 请求和返回类似浏览器的证书对象.

要手动覆盖自动装入配置时使用此功能 .

自: 1.0.0 (单位:千美元)

获取配置 ()

getConfiguration() => Promise<PasskeyRuntimeConfiguration>

从主机 Capacitor app 装入插件配置 .

这是 plugins.CapacitorPasskey 从 capacitor.config.*。 。 。 .

回返情况: Promise<PasskeyRuntimeConfiguration>

自: 1.1.0 国家

自动ShimWebAuthn(...)

autoShimWebAuthn(options?: ShimWebAuthnOptions | undefined) => Promise<PasskeyRuntimeConfiguration>

使用主机应用程序配置安装浏览器风格 shim .

这是保持现有浏览器WebAuthn代码工作的最简单方式: 配置插件在 capacitor.config.*,然后在 应用靴子.

回返情况: Promise<PasskeyRuntimeConfiguration>

自: 1.1.0 国家

创建证书(...)

createCredential(options: CreateCredentialOptions) => Promise<PasskeyRegistrationCredential>

从 JSON 安全 WebAuthn 请求注册密码 .

当您的后端已经返回时, 此方法很有用 PublicKeyCredentialCreationOptionsJSON 形式.

回返情况: Promise<PasskeyRegistrationCredential>

自: 1.0.0 (单位:千美元)

获得证书(...)

getCredential(options: GetCredentialOptions) => Promise<PasskeyAuthenticationCredential>

使用 JSON 安全 WebAuthn 请求中存在的密码认证 .

当您的后端已经返回时, 此方法很有用 PublicKeyCredentialRequestOptionsJSON 形式.

回返情况: Promise<PasskeyAuthenticationCredential>

自: 1.0.0 (单位:千美元)

已支持 ()

isSupported() => Promise<PasskeySupportResult>

报告当前运行时间是否有密码.

回返情况: Promise<PasskeySupportResult>

自: 1.0.0 (单位:千美元)

获取 PluginVersion ()

getPluginVersion() => Promise<PluginVersionResult>

返回当前平台执行版本标记 .

回返情况: Promise<PluginVersionResult>

自: 1.0.0 (单位:千美元)

接口

ShimWebAuthn 选项

安装浏览器风格 shim 时使用的选项 .

Passkey 运行时配置

从主机的 Capacitor 配置中装入了运行时间配置 .

这是返回的形状 getConfiguration()。 。 。 .

通行证

JSON安全注册证书被插件返回.

密码认证器

JSON安全证明反应有效载荷.

所有二进制字段都由 Base64url 编码.

创建证书选项

插件运输直接注册申请.

Passkey PublicKey 证书创建选项

JSON安全注册申请选项.

所有二进制字段必须被 Base64url 编码 .

密码存储方

JSON安全依赖党信息.

密码用户实体

JSON安全 WebAuthn 用户实体.

二进制标识符必须被 Base64url 编码 .

通行证

JSON - 安全证书参数条目.

密码键证书描述符

JSON安全地代表了公用钥匙证书的描述.

二进制标识符必须被 Base64url 编码 .

密码校正器选择

JSON安全验证员选择选项.

密码验证证书

JSON-安全认证证书被插件返回.

密码认证器

JSON安全断言反应有效载荷.

所有二进制字段都由 Base64url 编码.

获取证书选项

插件传输的直接认证请求 .

Passkey PublicKey 重要请求选项

JSON-安全认证请求选项.

所有二进制字段必须被 Base64url 编码 .

密码支持结果

当前运行时间的密码支持状态 .

插件变压器

插件版本有效载荷 .

类型异名

Passke 证书类型

支持的 WebAuthn 证书类型 .

'public-key'

密码校正

支持认证器附件值 .

'platform' | 'cross-platform'

记录

构造 T 类型 K 的一组属性类型

{ [P in K]: T; }

密码

支持居民关键偏好.

'discouraged' | 'preferred' | 'required'

密码用户验证

支持用户验证偏好.

'discouraged' | 'preferred' | 'required'

密码交换站

支持的证明偏好.

'none' | 'indirect' | 'direct' | 'enterprise'