操作场景
消费者密钥是客户端应用安全调用 AI 网关服务的核心凭证。当企业或开发者通过微服务 TSF AI 网关整合与调度后端 AI 能力时，消费者密钥为不同的客户端（如业务应用、移动 App 或第三方服务）创建唯一的身份认证凭据，用于这些客户端在调用网关 API 时的身份鉴权与访问控制。
为确保敏感密钥信息的安全，微服务 TSF AI 网关与腾讯云密钥管理系统（KMS）深度集成，实现密钥的全生命周期加密存储。KMS 使用经过第三方认证的硬件安全模块（HSM）来生成和保护密钥，确保包括腾讯云在内的任何人都无法获取您的明文主密钥，满足严格的合规性要求。通过集中化管理，本功能旨在强化安全管控，杜绝明文泄露和未授权访问风险，同时简化密钥的创建、更新、禁用、删除等运维流程。
创建密钥并将密钥绑定至消费者后（单个消费者支持绑定多种类型的密钥，一个密钥最多绑定给一个消费者），还需在模型 API 或 MCP 服务上配置相应的认证策略，才能完成访问控制的完整链路。
本文档指导您如何在 AI 网关中为消费者创建密钥（认证凭证）。
前提条件
操作步骤
查看密钥列表
1. 登录微服务平台控制台 ，在左侧导航栏选择 AI 网关进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的“ID”，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击密钥管理，进入密钥列表页。
4. 在页面顶部，单击消费者密钥页签。
5. 列表页将展示所有已创建的消费者密钥，包括密钥名称、类型、状态和生成方式等信息。您可以在此进行新建、编辑或删除等操作。
6. 当密钥状态为“已启用”时，删除操作将置灰不可用，系统会提示“请先禁用该密钥”。
新建密钥
1. 在消费者密钥列表页，单击新建。
2. 在“新建密钥”窗口中，配置以下密钥公共基础参数：
参数 | 是否必填 | 说明 |
密钥名称 | 是 | 2-60个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。 |
密钥凭证类型 | 是 | 选择凭证类型：API Key / JWT / OAuth 2.0 / OIDC。不同类型对应的配置项不同，详见下一步操作。 API Key 是最简单的认证方式，适用于内部服务或可信客户端。 JWT（JSON Web Token）适用于需要传递用户身份信息的场景，由客户端自行签发 Token 并在请求中携带。 OAuth 2.0 适用于需要接入第三方 OAuth 服务的场景，由客户端使用 Client ID/Secret 换取 Token 后携带访问。 OIDC（OpenID Connect）是基于 OAuth 2.0 的身份认证协议，适用于需要用户身份认证的场景。 |
描述 | 否 | 密钥的标识描述信息，最长可输入200个字符。 |
3. 填写凭证具体配置参数
3.1 密钥凭证类型：API Key
参数 | 是否必填 | 说明 |
生成方式 | 是 | 自定义：手动输入密钥值（消费者密钥为凭证内容） |
| | 密钥管理系统（KMS凭据）：关联腾讯云KMS中的凭据。需填写“凭据名称”和“凭据版本”，若无 KMS 凭证，则可以单击“新建凭证”跳转新建 |
| | 自动生成：网关自动生成随机的 API key |
凭证内容 | 是 | 8-60 个字符，支持英文大小写、数字及符号（"-"、"_"、"="），其中 "-"、"_" 不能作为首尾字符 |
说明：
API Key 一旦生成，请妥善保管，不要泄露给无关人员。
3.2 密钥凭证类型：JWT
参数 | 是否必填 | 说明 |
算法 | 是 | 选择 JWT 签名算法，如 HS256。 |
共享密钥 | 是 | 填写用于签发和验证 JWT 的共享密钥。 |
消费者标识 | 是 | 客户端自签 JWT 时把 iss 设为该值，网关按此反查消费者。建议使用业务可读名（如组织名 / 邮箱）。 |
3.3 密钥凭证类型：OAuth 2.0
参数 | 是否必填 | 说明 |
客户端 ID | 是 | OAuth 客户端 ID。 |
客户端密钥 | 是 | OAuth 客户端密钥。 |
3.4 密钥凭证类型：OIDC
参数 | 是否必填 | 说明 |
客户端 ID | 是 | OIDC 客户端 ID。 |
客户端密钥 | 是 | OIDC 客户端密钥。 |
签发者地址 | 是 | 身份提供商（IdP）签发地址，用于发现 OIDC 配置，如 https://example.com/oidc。 |
消费者标识 Claim 值 | 是 | IdP token 中用户的 claim 值（如 sub/email），运行时用于反查对应消费者，如 user@example.com。 |
4. 完成创建：单击确定完成密钥创建。新建的密钥将展示在消费者密钥列表中。
密钥绑定消费者
消费者与密钥为一对多关系，一个消费者可以绑定多个密钥，一个密钥只可以绑定一个消费者。您可以为密钥绑定一个消费者。
1. 在消费者密钥列表页，单击目标密钥的“ID/名称”，进入详情页
2. 单击添加资源，在“新增资源”弹窗中，左侧“请选择消费者”区域会列出所有可选的消费者，您可以通过搜索框快速查找。
3. 在左侧列表中，勾选一个需要绑定到该密钥的消费者，被选中的消费者会出现在右侧“已选择”列表中。
4. 如需移除消费者，可在右侧“已选择”列表中，单击某个消费者条目右侧的 × 图标，可将其从本组关联关系中移除，或直接选中新的消费者。
5. 调整完毕后，单击确定保存关联关系。
查看密钥详情
1. 在消费者密钥列表页，单击目标密钥的“ID/名称”。
2. 进入密钥详情页，您可以查看：
基本信息：包括密钥 ID、名称、类型、状态、创建时间等。
已绑定消费者：展示当前密钥已关联的消费者信息。
编辑密钥
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的编辑；或在密钥详情页右上角单击编辑。
2. 在编辑窗口中，支持修改密钥的名称和描述（备注）信息。
3. 单击确定保存修改。
说明：
API Key 凭证创建后不可修改，如需更换请删除后重新创建。
启用/禁用密钥
消费者密钥只有在启用状态下才可以生效，这意味着当密钥处于关闭或未激活状态时，AI 网关将无法识别或使用该密钥进行任何操作，因此在使用前务必确认密钥是否已正确启用。
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的禁用按钮后，密钥处于“已禁用”状态， AI 网关将无法识别或使用该密钥进行任何操作。
2. 启用操作需要在目标密钥处于“已禁用”情况下：单击启用，密钥将处于“启用”状态。
删除密钥
1. 在消费者密钥列表页，找到目标密钥，单击其操作列下的禁用按钮后，才可以进行删除操作，等待密钥禁用后，单击删除即可。
2. 系统将进行删除前的依赖关系校验：
若密钥已解除所有关联（消费者密钥需解除所有消费者关联），则弹窗直接显示密钥信息，单击确定即可删除。
若密钥仍存在关联资源，弹窗会提示“存在未解除的依赖关系”并列出具体依赖项。您需要先解除所有依赖关系后，单击重新检查，校验通过后方可删除。
注意事项：
删除密钥是不可逆操作，请谨慎操作。
KMS 凭据状态变化：如果您在腾讯云 KMS 控制台中修改了某个凭据，AI 网关为保障业务连续性，会短暂继续使用缓存的旧凭证内容（默认缓存时间约5分钟）。建议您在 KMS 上创建新版本的凭据，并在网关中关联新凭据后，再删除旧的 API Key 版本，以确保变更及时生效。
为了增加密钥的高可用性，建议您配置多个凭证，避免某个凭证被禁用后，消费者不可用导致事故发生。
凭证安全：API Key、共享密钥、客户端密钥等凭证信息务必妥善保管，不要提交到代码仓库或公开渠道。
凭证轮换：建议定期更换凭证，降低凭证泄露风险。
后续操作
创建消费者密钥后，需要在模型 API 或 MCP 服务上配置认证策略，声明该服务接受的认证方式及校验规则，详情请参见：
配置模型 API 认证策略。
配置 MCP 服务 访问控制。
常见问题
配置使用类
Q1：如何选择合适的认证方式?
根据您的实际场景选择：
API Key：简单场景，适用于内部服务或可信客户端，配置简单，性能最优。
JWT：需要传递用户身份信息，支持自定义 Claims，适用于微服务间调用。
OAuth 2.0：需要接入第三方 OAuth 服务，支持标准 OAuth 流程。
OIDC：需要用户身份认证，支持 SSO（单点登录）。
Q2：单个消费者可以配置多个凭证吗?
可以。单个消费者支持同时配置多种类型的凭证，例如：
凭证1：API Key 类型。
凭证2：JWT 类型。
凭证3：OAuth 2.0类型。
客户端可以根据实际情况选择使用哪种凭证访问 API。
Q3：JWT 的签名算法如何选择?
HS256（对称加密）：使用密钥（Secret）进行签名和验证，配置简单，性能最优，适用于内部服务。
RS256/ES256（非对称加密）：使用私钥签名、公钥验证，更安全，适用于需要分发公钥的场景。
如 JWT 由第三方服务颁发，需根据第三方服务使用的签名算法进行配置。
功能限制类
Q1：单个消费者最多可以配置多少个密钥凭证?
单个消费者最多可以配置20个凭证，支持多种类型混合配置。
Q2：OAuth 2.0支持哪些授权模式?
当前支持以下授权模式：
Client Credentials（客户端凭证模式）：适用于机器对机器（M2M）场景。
Password（密码模式）：适用于可信客户端场景。
Authorization Code（授权码模式）：适用于 Web 应用场景。
暂不支持 Implicit（隐式模式）和 Refresh Token 流程。
实践教程类
Q1：生产环境如何管理认证凭证?
建议的管理实践：
1. 凭证轮换：定期更换凭证（如每季度更换一次），降低凭证泄露风险。
2. 有效期设置：为凭证设置合理的有效期（如1年），避免永久有效凭证泄露后持续被滥用。
3. 权限分离：为不同的业务系统创建不同的消费者，避免共用凭证。
4. 监控告警：监控认证失败率，异常流量及时告警。
5. 凭证存储：凭证信息存储在配置中心或密钥管理服务中，不要硬编码在代码中。
6. 泄露应急：如凭证泄露，立即禁用或删除该凭证，并创建新凭证。
