Azure Key Vault

概览

本指南会带你完成将 Azure Key Vault 配置为 CrewAI Platform 组织的密钥 provider 的全过程，使用的是 带 client secret 的 Microsoft Entra App Registration。完成后，CrewAI Platform 就能够读取 Azure Key Vault 中存放的密钥，并在运行时将其注入为环境变量值。

前提条件

第 1 步 - 创建 App Registration

App Registration 是 CrewAI Platform 在 Microsoft Entra 侧进行认证时使用的身份。

在 Microsoft Entra portal 中，进入 App registrations 并点击 New registration。

Name: crewai-secrets-reader
Supported account types: Accounts in this organizational directory only (Single tenant)。
保留 Redirect URI 为空。

点击 Register。记下 App overview blade 上的 Application (client) ID 和 Directory (tenant) ID - 第 4 步会把它们填入 CrewAI Platform。

完整细节请参见 Microsoft 文档：Register an application with the Microsoft identity platform。

第 2 步 - 创建 Client Secret

在 App Registration 上，进入 Certificates & secrets → Client secrets → New client secret。

Description: crewai-platform
Expires: 选择一个与轮换策略一致的时长（Microsoft 上限为 24 个月）。

点击 Add。立即复制 Value 列 - 离开页面后它将无法再次显示。

第 3 步 - 授予 App Registration 访问 Key Vault 的权限

CrewAI Platform 需要读取你的 Key Vault 中的 secrets。你可以使用两种 scope - 为了简单可选 vault-wide，为了最小权限可选 per-secret。

Vault-wide (simpler)

在 Key Vault console 中打开目标 vault，然后进入 Access control (IAM) → Add → Add role assignment。

Role: Key Vault Secrets User
Assign access to: User, group, or service principal
Members: 搜索并选择你的 App Registration（crewai-secrets-reader）。

点击 Review + assign。

或者通过 Azure CLI：

az role assignment create \
  --assignee <APPLICATION_CLIENT_ID> \
  --role "Key Vault Secrets User" \
  --scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)

Per-secret (least privilege)

在单个 secret 级别授予该 role。对 CrewAI Platform 需要访问的每个 secret 重复：

az role assignment create \
  --assignee <APPLICATION_CLIENT_ID> \
  --role "Key Vault Secrets User" \
  --scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)

第 4 步 - 在 CrewAI Platform 中添加凭据

在 CrewAI Platform 中，进入 Settings → Secret Provider Credentials，然后点击 Add Credential。

填写表单：

Name: 描述性名称，例如 azure-prod。
Provider: Azure Key Vault。
Key Vault URL: vault 的 DNS hostname，例如 https://my-vault.vault.azure.net。
Tenant ID: 第 1 步中的 Microsoft Entra Directory (tenant) ID。
Client ID: 第 1 步中的 App Registration Application (client) ID。
Client Secret: 第 2 步中复制的 Value。 -（可选）勾选 Set as default credential for this provider。环境变量如果引用 Azure secrets 但没有显式指定凭据，就会使用默认凭据。

点击 Create。

第 5 步 - 在 Azure Key Vault 中至少创建一个 Secret

如果你还没有在 Key Vault 中创建 secrets，请现在创建一个，以便在第 6 步验证连接。

在 Key Vault console 中，进入 Objects → Secrets → Generate/Import。

Upload options: Manual
Name: 例如 openai-api-key
Secret value: 粘贴你的 secret value
其余保持默认。

点击 Create。

或者通过 Azure CLI：

az keyvault secret set \
  --vault-name <VAULT_NAME> \
  --name openai-api-key \
  --value "sk-your-actual-key"

完整细节请参见 Microsoft 文档：Set and retrieve a secret。

第 6 步 - 测试连接

回到 CrewAI Platform，在 Secret Provider Credentials 页面找到你刚创建的凭据，并点击 Test Connection。

成功提示会确认 CrewAI Platform 能够对 Microsoft Entra 进行认证，并从你的 vault 中读取 secrets。

如果测试失败，请检查最常见的原因：

症状	可能原因
`AADSTS7000215: Invalid client secret provided`	粘贴的 Client Secret 错误或已过期。重新创建 secret（第 2 步）并更新凭据。
`AADSTS700016: Application not found in the directory`	Tenant ID 或 Client ID 与 App Registration 不匹配。重新检查第 4 步。
`Forbidden — caller does not have permission`	App Registration 在 vault（或 per-secret）上缺少 Key Vault Secrets User role。重新检查第 3 步。
`Vault not found` / DNS errors	Key Vault URL 错误，或者你的 vault 使用了阻止公网访问的 private endpoints。请确认 host 能响应 `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`。
`Forbidden — request was not authorized`（vault 使用旧 access policies）	vault 尚未切换到 Azure RBAC。请在 vault 的 Access configuration 下把 permission model 设置为 Azure role-based access control，并重新授予第 3 步中的 role。

下一步

现在 Azure Key Vault 已连接，前往 Using the Secrets Manager，以：

为组织成员授予使用（或管理）Secrets Manager 的正确权限。
从 CrewAI Platform 环境变量中引用你的 Azure secrets。

如果你想要rotation-aware 的密钥，并且希望在不重新部署的情况下传播，请切换到 Azure Workload Identity Federation - 同一个 vault，不需要轮换 client secret，密钥会在每次 kickoff 时获取。

Screenshot Reference

上面的占位图对应如下文件：

01-register-app.png - Azure portal 的 “Register an application” 表单，已填入 crewai-secrets-reader。
02-create-client-secret.png - App Registration → Certificates & secrets → Client secrets，显示刚创建的 secret 行（Value 列在被遮蔽前高亮）。
03-grant-vault-rbac.png - Key Vault → Access control (IAM) → Add role assignment，已选择 Key Vault Secrets User 并将 App Registration 设为 member。
04-per-secret-rbac.png - 同一个面板，但作用范围限定到单个 secret resource（可选的最小权限路径）。
05-amp-add-credential-form-azure.png - CrewAI Platform 的 “Add Secret Provider Credential” 表单：Provider = Azure Key Vault，五个字段全部填好。
06-create-secret.png - Azure Key Vault 的 “Create a secret” 面板，已填入 openai-api-key 和一个值。
07-test-connection-success.png - 在凭据上点击 Test Connection 后，CrewAI Platform 的成功 toast / row state。