云原生智能网关认证策略

操作场景
认证策略用于控制客户端对 AI 网关 API 的访问权限。通过配置认证策略，您可以：
为不同的消费者配置不同的访问权限。
单个消费者支持配置多种类型的凭证。
实现细粒度的访问控制和安全防护。
﻿
认证策略在创建模型 API 时配置，确保只有授权的客户端才能访问网关服务。
本文档指导您如何在 AI 网关中配置和管理认证策略。支持的认证方式包括 API Key、JWT、OAuth 2.0、OIDC。
前置条件
已创建 AI 网关实例，详情请参见新建 AI 网关。
已创建消费者，详情请参见新建消费者。
已创建模型 API，详情请参见新建模型 API。
已为消费者创建认证密钥凭证，详情请参见新建消费者密钥。
操作步骤
为模型 API 配置认证策略
创建消费者并添加凭证后，需要在模型 API 中配置认证策略。
说明：
1. API 仅允许使用所配置认证方式的消费者进行访问。
2. 如果消费者配置了其他鉴权方式，由于其认证方式与 API 配置不匹配，将无法通过鉴权，导致访问失败。请确保为消费者配置与 API 一致的认证方式。
步骤1：进入模型 API 认证策略配置页
1. 登录 AI 网关控制台，选择目标实例。
2. 在左侧导航栏，选择模型管理 > 模型 API，单击目标 API ID 进入详情页。
3. 在详情页顶部，单击认证策略页签。
步骤2：启用认证并选择认证方式
单击编辑，完成以下配置：
参数
是否必填
说明
启用认证
是
认证开关。关闭状态即为免认证方式，任何客户端都可以访问 API，不进行任何认证。对于内网环境或测试场景，可以选择免认证方式。
生产环境强烈不建议使用免认证方式。
认证方式
是
API Key
系统将自动生成 API Key
﻿
﻿
JWT
Header 名称：从指定请求头中提取 JWT，多个用英文逗号分隔。
Cookie 名称：从指定 Cookie 中提取 JWT，多个用英文逗号分隔。
URI 参数：从指定 URI 参数中提取 JWT，多个用英文逗号分隔。
消费者标识：用于匹配消费者的标识。
标准 Claims 校验：exp（过期时间）、nbf（生效时间）。
最大有效期：JWT 允许的最大有效期，单位为秒，0 表示不限制。
Base64 编码：关闭（默认）——插件把数据库里 cngw_jwt_secrets 表存储的 secret 字段原样当作签名密钥，直接用它与 JWT 进行 HMAC 验签；开启——插件认为数据库里存的 secret 是 base64 编码后的字符串，会先对其做一次 base64 解码，得到原始密钥，再用原始密钥去验签。
CORS 预检验证：是否对 CORS 预检请求进行验证。
﻿
﻿
OAuth 2.0
Header 名称：从指定请求头中提取 Access Token，多个用英文逗号分隔。
Token 过期时间：Token 过期时间，单位为秒，0 表示不限制。
Scope 白名单：允许的 Scope 白名单，多个用英文逗号分隔。
强制校验 Scope：是否强制校验请求携带的 Token 的 Scope。
﻿
﻿
OIDC
客户端 ID（必填）：OIDC 客户端 ID。
客户端密钥（必填）：OIDC 客户端密钥。
签发者地址（必填）：身份提供商签发地址，用于发现 OIDC 配置，如 https://example.com/oidc。
Audience 目标受众：期望的 Audience 目标受众，留空则不校验。
Scopes 授权范围：请求的 Scopes 授权范围，多个用英文逗号分隔。
消费者标识：用于匹配消费者的标识。
Realm 认证域：认证失败时 WWW-Authenticate 响应头中返回的 realm 标识。
超时时间：请求身份提供商的超时时间，单位为秒。
Token Endpoint 令牌端点认证方法：客户端向 Token Endpoint 令牌端点请求时的认证方法。
Introspection Endpoint 令牌内省端点：令牌内省端点地址。
Introspection Endpoint 令牌内省端点认证方法：请求 Introspection Endpoint 令牌内省端点时的认证方法。
说明：
单个 API 仅支持一种认证方式。
单个 API 可以绑定多个消费者。
单个消费者可以配置多种类型的凭证(如同时配置 API Key 和 JWT)，客户端可根据实际情况选择使用哪种凭证。
步骤3：保存配置
单击确定保存认证策略配置。
新增授权
在认证策略页，对指定消费者组/消费者进行授权。
﻿
使用方式
配置完成后，客户端在请求中携带对应凭证访问网关。以下示例中的凭证提取位置（如 Authorization 头）需与认证策略中配置的 Header 名称 / Cookie 名称 / URI 参数 保持一致。
API Key
客户端请求时，在请求头中携带 API Key：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer {API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
说明：
Authorization Header 格式为 Bearer {API_Key}。
API Key 一旦生成，请妥善保管，不要泄露给无关人员。
JWT
客户端请求时，在请求头中携带 JWT Token：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer {JWT_Token}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
JWT Token 示例(HS256)：
Header:
{
  "alg": "HS256",
  "typ": "JWT"
}
﻿
Payload:
{
  "sub": "user123",
  "iss": "your-app",
  "exp": 1735660800
}
﻿
Signature:
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  your-secret-key
)
OAuth 2.0
方式1：客户端自行获取 Access Token
客户端先调用 OAuth 服务获取 Access Token，然后携带 Token 访问网关：
# 步骤1:获取Access Token
curl -X POST https://oauth.example.com/token \\
  -d "grant_type=client_credentials" \\
  -d "client_id=client-12345" \\
  -d "client_secret=secret-xxxxxx"
﻿
# 响应示例:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
﻿
# 步骤2:携带Access Token访问网关
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
方式2：网关代为获取 Access Token
网关可以根据配置的 OAuth 信息，代为获取 Access Token 并缓存，客户端只需提供 Client ID 和 Client Secret：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "X-Client-ID: client-12345" \\
  -H "X-Client-Secret: secret-xxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
OIDC
使用方式
客户端请求时，在请求头中携带 ID Token：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer {ID_Token}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
说明：
OIDC 使用 ID Token 进行身份认证，ID Token 是一个 JWT。
网关会自动从 OIDC 服务的 Discovery Endpoint 获取公钥，验证 ID Token 签名。
网关会校验 ID Token 的 iss、aud、exp 等标准 Claims。
结果验证
验证 API Key 认证
使用正确的 API Key 访问 API：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer {正确的API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
预期结果：返回200响应，成功调用模型。
使用错误的 API Key 访问 API：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer wrong-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
预期结果：返回401 Unauthorized 错误。
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API Key"
  }
}
验证 JWT 认证
使用消费者密钥中配置的共享密钥和算法生成 JWT Token（iss 设为消费者标识）：
import jwt
import time
﻿
# JWT配置
secret = os.getenv('SECRET_KEY') # 消费者密钥中配置的共享密钥
algorithm = "HS256" # 消费者密钥中配置的算法
﻿
# 生成Token
payload = {
    "sub": "user123",#这是啥
    "iss": "your-app", #这是啥
    "exp": int(time.time()) + 3600  # 1小时后过期
}
token = jwt.encode(payload, secret, algorithm=algorithm)
﻿
print(f"JWT Token: {token}")
使用生成的 JWT Token 访问 API：
curl -X POST https://{网关域名}/{base_path}/v1/chat/completions \\
  -H "Authorization: Bearer {JWT_Token}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
预期结果：返回200响应，成功调用模型。
验证 OAuth 2.0认证
先向 OAuth 服务获取 Access Token，再携带 Token 访问 API，可参考上文 使用方式 部分。
验证 OIDC 认证
使用 OIDC 服务颁发的 ID Token 访问 API，可参考上文 使用方式 部分。
注意事项
凭证安全：API Key、密钥、Client Secret 等凭证信息务必妥善保管，不要提交到代码仓库或公开渠道
凭证轮换：建议定期更换凭证，降低凭证泄露风险
有效期设置：建议为凭证设置有效期，避免长期有效凭证泄露后持续被滥用
最小权限原则：为不同的消费者配置不同的 API 访问权限，避免过度授权
免认证风险：生产环境禁止使用免认证方式，仅适用于内网测试场景
OAuth Token 缓存：网关会缓存 OAuth Access Token，如 Provider 侧 Token 失效，需等待缓存过期或手动刷新
凭证提取位置一致：客户端携带凭证的位置（Header / Cookie / URI 参数）需与认证策略中配置的一致，否则会认证失败
常见问题
配置使用类
Q1：如何选择合适的认证方式?
根据您的实际场景选择：
API Key：简单场景，适用于内部服务或可信客户端，配置简单，性能最优
JWT：需要传递用户身份信息，支持自定义 Claims，适用于微服务间调用
OAuth 2.0：需要接入第三方 OAuth 服务，支持标准 OAuth 流程
OIDC：需要用户身份认证，支持 SSO(单点登录)
免认证：仅适用于内网测试场景，生产环境禁用
Q2：单个 API 可以支持多种认证方式吗?
不可以。单个 API 仅支持一种认证方式，但可以绑定多个消费者，每个消费者可以配置多种凭证。如需支持多种认证方式，请创建多个 API，分别配置不同的认证方式。
功能限制类
Q1：单个 API 最多可以绑定多少个消费者?
单个 API 最多可以绑定100个消费者。
Q2：OAuth 2.0支持哪些授权模式?
当前支持以下授权模式：
Client Credentials(客户端凭证模式)：适用于机器对机器(M2M)场景
Password(密码模式)：适用于可信客户端场景
Authorization Code(授权码模式)：适用于 Web 应用场景
暂不支持 Implicit(隐式模式)和 Refresh Token 流程。
错误处理类
Q1：调用 API 时返回401 Unauthorized 错误怎么办?
401错误表示认证失败，请检查：
1. 凭证是否正确(API Key、JWT Token 等)
2. 该消费者是否已绑定到 API 的认证策略中
3. 凭证是否已过期或被禁用
4. Authorization Header 格式是否正确(格式：Bearer {凭证})
5. 如使用 JWT，检查签名算法和密钥是否与配置一致
6. 如使用 OAuth 2.0，检查 Access Token 是否有效
Q2：配置 JWT 认证后，调用时返回"Invalid signature"错误?
这表示 JWT 签名验证失败，请检查：
1. 签名算法是否与配置一致(HS256、RS256、ES256)
2. 密钥/公钥是否正确：
HS256：密钥必须与签名时使用的密钥一致
RS256/ES256：公钥必须与签名时使用的私钥对应
3. JWT Token 是否被篡改或损坏
建议使用 jwt.io 在线工具验证 JWT Token。
Q3：配置 OAuth 2.0认证后，调用时返回"Failed to get access token"错误?
这表示网关无法从 OAuth 服务获取 Access Token，请检查：
1. token Endpoint 地址是否正确
2. Client ID 和 Client Secret 是否正确
3. OAuth 服务是否正常可用(网关能否访问到 token endpoint)
4. Scope 配置是否正确(某些 OAuth 服务要求 Scope 必须匹配)
5. 授权模式是否与 OAuth 服务支持的模式一致
建议先使用 curl 直接调用 OAuth 服务的 token endpoint，确认可以成功获取 Access Token。
实践教程类
Q1：生产环境如何管理认证凭证?
建议的管理实践：
1. 凭证轮换：定期更换凭证(如每季度更换一次)，降低凭证泄露风险
2. 有效期设置：为凭证设置合理的有效期(如1年)，避免永久有效凭证泄露后持续被滥用
3. 权限分离：为不同的业务系统创建不同的消费者，避免共用凭证
4. 监控告警：监控认证失败率，异常流量及时告警
5. 凭证存储：凭证信息存储在配置中心或密钥管理服务中，不要硬编码在代码中
6. 泄露应急：如凭证泄露，立即禁用或删除该凭证，并创建新凭证
Q2：如何实现多环境(开发、测试、生产)的认证隔离?
建议采用以下方案：
1. 方案1：多网关实例
为开发、测试、生产环境分别创建独立的网关实例
每个实例配置独立的消费者和凭证
环境间完全隔离，互不影响
2. 方案2：单网关实例+多消费者
使用单个网关实例
为不同环境创建不同的消费者(如"开发消费者"、"生产消费者")
创建不同的 API，分别绑定不同的消费者
通过 API 访问地址区分环境(如 /dev/api、/prod/api)
建议使用方案1，环境隔离更彻底，更安全。
Q3：如何设计多租户场景的认证方案?
对于 SaaS 等多租户场景，建议采用以下方案：
1. 租户隔离：为每个租户创建独立的消费者
2. 认证方式：
B 端租户：使用 API Key 或 OAuth 2.0，便于管理
C 端用户：使用 JWT 或 OIDC，支持用户身份信息传递
3. 租户识别：
方案 A：在 JWT 的 Claims 中包含租户 ID(如 tenant_id)
方案 B：为每个租户分配独立的 API key
4. 访问控制：在网关层识别租户，后端服务根据租户 ID 进行数据隔离
5. 计费与配额：基于消费者维度进行流量统计和限流，实现租户级别的计费与配额管理

参数	是否必填	说明
启用认证	是	认证开关。关闭状态即为免认证方式，任何客户端都可以访问 API，不进行任何认证。对于内网环境或测试场景，可以选择免认证方式。生产环境强烈不建议使用免认证方式。
认证方式	是	API Key 系统将自动生成 API Key
			JWT Header 名称：从指定请求头中提取 JWT，多个用英文逗号分隔。 Cookie 名称：从指定 Cookie 中提取 JWT，多个用英文逗号分隔。 URI 参数：从指定 URI 参数中提取 JWT，多个用英文逗号分隔。消费者标识：用于匹配消费者的标识。标准 Claims 校验：exp（过期时间）、nbf（生效时间）。最大有效期：JWT 允许的最大有效期，单位为秒，0 表示不限制。 Base64 编码：关闭（默认）——插件把数据库里 cngw_jwt_secrets 表存储的 secret 字段原样当作签名密钥，直接用它与 JWT 进行 HMAC 验签；开启——插件认为数据库里存的 secret 是 base64 编码后的字符串，会先对其做一次 base64 解码，得到原始密钥，再用原始密钥去验签。 CORS 预检验证：是否对 CORS 预检请求进行验证。
			OAuth 2.0 Header 名称：从指定请求头中提取 Access Token，多个用英文逗号分隔。 Token 过期时间：Token 过期时间，单位为秒，0 表示不限制。 Scope 白名单：允许的 Scope 白名单，多个用英文逗号分隔。强制校验 Scope：是否强制校验请求携带的 Token 的 Scope。
			OIDC 客户端 ID（必填）：OIDC 客户端 ID。客户端密钥（必填）：OIDC 客户端密钥。签发者地址（必填）：身份提供商签发地址，用于发现 OIDC 配置，如 https://example.com/oidc。 Audience 目标受众：期望的 Audience 目标受众，留空则不校验。 Scopes 授权范围：请求的 Scopes 授权范围，多个用英文逗号分隔。消费者标识：用于匹配消费者的标识。 Realm 认证域：认证失败时 WWW-Authenticate 响应头中返回的 realm 标识。超时时间：请求身份提供商的超时时间，单位为秒。 Token Endpoint 令牌端点认证方法：客户端向 Token Endpoint 令牌端点请求时的认证方法。 Introspection Endpoint 令牌内省端点：令牌内省端点地址。 Introspection Endpoint 令牌内省端点认证方法：请求 Introspection Endpoint 令牌内省端点时的认证方法。

认证策略

本页目录：

操作场景

前置条件

操作步骤

为模型 API 配置认证策略

步骤1：进入模型 API 认证策略配置页

步骤2：启用认证并选择认证方式

步骤3：保存配置

新增授权

使用方式

API Key

JWT

OAuth 2.0

OIDC

使用方式

结果验证

验证 API Key 认证

验证 JWT 认证

验证 OAuth 2.0认证

验证 OIDC 认证

注意事项

常见问题

配置使用类

Q1：如何选择合适的认证方式?

Q2：单个 API 可以支持多种认证方式吗?

功能限制类

Q1：单个 API 最多可以绑定多少个消费者?

Q2：OAuth 2.0支持哪些授权模式?

错误处理类

Q1：调用 API 时返回401 Unauthorized 错误怎么办?

Q2：配置 JWT 认证后，调用时返回"Invalid signature"错误?

Q3：配置 OAuth 2.0认证后，调用时返回"Failed to get access token"错误?

实践教程类

Q1：生产环境如何管理认证凭证?

Q2：如何实现多环境(开发、测试、生产)的认证隔离?

Q3：如何设计多租户场景的认证方案?