JWT 认证
AISIX 可以使用短期 JSON Web Token(JWT)凭证认证 Agent,无须使用长期调用方 API Key。信任服务提供方会根据 JSON Web Key Set(JWKS)中发布的签名 Key 或共享密钥来验证每个 Token。每个经过验证的外部身份都会映射到调用方 API Key,并继承该 Key 的模型访问权限、限流和用量归因。在 AISIX Enterprise 和 AISIX Cloud 中,映射后的 Key 还会携带预算。
基于 JWKS 的服务提供方包括 Keycloak、Entra ID、Okta、Auth0 和其他兼容 OIDC 的身份服务提供方。AISIX 还可以验证由与网关共享密钥的签发者签署的 HMAC Token。无论采用哪种方式,AISIX 都会为每个请求验证 Token 签名和声明,Agent 不需要调用方 API Key 的明文值。
面向人工运维人员的控制台单点登录和面向 Agent 请求的网关 JWT 认证彼此独立,配置其中一项不会影响另一项。
工作原理
当环境中至少存在一个已启用的信任服务提供方时,AISIX 会检查每个请求的 Bearer Token:
- 如果 Bearer 是 JWT,其
iss(签发者)声明会选择信任服务提供方:当iss与某个已启用服务提供方的issuer相等时,仅由该服务提供方验证此 Token。签发者与所有已启用服务提供方均不匹配的 Token 只会到达未指定签发者的已启用共享密钥服务提供方,若其中没有一个能通过验证,则该 Token 被拒绝。 - AISIX 使用服务提供方的 JSON Web Key Set(JWKS)验证 Token 签名;如果该服务 提供方配置了共享密钥,则改用该密钥验证。随后验证注册声明:始终必需的
exp(过期时间)、仅在服务提供方配置了接受的受众时校验的aud(受众),以及存在时的nbf(生效时间)。 - 执行服务提供方的
required_scopes和bound_claims要求。 - 服务提供方身份声明的值(默认为
sub)会选择jwt_subject与该值相等,且jwt_provider指向此服务提供方的调用方 API Key。随后请求会以此 Key 的身份运行。将绑定限定到服务提供方,可以防止第二个受信任服务提供方签发冒充此服务提供方身份的 Token。 - 当没有 Key 直接绑定该身份时,服务提供方的 Claim 映射——按优先级排序、匹配已验证声明的规则——可以把请求解析到一把既有的 Key,让一整组身份共享一把受治理的 Key 而无需逐个注册。既未命中绑定也未命中映射的 Token 会被拒绝。
未通过验证或无法映射到调用方 API Key 的 Token 会在请求到达服务提供方、MCP 服务器或向量存储前被 AISIX 拒绝。对于 JWKS 服务提供方,身份服务提供方的签名 Key 轮换会自动生效,无须重启网关。
前置条件
开始前,请准备以下内容:
- 以下任一配置路径:
- AISIX Enterprise 或 AISIX Cloud 环境,以及具有
write作用域的 Admin Token。使用 AISIX Enterprise 时,请先完成 AISIX Enterprise 快速入门;如需申请 AISIX Cloud 访问权限,请联系 API7。 - 加载声明式
resources.yaml文件的开源 AISIX 网关。
- AISIX Enterprise 或 AISIX Cloud 环境,以及具有
- 向 Agent 签发 JWT 的系统,以及与其签名方式相应的验证材料:
- 使用 JWKS 验证时,请准备预期的签发者,以及其 JWKS 端点 URL 或 OIDC 发现文档(
<issuer>/.well-known/openid-configuration)。 - 使用 HMAC 签名时,请准备共享密钥。其 UTF-8 编码长度必须至少为 32 字节;预期的签发者和受众可选。
- 使用 JWKS 验证时,请准备预期的签发者,以及其 JWKS 端点 URL 或 OIDC 发现文档(
- 调用方可以使用的模型别名;控制面工作流还需要其模型 ID。如果尚未创建,请先配置服务提供方密钥和模型别名。
curl和jq。开源 AISIX 网关还需要 OpenSSL,以运行下文的凭证生成命令。
使用 JWKS 验证的服务提供方必须使用 AISIX 支持的非对称算法签署 Token:RSA(RS256、RS384、RS512、PS256、PS384 或 PS512)、ECDSA(ES256 或 ES384),或 EdDSA,并会拒绝 HMAC 签名的 Token。如果需要信任使用共享密钥签名的签发者,请改为给服务提供方配置 hmac_secret,详见共享密钥(HMAC)服务提供方。
配置 JWT 认证
请使用与你的部署方式对应的管理路径,配置信任服务提供方和绑定身份的调用方 API Key。
选择信任服务提供方设置
AISIX Enterprise、AISIX Cloud 和开源 AISIX 网关采用相同的信任设置,但对签发者唯一性的约束方式不同:
| 字段 | 说明 |
|---|---|
issuer | 预期的 iss 声明,会与 Token 进行精确比较。已配置的签发者在 AISIX 环境中必须唯一;在资源文件中,设置了签发者的已启用服务提供方必须使用不同的值。使用 JWKS 验证时必填;设置 hmac_secret 时可选。未指定签发者的共享密钥服务提供方不会校验 iss。 |
audiences | 接受的 aud 值。使用 JWKS 验证时必须至少配置一个值,且 Token 必须包含匹配值。设置 hmac_secret 时,省略该字段或使用空列表即可跳过受众校验。 |
jwks_uri | 获取签名 Key 的端点。省略时,从签发者的 OIDC 发现文档解析。不能与 hmac_secret 同时设置。 |
hmac_secret | 共享密钥,设置后该服务提供方改用 HMAC 验证。使用 JWKS 验证的服务提供方请省略此字段。详见共享密钥(HMAC)服务提供方。 |
identity_claim | 声明路径,其值用于选择调用方 API Key,会与每个 Key 的 jwt_subject 匹配,例如 resource_access.account。默认 sub |