云原生智能网关认证策略

操作场景
认证策略用于控制客户端对 AI 网关 API 的访问权限。通过配置认证策略，您可以：
支持多种认证方式(API Key、JWT、OAuth 2.0、OIDC)。
为不同的消费者配置不同的访问权限。
单个消费者支持配置多种类型的凭证。
实现细粒度的访问控制和安全防护。
﻿
认证策略在创建模型 API 时配置，确保只有授权的客户端才能访问网关服务。
本文档指导您如何在 AI 网关中配置和管理认证策略。
前置条件
已创建 AI 网关实例。
已创建消费者。
已创建模型 API 或 Agent API。
操作步骤
创建消费者
消费者是 AI 网关的访问主体，必须先创建消费者才能配置认证策略。
步骤1：进入消费者列表页
1. 登录 AI 网关控制台，选择对应实例。
2. 在左侧导航栏选择消费者管理，单击消费者页签。
3. 单击新建。
步骤2：配置消费者信息
参数
是否必填
说明
消费者名称
是
消费者的名称，支持中文、英文、数字、下划线，长度1-60字符。
所属消费者组
否
消费者所属的消费者组。
密钥
否
消费者绑定的密钥。
描述
否
消费者的功能描述，最多200字符。
步骤3：完成创建
单击确定完成消费者创建。
为消费者添加认证凭证
创建消费者后，需要为其添加认证凭证，支持同时配置多种类型的凭证。
步骤1：进入消费者详情页
在消费者列表页，单击消费者名称或操作列的详情。
步骤2：添加凭证
在凭证管理区域，单击添加凭证，选择凭证类型。
认证方式1：API Key
API Key 是最简单的认证方式，适用于内部服务或可信客户端。
配置参数
参数
是否必填
说明
示例
凭证类型
是
选择 API Key
API Key
API Key
自动生成
系统自动生成 API Key，也可自定义
ak-xxxxxxxxxx
有效期
否
设置凭证有效期,默认永久有效
2027-12-31
使用方式
客户端请求时，在请求头中携带 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 一旦生成，请妥善保管，不要泄露给无关人员。
认证方式2：JWT
JWT(JSON Web Token)适用于需要传递用户身份信息的场景，支持自定义 Claims。
配置参数
参数
是否必填
说明
示例
凭证类型
是
选择 JWT
JWT
签名算法
是
选择 JWT 签名算法：
• HS256(HMAC SHA256)
• RS256(RSA SHA256)
• ES256(ECDSA SHA256)
HS256
密钥/公钥
是
根据签名算法配置：
• HS256：配置密钥(Secret)
• RS256/ES256：配置公钥(Public Key)
your-secret-key
有效期校验
否
是否校验 JWT 的 exp 字段
开启
必需 claims
否
配置必须包含的 Claims 字段
sub, iss
使用方式
客户端请求时，在请求头中携带 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
)
认证方式3：OAuth 2.0
OAuth 2.0适用于需要接入第三方 OAuth 服务的场景，支持多种授权模式。
配置参数
参数
是否必填
说明
示例
凭证类型
是
选择 OAuth 2.0
OAuth 2.0
授权模式
是
选择 OAuth 2.0授权模式：
• Client Credentials(客户端凭证模式)
• Password(密码模式)
• Authorization Code(授权码模式)
Client Credentials
Token Endpoint
是
OAuth 服务的 Token 获取地址
https://oauth.example.com/token
Client ID
是
OAuth 客户端 ID
client-12345
Client Secret
是
OAuth 客户端密钥
secret-xxxxxx
Scope
否
请求的权限范围
read write
Token 缓存时长
否
Token 缓存时长，默认根据 Token 的 expires_in 字段
3600秒
使用方式
方式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": "你好"}]
  }'
认证方式4：OIDC
OIDC(OpenID Connect)是基于 OAuth 2.0的身份认证协议，适用于需要用户身份认证的场景。
配置参数
参数
是否必填
说明
示例
凭证类型
是
选择 OIDC
OIDC
Issuer URL
是
OIDC 服务的 Issuer 地址
https://oidc.example.com
Client ID
是
OIDC 客户端 ID
client-12345
Client Secret
否
OIDC 客户端密钥(部分 Provider 需要)
secret-xxxxxx
Discovery Endpoint
自动生成
根据 Issuer URL 自动生成 Discovery 地址
https://oidc.example.com/.well-known/openid-configuration
公钥获取方式
是
选择公钥获取方式：
• 自动发现(从 Discovery Endpoint 获取)
• 手动配置(手动输入 JWKS 或公钥)
自动发现
使用方式
客户端请求时，在请求头中携带 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，不进行任何认证。
生产环境强烈不建议使用免认证方式。
为 API 配置认证策略
创建消费者并添加凭证后，需要在 API 中配置认证策略，绑定消费者。
步骤1：进入 API 配置页
在创建或编辑模型 API/Agent API 时，找到认证策略区域。
步骤2：选择认证方式
参数
是否必填
说明
示例
认证方式
是
选择该 API 支持的认证方式(单选)
API Key
绑定消费者
是(除免认证外)
选择允许访问该 API 的消费者，支持多选
消费者 A
消费者 B
说明：
单个 API 仅支持一种认证方式。。
单个 API 可以绑定多个消费者
单个消费者可以配置多种类型的凭证(如同时配置 API Key 和 JWT)，客户端可根据实际情况选择使用哪种凭证。
步骤3：保存配置
单击 确定 保存认证策略配置。
管理消费者凭证
查看凭证列表
在消费者详情页的 凭证管理 区域，可查看该消费者的所有凭证：
凭证类型(API Key、JWT、OAuth 2.0、OIDC)
凭证状态(启用、禁用、已过期)
创建时间和有效期
禁用凭证
如需临时禁用某个凭证，单击操作列的禁用。禁用后，使用该凭证的请求将被拒绝。
启用凭证
对于已禁用的凭证，单击操作列的启用即可重新启用。
删除凭证
单击操作列的删除，可永久删除该凭证。删除后，使用该凭证的请求将被拒绝。
说明：
删除凭证是不可逆操作，请谨慎操作。
更新凭证
对于 JWT、OAuth 2.0、OIDC 凭证，单击操作列的 编辑，可更新凭证配置(如密钥、Token Endpoint 等)。
说明：
API Key 凭证创建后不可修改，如需更换请删除后重新创建。
结果验证
验证 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（使用配置的密钥和签名算法）：
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认证
先获取 Access Token，再访问 API，可参考上文 使用方式 部分。
验证 OIDC 认证
使用 OIDC 服务颁发的 ID Token 访问 API，可参考上文 使用方式 部分。
注意事项
凭证安全：API Key、密钥、Client Secret 等凭证信息务必妥善保管，不要提交到代码仓库或公开渠道
凭证轮换：建议定期更换凭证，降低凭证泄露风险
有效期设置：建议为凭证设置有效期，避免长期有效凭证泄露后持续被滥用
最小权限原则：为不同的消费者配置不同的 API 访问权限，避免过度授权
免认证风险：生产环境禁止使用免认证方式，仅适用于内网测试场景
OAuth Token 缓存：网关会缓存 OAuth Access Token，如 Provider 侧 Token 失效，需等待缓存过期或手动刷新
常见问题
配置使用类
Q1：如何选择合适的认证方式?
A：根据您的实际场景选择：
API Key：简单场景，适用于内部服务或可信客户端，配置简单，性能最优
JWT：需要传递用户身份信息，支持自定义 Claims，适用于微服务间调用
OAuth 2.0：需要接入第三方 OAuth 服务，支持标准 OAuth 流程
OIDC：需要用户身份认证，支持 SSO(单点登录)
免认证：仅适用于内网测试场景，生产环境禁用
Q2：单个消费者可以配置多个凭证吗?
A：可以。单个消费者支持同时配置多种类型的凭证，例如：
凭证1：API Key 类型
凭证2：JWT 类型
凭证3：OAuth 2.0类型
客户端可以根据实际情况选择使用哪种凭证访问 API。
Q3：单个 API 可以支持多种认证方式吗?
A：不可以。单个 API 仅支持一种认证方式，但可以绑定多个消费者，每个消费者可以配置多种凭证。
如需支持多种认证方式，请创建多个 API，分别配置不同的认证方式。
Q4：JWT 的签名算法如何选择?
A：
HS256(对称加密)：使用密钥(Secret)进行签名和验证，配置简单，性能最优，适用于内部服务
RS256/ES256(非对称加密)：使用私钥签名、公钥验证，更安全，适用于需要分发公钥的场景
如 JWT 由第三方服务颁发，需根据第三方服务使用的签名算法进行配置。
功能限制类
Q1：单个消费者最多可以配置多少个凭证?
A：单个消费者最多可以配置20个凭证，支持多种类型混合配置。
Q2：单个 API 最多可以绑定多少个消费者?
A：单个 API 最多可以绑定100个消费者。
Q3：OAuth 2.0支持哪些授权模式?
A：当前支持以下授权模式：
Client Credentials(客户端凭证模式)：适用于机器对机器(M2M)场景
Password(密码模式)：适用于可信客户端场景
Authorization Code(授权码模式)：适用于 Web 应用场景
暂不支持 Implicit(隐式模式)和 Refresh Token 流程。
错误处理类
Q1：调用 API 时返回401 Unauthorized 错误怎么办?
A：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"错误?
A：这表示 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"错误?
A：这表示网关无法从 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：生产环境如何管理认证凭证?
A：建议的管理实践：
1. 凭证轮换：定期更换凭证(如每季度更换一次)，降低凭证泄露风险
2. 有效期设置：为凭证设置合理的有效期(如1年)，避免永久有效凭证泄露后持续被滥用
3. 权限分离：为不同的业务系统创建不同的消费者，避免共用凭证
4. 监控告警：监控认证失败率，异常流量及时告警
5. 凭证存储：凭证信息存储在配置中心或密钥管理服务中，不要硬编码在代码中
6. 泄露应急：如凭证泄露，立即禁用或删除该凭证，并创建新凭证
Q2：如何实现多环境(开发、测试、生产)的认证隔离?
A：建议采用以下方案：
1. 方案1：多网关实例
为开发、测试、生产环境分别创建独立的网关实例
每个实例配置独立的消费者和凭证
环境间完全隔离，互不影响
2. 方案2：单网关实例+多消费者
使用单个网关实例
为不同环境创建不同的消费者(如"开发消费者"、"生产消费者")
创建不同的 API，分别绑定不同的消费者
通过 API 访问地址区分环境(如 /dev/api、/prod/api)
建议使用方案1，环境隔离更彻底，更安全。
Q3：如何设计多租户场景的认证方案?
A：对于 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. 计费与配额：基于消费者维度进行流量统计和限流，实现租户级别的计费与配额管理
参数	是否必填	说明
消费者名称	是	消费者的名称，支持中文、英文、数字、下划线，长度1-60字符。
所属消费者组	否	消费者所属的消费者组。
密钥	否	消费者绑定的密钥。
描述	否	消费者的功能描述，最多200字符。
认证策略

本页目录：

操作场景

前置条件

操作步骤

创建消费者

步骤1：进入消费者列表页

步骤2：配置消费者信息

步骤3：完成创建

为消费者添加认证凭证

步骤1：进入消费者详情页

步骤2：添加凭证

认证方式1：API Key

配置参数

使用方式

认证方式2：JWT

配置参数

使用方式

认证方式3：OAuth 2.0

配置参数

使用方式

认证方式4：OIDC

配置参数

使用方式

免认证方式

为 API 配置认证策略

步骤1：进入 API 配置页

步骤2：选择认证方式

步骤3：保存配置

管理消费者凭证

查看凭证列表

禁用凭证

启用凭证

删除凭证

更新凭证

结果验证

验证 API Key 认证

验证 JWT 认证

验证 OAuth 2.0认证

验证 OIDC 认证

注意事项

常见问题

配置使用类

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

Q2：单个消费者可以配置多个凭证吗?

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

Q4：JWT 的签名算法如何选择?

功能限制类

Q1：单个消费者最多可以配置多少个凭证?

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

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

错误处理类

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

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

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

实践教程类

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

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

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