如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为 Microsoft Azure 配置工作负载身份联合

您可以在以下两种场景中使用 Microsoft Azure 作为工作负载身份提供方:

  • Azure 托管标识:使用 Microsoft Entra ID 为托管标识签发的访问令牌换取短期 OpenAI 访问令牌。
  • AKS:使用 Azure Kubernetes 服务(AKS)的投射服务账户令牌换取短期 OpenAI 访问令牌。

Azure 托管标识

在 Azure 上运行的工作负载可以使用 Azure 托管标识请求 Microsoft Entra 令牌,无需存储长期有效的机密。在 OpenAI 工作负载身份联合中,托管标识令牌用作主体令牌。OpenAI 会先验证此令牌,再签发 OpenAI 访问令牌。

设置 Azure 托管标识

在 Microsoft Entra 中注册应用程序,或使用现有的应用程序注册来表示 OpenAI 应信任的令牌受众。配置该应用程序的应用程序 ID URI。工作负载向 Azure 实例元数据服务(IMDS)请求令牌时,会将此 URI 用作 resource 的值。签发的令牌中,aud 声明的值也是此 URI。有关 Microsoft 端的设置步骤,请参阅 Microsoft Entra 指南中的创建新的 Entra ID 应用程序和服务主体。

在 Microsoft Entra ID 中配置的应用程序 ID URI、IMDS 的 resource 参数、签发的令牌中的 aud 声明以及 OpenAI 工作负载身份提供方的受众必须完全一致。

创建托管标识,然后将其分配给运行应用程序的 Azure 资源,例如虚拟机。该资源必须能够在运行时调用 IMDS。有关 Azure 端的设置详情,请参阅 Microsoft 的托管标识概述,并查阅相应 Azure 资源文档中有关分配标识的说明。

获取 Azure 托管标识令牌

从已分配托管标识的 Azure 资源向 IMDS 请求令牌,并将应用程序 ID URI 用作 resource 参数。OpenAI 在令牌交换时将此令牌用作主体令牌,并签发 OpenAI 访问令牌。

APPLICATION_ID_URI="api://<application-client-id>"

TOKEN=$(curl -sS -G -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token" \
  --data-urlencode "api-version=2018-02-01" \
  --data-urlencode "resource=${APPLICATION_ID_URI}" \
  | jq -r .access_token)
export TOKEN

如果该资源有多个用户分配的托管标识,请添加 client_id、object_id 或 msi_res_id 查询参数,指定您要使用的托管标识。有关 IMDS 令牌请求参数,请参阅 Microsoft 文档在虚拟机上使用托管标识获取访问令牌。

检查令牌

配置工作负载身份联合之前,请将 Microsoft Entra 令牌导出为环境变量 TOKEN,然后在本地运行以下脚本以检查令牌中的声明:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

此命令仅解码 JWT 载荷,不验证令牌签名。请使用本地解码器处理生产环境的令牌,避免将这些令牌粘贴到第三方工具中。

解码后的 Microsoft Entra ID 托管标识令牌类似于以下示例:

{
  "iss": "https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0",
  "aud": "api://00000000-1111-2222-3333-444444444444",
  "tid": "11111111-2222-3333-4444-555555555555",
  "appid": "22222222-3333-4444-5555-666666666666",
  "oid": "33333333-4444-5555-6666-777777777777",
  "sub": "33333333-4444-5555-6666-777777777777",
  "xms_mirid": "/subscriptions/<subscription-id>/resourcegroups/my-resource-group/providers/Microsoft.Compute/virtualMachines/openai-wif-vm",
  "iat": 1716235422,
  "exp": 1716239022
}

核对您准备在 OpenAI 中配置的声明:

  • iss:使用令牌中签发者的确切值。签发者可能是 https://login.microsoftonline.com/<tenant-id>/v2.0,但不要假定它一定包含这个后缀。
  • aud:必须与应用程序 ID URI、IMDS 的 resource 参数以及 OpenAI 工作负载身份提供方的受众一致。
  • tid:Microsoft Entra 租户 ID。
  • appid:如果存在,此声明表示托管标识的应用程序 ID(客户端 ID)。
  • iat 和 exp:检查令牌从签发到过期的完整有效期,即 exp - iat,单位为秒。

对于 Codex,请将提供方的 max_assertion_lifetime_seconds 设为经批准的上限,并确保该上限覆盖签发者预期的令牌有效期范围。不要使用令牌的剩余有效时间,也不要假定所有 Entra 令牌的有效期都是一小时。Microsoft 文档说明了访问令牌的有效期会有所不同,且 Microsoft 不支持配置托管标识令牌的有效期。

托管标识令牌也可能包含 azp、oid、sub 或 xms_mirid 等声明。请以解码后的令牌为准,选择能准确标识您所信任的托管标识和资源边界的声明。

根据解码后的载荷,将收到的令牌与 OpenAI 中配置的签发者、受众和映射值进行比对。在交换令牌之前,检查 iss、aud、tid 以及托管标识相关声明即可发现大多数配置问题。

配置工作负载身份联合

在 OpenAI 中为 Microsoft Entra ID 签发者创建工作负载身份提供方,然后添加服务账户映射,用于匹配托管标识令牌中取值稳定的声明。

先配置工作负载身份提供方,再创建服务账户映射。

设置工作负载身份提供方

  1. 创建工作负载身份提供方。将名称设为唯一值,例如 azure-managed-identity-prod。填写描述,例如 Production Azure managed identity workloads,以便管理员识别该提供方。

  2. 设置签发者和受众。先获取一个托管标识令牌样本并检查其中的声明,再将 OIDC 签发者 URL 设为令牌中 iss 声明的确切值。例如,签发者可能是 https://login.microsoftonline.com/<tenant-id>/v2.0。将受众设为您配置的 Microsoft Entra 应用程序 ID URI,例如 api://<application-client-id>。该值必须与令牌的 aud 声明一致。

  3. 使用 Microsoft Entra 的令牌验证机制。保持使用上传的 JWKS 验证令牌选项关闭。OpenAI 使用 Microsoft Entra 签发者元数据和 JWKS 验证托管标识令牌。

  4. 如果映射需要派生属性,请添加属性转换。例如,输入 managed_identity_client_id 并使用表达式 assertion.appid,即可根据托管标识的应用程序 ID(客户端 ID)声明创建 openai.managed_identity_client_id。控制面板会自动添加 openai. 前缀。如果原始令牌声明本身以 openai. 开头,除非配置了相应的转换,否则系统在匹配 openai. 映射键时会忽略该声明。

设置服务账户映射

  1. 创建服务账户映射。将名称设为在该工作负载身份提供方内唯一的值,例如 vm-openai-wif。填写描述,例如 Production VM Azure managed identity workload,说明哪个工作负载可以使用此映射。

  2. 匹配取值稳定的托管标识声明。为每个必须匹配的声明添加一行,填写键和值。如果令牌包含 appid,请将键设为 appid,将值设为托管标识的客户端 ID。appid 声明标识托管标识的应用程序 ID(客户端 ID),在将映射绑定到特定托管标识时,通常是取值最稳定的声明。如果令牌不包含 appid,请从解码后的令牌中选择其他取值稳定的声明,例如 azp、oid、sub 或 xms_mirid。要将映射绑定到单个租户,请另加一行,将键设为 tid,将值设为 Microsoft Entra 租户 ID。请解码从 IMDS 获取的令牌样本,并选择对您信任的托管标识和资源而言取值稳定的声明。

  3. 选择 OpenAI 目标。将项目设为目标服务账户所属的 OpenAI 项目。将服务账户设为 Azure 工作负载可以使用的 OpenAI 服务账户,例如 azure-managed-identity-prod-openai-wif。

  4. 按需缩小 API 权限范围。选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限。如果将权限留空,则不会为工作负载身份联合添加额外的范围限制。使用该令牌发起的请求仍按所映射服务账户的权限进行授权。

在代码中使用令牌

配置 OpenAI SDK 客户端,使其从 IMDS 请求 Azure 托管标识令牌,并用该令牌换取 OpenAI 签发的访问令牌。

将 OPENAI_WIF_AUDIENCE 设为已配置为工作负载身份提供方受众的 Microsoft Entra 应用程序 ID URI。SDK 会为该受众请求托管标识令牌,用它换取 OpenAI 签发的访问令牌,然后使用 OpenAI 令牌对 API 请求进行身份验证。

使用 Azure 托管标识令牌进行身份验证
import OpenAI from "openai";

const imdsEndpoint = "http://169.254.169.254/metadata/identity/oauth2/token";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;

if (!identityProviderId || !serviceAccountId || !audience) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID, OPENAI_SERVICE_ACCOUNT_ID, and OPENAI_WIF_AUDIENCE"
  );
}

function azureManagedIdentityTokenProvider(resource: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const url = new URL(imdsEndpoint);
      url.searchParams.set("api-version", "2018-02-01");
      url.searchParams.set("resource", resource);

      const clientId = process.env.AZURE_CLIENT_ID;
      if (clientId) {
        url.searchParams.set("client_id", clientId);
      }

      const response = await fetch(url, {
        headers: { Metadata: "true" },
      });

      if (!response.ok) {
        throw new Error(
          `Azure IMDS token request failed with status ${response.status}.`
        );
      }

      const body = await response.json();
      if (!body.access_token) {
        throw new Error("Azure IMDS did not return an access token.");
      }

      return body.access_token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: azureManagedIdentityTokenProvider(audience),
  },
});

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  input: "Say hello from Azure managed identity workload identity federation.",
});

console.log(response.output_text);

Microsoft Azure 最佳实践

  • 尽可能使用托管标识。与手动分发凭据相比,托管标识提供了更简单、更安全的身份验证方式。
  • 为不同的应用程序和环境分别使用独立的托管标识、Microsoft Entra 应用程序和 OpenAI 映射。避免在开发、预发布和生产工作负载之间共用同一标识。
  • 限制可接受的受众。仅配置 OpenAI 工作负载身份联合所需的受众。
  • 为不同的安全边界使用专用的 Microsoft Entra ID 应用程序。分别使用独立的应用程序有助于明确归属,也便于审计和管理访问权限。
  • 优先为各工作负载单独配置映射。匹配特定于工作负载的声明,避免使用适用于整个租户的宽泛属性。
  • 定期检查联合凭据配置。工作负载停用很久之后,遗留的联合凭据仍可能在无意中授予访问权限。
  • 将生产环境与非生产环境的标识分开。生产工作负载应使用独立的联合身份和 OpenAI 服务账户进行身份验证。