API 密钥是用于验证请求身份的机密凭据。服务账户是供应用或自动化工作负载使用的非人类身份。服务账户可以拥有 API 密钥:在同一套身份验证机制中,服务账户提供身份,密钥提供凭据。
个人开发时,请使用您自己的项目密钥。如果应用或自动化任务需要独立的权限和生命周期,请使用服务账户。通过管理 API 管理组织时,请使用管理 API 密钥。
选择合适的身份
| 工作负载 | 身份和凭据 | 选择原因 |
|---|---|---|
| 个人在本地进行开发或探索 | 您的用户账户和项目 API 密钥 | 发起请求时使用的是您在项目中的访问权限。 |
| 已部署的应用、定时作业或 CI 工作流 | 项目服务账户及其 API 密钥 | 工作负载拥有独立于开发者个人的身份。 |
| 使用 OpenAI 支持的身份提供商的工作负载 | 配置了工作负载身份联合的项目服务账户 | 工作负载无需存储长期有效的 OpenAI API 密钥即可完成身份验证。 |
| 用于创建项目或管理项目服务账户及密钥的自动化任务 | 管理 API 密钥 | 管理组织需要使用专门的管理端点和权限。 |
使用用户密钥发起请求时,适用的是密钥所有者的访问权限。请勿让整个团队共用一名开发者的密钥,也不要将该开发者的个人身份用作生产应用的永久身份。
每个服务账户都属于一个项目。请在项目内为每个工作负载分配所需的身份和访问权限。为不同应用或环境分别创建项目,可以隔离各自的资源、成员和用量。如果只需区分同一项目中的工作负载,可以分别创建服务账户,无需另建项目。
了解权限和范围
API 密钥能执行哪些操作,取决于密钥本身及其所有者的权限。设置密钥的权限范围可以限制密钥能执行的操作,但无法授予用户或服务账户本身没有的权限。即使密钥未设置范围限制,也只能在其所有者的有效权限内使用。
仅向服务账户分配其工作负载所需的角色,然后根据需要限制其密钥的权限范围。有关授权模型,请参阅权限和角色。如需了解如何通过配置创建身份、分配自定义角色并签发限定权限范围的密钥,请参阅使用 Terraform 配置服务账户。
管理 API 密钥与项目工作负载密钥的用途不同。请将管理凭据保存在负责创建和管理资源的可信服务中。应用发起模型请求时,应使用项目服务账户的凭据。
自动管理项目和密钥
如果您的应用需要为客户创建项目,使用项目服务账户可以让每个工作负载拥有独立的身份,无需依赖运行配置流程的开发者。负责配置的服务使用管理 API 来管理项目及其服务账户,配置完成的应用则使用自己的项目凭据。
相关管理操作如下:
| 操作 | 用途 |
|---|---|
| 创建项目 | 创建工作负载的资源和服务账户所属的项目。 |
| 创建服务账户 | 在该项目中为工作负载创建身份。使用 create_service_account_only 选项时,只创建服务账户,不分配默认角色,也不生成初始 API 密钥。 |
| 创建服务账户 API 密钥 | 为现有服务账户签发密钥,并按需设置密钥的权限范围和到期时间。 |
| 管理项目 API 密钥 | 列出、检索、更新或撤销现有的项目密钥,包括服务账户密钥。 |
项目 API 密钥管理端点不支持代其他用户创建归其个人所有的项目密钥。如需通过程序创建密钥,请使用服务账户,并调用相应的密钥创建端点。
创建服务账户时,如果不分配默认角色,该账户不会自动获得发起模型请求的权限。请先分配所需权限,再使用该账户的凭据。创建密钥时也必须遵守组织和项目的密钥策略,服务账户无法绕过这些策略。
管理凭据的生命周期
API 仅在创建服务账户密钥时返回完整的密钥值。请将密钥保存在机密管理工具中,并在服务器端将其提供给工作负载。切勿在浏览器代码、移动应用、版本控制系统、日志或返回给客户的响应中包含密钥。
请根据组织和项目的策略设置到期时间。轮换密钥时,先签发新密钥,再更新工作负载以使用新密钥,确认工作负载运行正常后再撤销旧密钥。更换密钥时,服务账户可以继续使用原有身份。
工作负载的职责发生变化时,请重新审查其访问权限。停用工作负载时,请撤销其凭据。有关密钥治理和到期策略,请参阅生产环境 API 密钥指南。如需在不存储 API 密钥的情况下完成身份验证,请参阅工作负载身份联合。