OpenBot 桌面端 Windows 代码签名实战:用 Azure Key Vault 与 GitHub OIDC 为 Tauri 应用接入 Authenticode
OpenBot 桌面端 Windows 代码签名实战:用 Azure Key Vault 与 GitHub OIDC 为 Tauri 应用接入 Authenticode
本文以仓库内的 Tauri 签名实践文档为骨架,讲清楚一件容易被混淆的事:在 OpenBot 的桌面发布链路里,哪一种签名由哪一把密钥、哪一个工具、哪一种访问权限完成。读完后你应该能独立完成三件事:把 signCommand 接到 Key Vault 里的不可导出证书、用 GitHub OIDC 免密换取 Key Vault 访问令牌、以及在发布前用可复核的证据证明 .exe 与 NSIS 安装包确实被正确签名并带时间戳。
一、先厘清边界:三种彼此独立的签名机制
组织的签名基础设施包含三个互不相干的机制。它们使用不同的密钥、不同的工具和不同的验证路径,一旦混为一谈,排查就会彻底跑偏:
| 机制 | 密钥 | 工具 | 适用范围 |
|---|---|---|---|
| NuGet 作者签名(author signature) | DigiCert 证书,CN=Tawkit, Inc.,私钥位于 Azure Key Vault(不可导出,RSA-HSM) |
NuGetKeyVaultSignTool |
仅 *.nupkg |
| Authenticode(本文主题) | 同一张 DigiCert 证书、同一个 Key Vault | AzureSignTool |
Windows PE 二进制:.exe、.dll、.msi(含 Tauri 构建产物) |
| 程序集强名称(strong-naming) | AGUI.snk |
MSBuild | .NET 程序集,与上述两种签名无关 |
| Tauri 更新包签名 | Tauri minisign 密钥对(不是 Key Vault 证书) | tauri signer |
tauri-plugin-updater 的更新清单 |
以下几条事实经常被写错,需要单独强调:
- nuget.org 在推送时会自动施加自己的仓库签名(repository signature)。作者签名的作用只是把包在画廊上标记为 "signed",它与 Authenticode 完全无关。
- 符号包(
*.snupkg)是有意不做作者签名的。 - 证书的签发链为 DigiCert Trusted G4 Code Signing RSA4096 SHA384 2021 CA1,属于 OV 验证而非 EV。正因为是 OV,Windows SmartScreen 的信誉是随着已签名版本的发布逐个累积的,而不是瞬间授予。全新应用出现"看起来像未签名"的警告属于预期现象,不是签名失败。
- 私钥永不离开 HSM。无论是 NuGet 签名还是 Authenticode 签名,本质都是在 Key Vault 内执行一次
keys/sign操作。不要尝试导出密钥,也不要生成.pfx。
原文档把 NuGet 通道(.github/workflows/publish-release.yml 的签名步骤与 sdks/dotnet/docs/signing.md 设计文档)作为参照实现,本次 Tauri 通道就是把同一套模式平移过来。
二、把签名接入 Tauri 构建
2.1 用 signCommand 覆盖默认的 signtool 调用
在 tauri.conf.json 中覆盖默认的 signtool.exe 调用。Tauri 会对每个二进制文件调用一次、对每个安装包再调用一次,并把 %1 替换为对应文件路径:
{
"bundle": {
"windows": {
"signCommand": "pwsh ./scripts/sign-tauri.ps1 %1"
}
}
}
OpenBot 仓库采用的是等价的对象写法,把命令与参数拆开,避免引号转义问题,见 desktop/src-tauri/tauri.windows-signing.conf.json:
{
"$schema": "https://schema.tauri.app/config/2",
"bundle": {
"targets": ["nsis"],
"windows": {
"signCommand": {
"cmd": "pwsh",
"args": ["-NoProfile", "-NonInteractive", "-File", "../scripts/sign-windows.ps1", "%1"]
}
}
}
}
不要配置遗留的 certificateThumbprint / digestAlgorithm / timestampUrl 字段——它们期望本地已安装证书且私钥在本地可访问,根本无法触达 Key Vault 里的 HSM。
一个容易踩的配置层级问题:signCommand 必须落在 bundle.windows 之下,而不是 v1 风格顶层的 windows 键。放错位置的表现是"配置看起来生效、二进制却没签名"。
2.2 编写包装脚本
包装脚本对应 NuGet 通道中 NuGetKeyVaultSignTool 那一步:同一个 Vault URL、同一个证书名、同样的摘要算法与时间戳权威。最小形态如下:
param([string]$File)
azuresigntool sign `
-fd sha256 `
-tr http://timestamp.digicert.com `
-td sha256 `
-kvu $env:AZURE_KEY_VAULT_URL `
-kvc $env:CODE_SIGNING_CERT_NAME `
-kva $env:AZURE_ACCESS_TOKEN `
$File
if ($LASTEXITCODE -ne 0) { throw "Signing failed for $File" }
仓库中的生产版本 desktop/scripts/sign-windows.ps1 在这个骨架上补了几层保护,值得逐条对照:
- 模式闸门前置:脚本第一件事是检查
$env:WINDOWS_SIGNING -ne 'keyvault'就抛错,保证任何未显式开启签名的构建都不可能意外动用发布者密钥。 - 配置缺失显式失败:
AZURE_KEY_VAULT_URL、CODE_SIGNING_CERT_NAME任一为空即抛错,而不是让 AzureSignTool 报一个含义模糊的参数错误。 - 输入存在性校验:签名目标不存在时立即终止,避免 Tauri 传入异常路径后静默"成功"。
- 工具可用性预检:
Get-Command az, AzureSignTool.exe -ErrorAction Stop把"工具没装"与"签名被拒"区分开。 - 每次调用都重新取令牌:注释写明原因——Tauri 可能在签名前编译很久,提前获取的令牌可能已过期。
- 令牌防泄漏:取到令牌后立刻
::add-mask::注册日志掩码,并在finally中Remove-Item Env:AZURE_ACCESS_TOKEN,无论成功失败都不残留。 - 附加描述:
-d OpenBot把产品名写进签名信息,便于验证与审计时辨认。
$env:AZURE_ACCESS_TOKEN = az account get-access-token --resource https://vault.azure.net --query accessToken --output tsv --only-show-errors
Write-Host "::add-mask::$env:AZURE_ACCESS_TOKEN"
& AzureSignTool.exe sign -fd sha256 -tr http://timestamp.digicert.com -td sha256 `
-kvu $env:AZURE_KEY_VAULT_URL -kvc $env:CODE_SIGNING_CERT_NAME `
-kva $env:AZURE_ACCESS_TOKEN -d OpenBot $file
注意 --resource 必须是 https://vault.azure.net(Key Vault 资源),不能是 Graph 或 ARM 管理端点。
2.3 两个工具的旗标映射
从 NuGet 通道迁移时,务必核对下表,保持语义完全一致:
| NuGetKeyVaultSignTool | AzureSignTool |
|---|---|
--file-digest sha256 |
-fd sha256 |
--timestamp-rfc3161 http://timestamp.digicert.com |
-tr http://timestamp.digicert.com |
--timestamp-digest sha256 |
-td sha256 |
--azure-key-vault-url |
-kvu |
--azure-key-vault-certificate |
-kvc |
--azure-key-vault-accesstoken |
-kva |
三、用 GitHub OIDC 串联工作流,不引入长期密钥
发布作业通过 GitHub OIDC 联合身份认证到 Azure,与 NuGet 通道一致。不要引入 client secret。
- uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_SIGNING_CLIENT_ID }} # federated to GH OIDC
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
allow-no-subscriptions: true
- run: dotnet tool install --global AzureSignTool
- run: |
$env:AZURE_ACCESS_TOKEN = (az account get-access-token `
--resource https://vault.azure.net --query accessToken -o tsv)
npm run tauri build
作业必须声明 permissions: id-token: write(配合 contents: read)。缺少它,GitHub 根本不会签发 OIDC 令牌——这是新工作流或新仓库首次运行登录失败最常见的原因,没有之一。
OpenBot 的 .github/workflows/desktop-signing.yml 在此基础上做了几处收紧,可作为生产参考:
sign作业单独声明permissions: contents: read与id-token: write,而只做回归的checks作业仅有contents: read,权限不扩散。- 登录前先校验五个环境变量齐全,并核对
git rev-parse HEAD与SIGNING_SOURCE_SHA一致,防止"批准的是 A 提交、签的是 B 提交"。 - 登录后先做一次只读冒烟:
az keyvault certificate show,先证明证书可读,再进入耗时构建。 - AzureSignTool 不使用
dotnet tool install,而是下载固定版本 7.0.1 并校验 SHA-256,未通过即中止;随后把目录写进GITHUB_PATH。
四、保留模式闸门(安全默认值)
沿用既有的 signing-mode 接缝:工作流输入默认 none(不签名,在任何 Vault 就绪前都可安全合并),只有 keyvault 才启用签名。Tauri 侧有两种实现方式:
- 仅在发布作业中合并一个包含
signCommand的tauri.windows.conf.json覆盖层; - 或基础配置完全不带
signCommand,在 mode = keyvault 时把构建好的.exe/.msi作为显式后置步骤签名。
两种都可接受,不变量只有一条:未配置好凭据的环境既不会失败,也不会静默签名。
OpenBot 选择了"独立命名的覆盖层 + 显式传参"这条路线,并且刻意避开了 Tauri 的自动合并约定。docs/windows-signing.md 明确警告:覆盖层文件名是 tauri.windows-signing.conf.json,不要改成 tauri.windows.conf.json——后者会被 Tauri 自动合并进每一次 Windows 构建,等于给所有普通 CI 与 fork PR 打开了签名开关。
构建命令因此需要显式叠加两层配置:
bun run tauri build --config src-tauri/tauri.windows-signing.conf.json --config src-tauri/tauri.build-version.conf.json --bundles nsis
仓库还针对这个不变量写了断言。desktop/scripts/test-windows-signing.ps1 会读取基础配置 desktop/src-tauri/tauri.conf.json,确认 bundle.windows.signCommand 不存在,并确认 tauri.windows.conf.json 这个文件名也没有出现——两道检查共同防止"签名被自动打开"。
五、访问权限:什么需要改,什么不用改
Key Vault 侧的权限模型对 NuGet 签名与 Authenticode 签名完全相同。AzureSignTool 恰好只需要三个操作:Key: Sign、Secret: Get、Certificate: Get——正是 NuGetKeyVaultSignTool 每次发布已经在做的三件事。因此:
- 不需要新增任何 Azure RBAC 角色分配(既有的 Key Vault Crypto User,或传统 access policy,已覆盖这些操作)。
- 不需要修改 Vault 配置——同一个 Vault、同一张证书、同一个
keys/sign操作。 - 不需要新访问策略、不需要导出密钥、不需要生成
.pfx。
注意一处与"零变更"表述相关的细节:docs/windows-signing.md 记录了 OpenBot 在 RBAC 模式下所需的组合是 Key Vault Certificate User 加 Key Vault Crypto User,因为 Crypto User 单独并不授予证书读取权限。这与 AzureSignTool 的三项操作需求一致,只是把"读证书"显式写了出来。
唯一可能需要改动 Entra ID 的,是映射 GitHub OIDC 令牌到应用注册的联邦凭据(federated credential),且只在 Tauri 构建运行于现有凭据未覆盖的位置时才需要。
5.1 同仓库 / 同环境 → 什么都不用改
如果 Tauri 签名作业与既有 NuGet 签名作业运行在同一个仓库、同一 environment 或同一 ref 下,现有联邦凭据已经覆盖,AZURE_SIGNING_CLIENT_ID 与 AZURE_TENANT_ID 直接可用。
5.2 不同仓库 → 增加一条联邦凭据
联邦凭据的 subject 是精确匹配的:不支持通配符,也不存在 repo:org/* 这种组织级覆盖。作用域为 repo:ag-ui-protocol/ag-ui:... 的凭据不会覆盖任何其他仓库。在 NuGet 通道使用的同一个应用注册上新增一条:
- Issuer:
https://token.actions.githubusercontent.com - Audience:
api://AzureADTokenExchange - Subject:新仓库的令牌 subject,例如
repo:other-org/tauri-app:environment:release或repo:other-org/tauri-app:ref:refs/heads/main
主题格式的坑(2026 年之后尤其重要):2026 年 7 月 15 日之后创建的仓库默认签发不可变主题格式——repo:owner@owner-id/repo@repo-id:ref:...,里面内嵌数字 ID。如果 Tauri 仓库是全新的,它的 OIDC 令牌 sub 声明就是这个格式,凭据 subject 必须与之逐字符一致。创建凭据之前,先跑一个调试工作流把 sub 打印出来,原样复制。
仓库里的 desktop/signing/azure-federation.json 就是这种不可变格式的实例,并且把作用域收窄到环境:
{
"name": "openbot-windows-signing",
"issuer": "https://token.actions.githubusercontent.com",
"subject": "repo:CopilotKit@131273140/OpenBot@1336502227:environment:windows-signing",
"description": "OpenBot protected Windows signing workflow; existing DigiCert certificate",
"audiences": ["api://AzureADTokenExchange"]
}
创建命令(在仓库根目录执行):
az ad app federated-credential create \
--id <AZURE_CLIENT_ID> \
--parameters desktop/signing/azure-federation.json
操作前先检查已有凭据,不要重复创建或替换掉其他仓库的凭据。返回 Insufficient privileges 说明需要应用所有者/管理员来执行——GitHub 的环境审批不会授予 Entra 权限。
仓库多的场景可以改用 Entra 灵活联合身份(flexible federation,基于声明匹配表达式),让一条凭据覆盖多个仓库;当第三个、第四个签名仓库可预期时优先选它。
5.3 跨仓库清单(完整版)
在另一个仓库里:
- 在现有应用注册上新增联邦凭据(见上)。
- 设置仓库 secrets/variables:
AZURE_TENANT_ID、AZURE_SIGNING_CLIENT_ID(与 ag-ui 仓库同值),外加AZURE_KEY_VAULT_URL、CODE_SIGNING_CERT_NAME。Secrets 不跨仓库共享——要么每个仓库各建一份,要么把非敏感值(tenant ID、client ID、Vault URL、证书名)提升为组织级 Actions variables,让两个仓库读取同一份真相。 - 若凭据 subject 按环境作用域,创建对应签名环境(如
release)并施加保护规则。 - 在签名作业上声明
permissions: id-token: write。 - 在作业中安装 AzureSignTool:
dotnet tool install --global AzureSignTool。 - 加上
tauri.conf.json的signCommand与包装脚本(仓库本地)。
OpenBot 的实际做法与清单第 2、3 条完全对应:五个值全部以 variables 形式挂在 windows-signing 环境上(它们是公开标识符,不是密码),指针本体的审批则由环境的 required reviewers 承担。
5.4 爆炸半径:共享身份与独立身份
把凭据加到现有应用注册上,意味着 Tauri 仓库共享了那个能够在组织代码签名密钥上调用 keys/sign 的身份:任何能触发该仓库签名作业的人,都能用 Tawkit 证书签任何东西。又因为证书是 OV,SmartScreen 信誉归属于共享的发布者——任何一个仓库的签名作业被攻破,都会损害整个组织的签名信誉。
在 Azure 侧零成本的缓解措施:
- 把联邦凭据限定到受保护环境(subject 形如
...:environment:release)并配置必需审批,而不是普通分支 ref,让签名只在批准后发生。 - 在新仓库保留
signing-mode: none | keyvault闸门,与既有接缝一致,使未配置的 PR 永远无法触发签名。
如果确实需要隔离,就为 Tauri 仓库建立独立的应用注册——这是唯一一种真的需要新增 Azure 权限的变体,因为新的服务主体必须在 Vault 上被手工授予 Key Vault Crypto User。
六、验证:签了不等于签对
6.1 基础验证命令
构建完成后、发布之前:
# Authenticode + 证书链 + RFC 3161 时间戳
signtool verify /pa /v /all path\to\App.exe
# PowerShell 替代方案
Get-AuthenticodeSignature path\to\App.exe | Format-List
期望结果:Status 为 Valid,SignerCertificate 的 subject 为 CN=Tawkit, Inc.,TimeStamperCertificate 来自 DigiCert,且时间戳落在证书有效期内。
NuGet 包走独立通道、同一个 Vault:dotnet nuget verify Package.nupkg --verbosity detailed。
6.2 仓库的双产物验证与证据文件
OpenBot 的验证并不止步于"跑一次 signtool"。desktop/scripts/verify-windows-signatures.ps1 会同时校验应用可执行文件与 NSIS 安装包,并产出机器可读证据:
- 用
Get-AuthenticodeSignature判定Status -ne 'Valid'即失败,覆盖NotSigned、HashMismatch、NotTrusted。 - 用
SignerCertificate.GetNameInfo(SimpleName)严格比较发布者是否为Tawkit, Inc.——注意这是-cne大小写敏感比较,名为Tawkit, Inc. imposter的证书会被拦下。 - 要求
TimeStamperCertificate非空;signtool verify /pa /all /v /tw中/tw会在缺失时间戳时返回退出码 2,脚本把任何非零退出码都当作失败。 - 安装包目录中
*-setup.exe必须恰好一个,多出来的陈旧产物会被判为失败。 - 传入
-ExpectedVersion时,ProductVersion与FileVersion必须与desktop/build-version.json中的版本逐字符相等。 - 汇总写入
signatures.json:源提交 SHA、每个文件的 SHA-256、签名状态、发布者、签名证书与时间戳证书的 subject 与指纹、signtool 退出码;同时保留.signtool.txt原始输出。
一个来自真实踩坑的细节:Tauri 在打包完成后会把未签名的构建产物还原回 target/release,所以直接验证 target/release/openbot-desktop.exe 检查的是另一个副本。正确做法是用 7-Zip 从 NSIS 安装包里把已签名的载荷抽到 desktop/signed-app/,再验证这份——工作流步骤 "Extract signed app from NSIS installer" 正是如此,默认路径参数也默认指向 signed-app/。回归测试里专门有一条用例复现这个布局,断言验证脚本选中的是安装包载荷而不是被还原的构建输出。
6.3 版本一致性是签名验证的前置条件
因为 OpenBot 的内部构建版本形如 X.Y.Z-internal.g<commit>,版本检查必须与 ProductVersion/FileVersion 完全一致。这个版本由 desktop/scripts/desktop-version.ts 生成:它从根 package.json 读取发布号,从 git rev-parse HEAD 取提交 SHA,写出 tauri.build-version.conf.json 与 desktop/build-version.json。签名作业在编译前执行:
bun scripts/desktop-version.ts internal
随后用生成的 desktop/build-version.json 里的版本号驱动验证脚本,形成"版本生成 → 编译打包 → 签名 → 校验内嵌版本 → 校验签名"的闭环。相关约定见 docs/releasing.md。
6.4 新仓库上线顺序
- 调试工作流:请求 OIDC 令牌并打印
sub声明。 - 用该精确 subject 创建联邦凭据。
azure/login,然后做只读冒烟:az keyvault certificate show --vault-name <vault> --name <cert>。- 冒烟通过则
keys/sign也会通过——签名权限已被每次 NuGet 发布反复证明。 - 开启签名跑完整
tauri build。
七、故障模式与诊断
| 现象 | 根因 | 处理 |
|---|---|---|
azure/login 报 "federated credential not found" |
subject 不匹配 | 打印作业的 sub 声明,与凭据 subject 逐字符比对;注意 2026-07-15 后新仓库的不可变格式,以及 environment 与 ref 作用域差异 |
| 未签发 OIDC 令牌 / 登录拿不到令牌 | 作业缺少 permissions: id-token: write |
补上该权限 |
signCommand 未被调用 / 二进制未签名 |
配置没落在 bundle.windows 下(写成了 v1 顶层 windows),或命令非零退出 |
修正层级;非零退出会直接让打包步骤失败,务必让脚本 exit 0 |
| 找不到 AzureSignTool | 工具未安装在跑构建的同一个 runner/作业中 | 在同一作业内安装或固定版本下载 |
| Vault 返回 401 / invalid token | 令牌的资源作用域不对 | 必须指向 https://vault.azure.net,不是 Graph 或管理端点 |
| 新仓库签名 403、老仓库正常 | 有人给新仓库建了独立应用注册,而该 SPN 未获授权 | 在 Vault 上授予该 SPN Key Vault Crypto User;或改回复用现有应用注册 |
| 本地签名有效但 SmartScreen 仍告警 | OV 证书在全新应用上的信誉状态 | 预期行为,不要换证书或反复重签"修复" |
| 更新包校验失败 | 更新签名来自 Tauri minisign 密钥对,从不来自 Vault 证书 | 用 tauri signer generate 单独生成并配置 |
针对第一条,OpenBot 的做法是把"打印 subject"这一步产品化:联邦凭据的 subject 是以 repo:CopilotKit@131273140/OpenBot@1336502227:environment:windows-signing 这种带所有者与仓库 ID 的不可变形式签入仓库的,任何人改动作用域都会在 diff 里可见,而不是散落在某个人的记忆里。
另外还有两条与本文主题相邻、但同样值得记录的事实:普通桌面 CI 与 fork PR 的构建保持不签名;signtool verify 通过只说明签名链完整,它不测试 SmartScreen 信誉,也不执行应用 UI——这两件事无法在签名作业里被证明。
八、回归测试:在没有 Azure 的情况下守住命令边界
签名脚本最难测的部分是"本机退出码"与"PowerShell 异常"之间的边界,以及失败后令牌是否残留。desktop/scripts/test-windows-signing.ps1 用合成命令结果覆盖了这些路径,完全不需要 Azure 凭据、证书存储或网络:
pwsh -NoProfile -File desktop/scripts/test-windows-signing.ps1
它断言的场景包括:未设置 WINDOWS_SIGNING=keyvault 时拒绝签名;缺少 AZURE_KEY_VAULT_URL 或 CODE_SIGNING_CERT_NAME 时显式报错;输入文件不存在时拒绝且从未调用签名器;az 返回 1 或返回空令牌时失败且令牌不残留;AzureSignTool 返回 1 时失败且令牌不残留;成功路径下令牌被注册为日志掩码、含空格的路径未被拆断;NotSigned/HashMismatch/NotTrusted 三种状态在应用与安装包上都被拒绝;发布者名称不匹配、缺失时间戳、signtool 退出码 1 与 2 都被拦下;证据 JSON 同时包含两个文件与源 SHA;内嵌版本两个字段各自不匹配都被拦下;安装包目录为 0 个或 2 个时失败。
这套测试在 Windows PR CI 上无需 Azure 即可运行;只有受保护的签名作业才能同时验证证书、OIDC 联合身份与真实 Windows 签名链。
九、落地检查清单
- [ ]
signCommand位于bundle.windows,且不在基础配置里。 - [ ] 覆盖层文件名不是
tauri.windows.conf.json,避免被 Tauri 自动合并。 - [ ] 包装脚本带
WINDOWS_SIGNING=keyvault闸门,并在每次调用时刷新访问令牌。 - [ ] 令牌全程不进日志、
GITHUB_ENV、outputs 或产物,finally中清理。 - [ ]
-fd/-td为 sha256,-tr使用 RFC 3161 时间戳服务。 - [ ] 签名作业声明
id-token: write,并绑定受保护环境与必需审批。 - [ ] 跨仓库时飞地凭据 subject 与令牌
sub逐字符一致,非敏感值提升为组织级 variables。 - [ ] 验证对象是从 NSIS 安装包抽出的载荷,而非被 Tauri 还原的构建输出。
- [ ] 验证同时覆盖
.exe与*-setup.exe,检查状态、发布者、时间戳、内嵌版本,并留存signatures.json。 - [ ] 需要自动更新时,单独生成并配置 minisign 密钥对,不复用 Vault 证书。
相关文档与实现入口:docs/windows-signing.md、docs/releasing.md、.github/workflows/desktop-signing.yml、desktop/src-tauri/tauri.windows-signing.conf.json、desktop/scripts/sign-windows.ps1、desktop/scripts/verify-windows-signatures.ps1、desktop/scripts/test-windows-signing.ps1、desktop/signing/azure-federation.json。