@ clerk/ 电子
开始
办事员 是将认证和用户管理添加到您的 Electron 应用程序中的最简单方式.
[尖叫声]
@clerk/electron以β为单位。 API在1.0前可能会有变化.
软件包有这些切入点:
@clerk/electron运行在主进程.@clerk/electron/preload在预装入脚本中运行.@clerk/electron/react运行在渲染器过程中.@clerk/electron/storage是默认符号存储, 由electron-store。 。 。 .@clerk/electron/passkeys为渲染器进程增加密码(WebAuthn)支持.
// main.ts
import { app, BrowserWindow, net, protocol } from 'electron';
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
const clerk = createClerkBridge({
storage: storage(),
renderer: {
scheme: 'my-app',
host: 'renderer',
},
passkeys: true,
});
if (clerk.isPrimaryInstance) {
app.whenReady().then(() => {
protocol.handle('my-app', request => {
const url = new URL(request.url);
const file = url.pathname === '/' ? 'index.html' : url.pathname;
return net.fetch(pathToFileURL(join(__dirname, '../renderer', file)).toString());
});
const win = new BrowserWindow({
webPreferences: {
preload: join(__dirname, '../preload/index.js'),
},
});
win.loadURL('my-app://renderer/');
});
}
在Windows和Linux上,一个深层链接开始第二版的应用程序,所以回调只到达
通过Electron的单相锁运行过程. 当你配置一个渲染器方案时,
createClerkBridge 默认获取此锁定, 并退出转发后的二次进程
他们的命令行参数。 打电话之前 app.whenReady(),当
isPrimaryInstance 实值 false。 。 。 . app.quit() 是一个同步的,所以 whenReady 仍然可以开火在一个
进程正在关闭. cleanup() 释放锁,除非应用程序已经拥有
马可斯不需要锁 深层链接通过 open-url所以书记官没有锁
isPrimaryInstance 总是 true。 。 。 .
如果应用程序管理锁, 在创建桥前先获取并禁用办事员的锁 管理层:
const gotTheLock = app.requestSingleInstanceLock();
if (!gotTheLock) {
app.quit();
} else {
createClerkBridge({
storage: storage(),
renderer: { scheme: 'my-app', host: 'renderer' },
manageSingleInstanceLock: false,
});
}
Linux 软件包还必须在其中注册渲染器方案 .desktop 条目,以便浏览器
启动应用程序 :
Exec=/path/to/my-app %U
MimeType=x-scheme-handler/my-app;
单位 my-app://renderer/sign-in, (中文(简体) ), my-app 这是计谋, renderer 是宿主, my-app://renderer 是来源,而且 /sign-in 是路径。 如果您的渲染器使用基于路径的路由,则服务来自同一来源的每条路由,并按需要返回渲染器入口.
// preload.ts
import { exposeClerkBridge } from '@clerk/electron/preload';
exposeClerkBridge({ passkeys: true });
// renderer.tsx
import { ClerkProvider } from '@clerk/electron/react';
import { passkeys } from '@clerk/electron/passkeys';
<ClerkProvider
publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}
passkeys={passkeys}
>
{/* ... */}
</ClerkProvider>;
设置特定应用产品符号,例如: Acme Co/1.0.0,通过 userAgent 改为 createClerkBridge 在创建渲染器窗口之前。 办事员保留Electron的平台细节,例如: Macintosh 或者说 Windows。用户Profile的会话活动然后显示您的产品代号为应用程序名:
createClerkBridge({
storage: storage(),
renderer: { scheme: 'my-app', host: 'renderer' },
userAgent: 'Acme Co/1.0.0',
});
允许来源
将你的造型师的出处加进允许的出处 否则,书记官将拒绝同时载有两种材料的出纸器请求 Origin 还有一个 Authorization 标题有"既确定"奥里金",也禁止"认证"标题". 一旦有客户代号 渲染器就会发出两种信号.
curl -X PATCH https://api.clerk.com/v1/instance \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"allowed_origins": ["my-app://renderer", "http://localhost:5173"]}'
包含您的自定义方案来源, 并在开发过程中包含您的 dev 服务器来源 。 该命令取代了实例的全部列表, 因此包含实例已经允许的每个来源 。 要查看当前列表,请发送 GET 请求到同一终点.
内容安全政策
@clerk/electron 装入 Clerks 预建的 UI 在运行时从 Clerks 的 CDN 开始而不是捆绑它, 因此您的渲染器的内容安全政策必须允许 Clerk 的前端 API 主机 。 如果没有的话,UI脚本就无法加载,而Clark组件也永远不会渲染出.
替换 {fapi_host} 下面的你的例子 前端 API 主机,位于 办事员板 下级 API 密钥它包括: clerk. 部分(例如, clerk.your-app.com 生产中或 your-slug.clerk.accounts.dev (见E/CN.4/Sub.2/2000/L.31)。 不要使用账户门户 URL(your-slug.accounts.dev) (中文(简体) ). 主机阻止UI脚本装入.
default-src 'self';
script-src 'self' 'unsafe-inline' https://{fapi_host} https://challenges.cloudflare.com https://*.protect.clerk.com;
connect-src 'self' https://{fapi_host} https://*.protect.clerk.com:* https://clerk-telemetry.com;
img-src 'self' https://img.clerk.com data:;
style-src 'self' 'unsafe-inline';
worker-src 'self' blob:;
frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com;
form-action 'self';
[注] 这个政策涵盖入住,入住,和热载UI. 书记员计费(Stripe)和其他功能需要更多的出处. 见文员 CSP指南 完整名单.
要么用一个 <meta> 在您的渲染器 HTML 中标记 :
<meta
http-equiv="Content-Security-Policy"
content="default-src 'self'; script-src 'self' 'unsafe-inline' https://{fapi_host} https://challenges.cloudflare.com https://*.protect.clerk.com; connect-src 'self' https://{fapi_host} https://*.protect.clerk.com:* https://clerk-telemetry.com; img-src 'self' https://img.clerk.com data:; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:; frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com; form-action 'self';"
/>
或,作为 电子安全指南 建议:
// main.ts
import { app, session } from 'electron';
const fapiHost = 'clerk.your-app.com';
app.whenReady().then(() => {
session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
callback({
responseHeaders: {
...details.responseHeaders,
'Content-Security-Policy': [
[
"default-src 'self'",
`script-src 'self' 'unsafe-inline' https://${fapiHost} https://challenges.cloudflare.com https://*.protect.clerk.com`,
`connect-src 'self' https://${fapiHost} https://*.protect.clerk.com:* https://clerk-telemetry.com`,
"img-src 'self' https://img.clerk.com data:",
"style-src 'self' 'unsafe-inline'",
"worker-src 'self' blob:",
"frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com",
"form-action 'self'",
].join('; '),
],
},
});
});
});
[注] 当渲染器从维特等dev服务器上载时,HMR需要更宽松的规则. 添加
'unsafe-eval'改为script-src和您的 dev 服务器的来源connect-src(例如,ws://localhost:<port> http://localhost:<port>) (中文(简体) ). 许多应用软件在开发过程中跳过CSP,只应用于被包建的架构.
密码
密码以两种模式工作. 办事员为每个请求选择一个:
- 渲染器模式: 当窗口装入内容时
https://从一个匹配您的 RP( 依赖方) ID 的源头, 渲染器使用 Chromium 的内置 WebAuthn 。 OS或浏览器同步证书. Windows Hello工作时没有设置. 在macOS上触摸ID需要用42号或以后的电能app.configureWebAuthn。 。 。 . - 本地模式: 当窗口装入本地捆绑时, 例如
scheme://host, WebAuthn 的出处检查拒绝了请求. 书记员将仪式通过IPC传送到主要流程. 可选@clerk/electron-passkeys本地模块然后调用 OS WebAuthn APIs (MacOS上的认证服务),webauthn.dll)),在视窗上.
Passkey自动填充依赖于WebAuthn有条件的调解,只有渲染器可以提供. 在本地模式下,登录形式通过"使用密码"动作提供密码. 它从不自己打开密码提示器.
设置
本地模式需要可选本地模块 :
pnpm add @clerk/electron-passkeys
// main process
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';
createClerkBridge({ storage: storage(), passkeys: true });
// preload script
import { exposeClerkBridge } from '@clerk/electron/preload';
exposeClerkBridge({ passkeys: true });
// renderer process (React)
import { ClerkProvider } from '@clerk/electron/react';
import { passkeys } from '@clerk/electron/passkeys';
<ClerkProvider
publishableKey={publishableKey}
passkeys={passkeys}
>
{/* ... */}
</ClerkProvider>;
您的应用程序只在您通过密码时将密码捆绑并初始化 passkeys 道具 (英语). 如果你自己来管理书记员 而不是用 ClerkProvider把它接起来 clerk.load()数字 :
// renderer process (vanilla)
import { Clerk } from '@clerk/clerk-js';
import { createPasskeyProvider } from '@clerk/electron/passkeys';
const clerk = new Clerk(publishableKey);
createPasskeyProvider(clerk);
await clerk.load();
本地模式的 macOS 要求
就像iOS上的密码一样,macOS平台API需要验证您的应用程序和域名之间的关联:
- 在书记板,去 原生应用 页面,并确保启用本地 API。 你的电动软件需要它.
- 将 iOS 应用程序添加到 原生应用 在书记板上。 你需要你的应用程序的 App ID 前缀和 Bundle ID 。 一个Electron macOS应用程序使用与iOS应用程序相同的配置.
- 签名您的应用程序
com.apple.developer.associated-domains包含webcredentials:<rp-domain>。这是 限制 权利。 大楼必须嵌入一个提供配置,与相关域的能力相配合,用于捆绑的ID,而且应享权利还必须包括com.apple.application-identifier财务报告和审定财务报表com.apple.developer.team-identifier匹配配置图.
这些提示都针对相同的模糊"与域无关"错误:
- 用一个 苹果开发 身份证明(
mac.type: development电子制造器)和a macOS 应用开发 包括您的 Mac 的配置文件 。 同时在机器上安装配置文件( S)~/Library/Developer/Xcode/UserData/Provisioning Profiles/<UUID>.provisionprofile) (中文(简体) ). - 复制
.app捆绑在一起ditto。其他复制方法可以打破应用程序封条,而macOS忽略了签名失败的应用程序的权益codesign --verify --deep --strict。 。 。 . swcd在应用程序启动时注册域协会。 检查一下sudo swcutil show如果卡住了,就赶紧跑sudo swcutil reset并重新启动.- 优先使用默认(生产/CDN)关联路由.
?mode=developer与sudo swcutil developer-mode -e true也行,但常常是片状的.
Windows没有相应的要求. Linux没有本土模式,因此包括外置安全密钥在内的密码,只能在那里以渲染器模式工作.
支助
帮帮忙,来看我们 支持页面。 。 。 .
捐款
我们欢迎所有社区的贡献! 如果你想以任何方式作出贡献,请阅读 我们的捐款准则 财务报告和审定财务报表 行为守则。 。 。 .
警卫
@clerk/electron 遵循安全方面的良好做法,但不能保证100%的安全.
@clerk/electron 提供 "就这样" 没有 保证. 冒险使用.
欲了解更多信息并报告安全问题,请参见我们 安全记录。 。 。 .
许可证
本项目根据以下规定获得许可证: 麻省理工学院许可证。 。 。 .
见 自由主义 更多信息.