@ civic/ auth- 验证
JWT 用于使用 JWKS 端点发现的 Civil Auth 证书的验证库 .
特征
- 使用 JWKS 端点发现进行 JWT 符号验证
- OIDC配置发现(. 熟知/开通配置)
- 使用基于发行器的密钥为 JWKS 数据构建缓存
- 支持多个缓存执行( InMemory and Bundled)
- 具有完整类型安全的脚本支持
安装
pnpm add @civic/auth-verify
使用量
基本用途
import { verify } from '@civic/auth-verify';
// Verify a token with default settings (uses Civic Auth issuer)
const payload = await verify(token);
console.log(payload);
使用自定义缓存
默认情况下,库对JWKS数据使用内存缓存. 如有需要,您可以自行提供缓存执行 .
在内存缓存中,密钥被存储在内存中,并在进程重启时丢失.
库使用所有共享的默认实例 verify 除非你自己提供.
如果您想要控制缓存的生命周期,请提供以下内容:
import { verify, InMemoryJWKSCache } from '@civic/auth-verify';
// Create a custom cache instance
const cache = new InMemoryJWKSCache();
// Use the cache for verification
const payload = await verify(token, {
jwksCache: cache
});
使用 “ Bundled 缓存 ” (预装 Civil Auth JWKS)
Bundled缓存是预存有Civil Auth JWKS密钥的密钥缓存,可用于离线验证或降低延迟.
- 预装密钥: 包含在构建时捆绑的最新公民 Auth JWKS
- 离线支持: 能够验证公民 没有网络请求的认证符
- 业绩: 取消 JWKS 为 Civil Auth 令牌获取的初始版本
- 更新: 捆绑的JWKS在包建/发布时被更新
- 广泛: 仍然可以为其他发行人动态获取并缓存 JWKS
说明:被捆绑的JWKS是Civil Auth键所特有的. 如果使用另一个发行器,您仍可使用 InMemoryJWKSCache 或执行自己的缓存.
import { verify, BundledJWKSCache } from '@civic/auth-verify';
// Use bundled cache with pre-downloaded Civic Auth JWKS
const cache = new BundledJWKSCache();
const payload = await verify(token, {
jwksCache: cache
});
API 密码
verify(token: string, options?: VerifyOptions): Promise<JWTPayload>
验证一个JWT标志,并返回其有效载荷.
参数
token- JWT证明书options- 可选核查选项issuer- 符号发行器 URL( 默认为 Civil Auth)wellKnownConfigurationUrl- 自定义 OpenID 配置 URLjwksCache- 自定义 JWKS 缓存执行aud- 标志的预期受众值(可选)clientId- 对象的预期客户端ID值(可选). 如果提供,JWT必须在以下两种中的任何一种中包含这一数值:client_id或者说tid字段issuerValidator- 可选上游(issuer: string) => boolean为了接受这个标志iss索赔。 提供时,Jose的精确匹配的发行人检查被跳过,而代号是iss3⁄4 ̄ ̧漯B 用它来接受多个发行商,例如动态客户注册的租户范围发行商(英语:https://auth.civic.com/oauth/<tid>/JWKS的发现仍然使用issuer(或默认),所以每个被接受的发行者必须共享JWKS.
回返
一个能解决JWT有效载荷的承诺.
接受多个发行人(例如,租户范围/DCR令牌)
import { verify } from '@civic/auth-verify';
// Accept the base Civic issuer and any tenant-scoped issuer beneath it
const payload = await verify(token, {
issuerValidator: (iss) => iss.startsWith('https://auth.civic.com/oauth/'),
});
发展
# Install dependencies
pnpm install
# Run tests
pnpm test
# Build
pnpm build
# Lint
pnpm lint