@qldc /身份验证
验证节点API中的QLDC劳动力和Entra External ID访问令牌。
包检查签名、显式的颁发者、受众、过期和 oid． 外部ID令牌是 public 并且当其电子邮件在呼叫者的工作电子邮件域列表中时被拒绝。劳动力令牌是 staff． 没有默认的发行者：应用程序通过它信任的发行者，并且空白的受众，发行者或工作邮件列表在启动时失败。
每个SPA都有自己的MSAL设置。 km-auth-extensions 自己检查微软的扩展服务令牌。
安装
npm install @qldc/auth
本地同胞结帐：
{
"dependencies": {
"@qldc/auth": "file:../km-auth"
}
}
使用
import {
QLDC_WORK_EMAIL_DOMAINS,
createExternalIdVerifier,
createWorkforceVerifier,
externalIdIssuer,
workforceIssuers,
} from "@qldc/auth";
const tenantId = process.env.ENTRA_TENANT_ID!;
const audience = process.env.ENTRA_AUDIENCE!;
const verifyWorkforce = createWorkforceVerifier({
audience,
...workforceIssuers(tenantId),
debug: process.env.NODE_ENV === "development", // optional: enable error logging
});
const verifyExternalId = createExternalIdVerifier({
audience: process.env.EXTERNAL_ID_AUDIENCE!,
issuer: externalIdIssuer(process.env.EXTERNAL_ID_TENANT_ID!),
workEmailDomains: QLDC_WORK_EMAIL_DOMAINS,
debug: process.env.NODE_ENV === "development", // optional: enable error logging
});
const staff = await verifyWorkforce(token); // AuthPrincipal | null
const pub = await verifyExternalId(token);
一个劳动力专用的应用程序创建 createWorkforceVerifier 并且不创建外部ID验证器。 workforceIssuers 包含v1颁发者(https://sts.windows.net/{tenant}/）. 省略 v1 当应用程序不接受这些令牌时。
externalIdIssuer 使用 https://{tenant}.ciamlogin.com/{tenant}/v2.0． 登录主机 signin.qldc.govt.nz 不是令牌发行者。
观众接受GUID和 api://{guid} 形式相同的应用程序注册。其他 api:// 值必须与令牌完全匹配。
QLDC_WORK_EMAIL_DOMAINS 是 qldc.govt.nz， qlcht.org.nz, alpinewaters.co.nz． 匹配包括子域。只有当调用者传递该列表时，验证者才使用该列表。
经核实的委托人：
| 场 | 意义 |
|---|---|
capability | staff 或者 public |
oid | Entra对象id。密钥公共用户数据由此。 |
email | email， upn， preferred_username，或者 unique_name |
roles， scp | 劳动力应用程序的角色和范围，当存在时 |
检查失败的令牌返回 null.
调试模式
启用 debug: true 在开发中，将验证失败记录到控制台：
const verifyWorkforce = createWorkforceVerifier({
audience,
...workforceIssuers(tenantId),
debug: true,
});
调试日志包括：
- 无效的JWT格式错误
- 令牌签名失败
- 发行人/观众不匹配
- 过期的问题
- 工作邮件拒绝（仅限外部ID）
先进的类型
对于可观察性和监控，包导出了额外的类型：
import type {
VerificationResult,
VerificationFailureReason,
TokenVerifierWithResult,
} from "@qldc/auth";
这些类型支持构建带有结构化错误响应的自定义验证器，而不仅仅是 null.
发布(维护人员)
CI使用 npm可信发布 （OIDC） -寿命不长 NPM_TOKEN.
- 在npmjs.com→包→ 设置→可信发布者：连接GitHub /repo和
publish.yml - Bump版本和push标签；行动发布:
npm version patch # or minor / major
git push --follow-tags
脚本
npm test
npm run build
npm run typecheck