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

在以下任一场景中，将 Microsoft Azure 用作工作负载身份提供者：

Azure 托管标识： 将为托管标识颁发的 Microsoft Entra ID 访问令牌交换为短期 OpenAI 访问令牌。
AKS: 将投影的 Azure Kubernetes Service (AKS) 服务账号令牌交换为短期 OpenAI 访问令牌。

Azure 托管标识

Azure 托管标识允许 Azure 托管的工作负载请求 Microsoft Entra 令牌，而无需存储长期有效的机密。在 OpenAI 工作负载身份联合中，托管标识令牌是 OpenAI 在颁发 OpenAI 访问令牌之前验证的主体令牌。

设置 Azure 托管标识

创建或使用一个 Microsoft Entra 应用注册，以表示 OpenAI 应信任的令牌受众。将其 应用程序 ID URI；此 URI 是该 resource 值配置为您的工作负载从 Azure 实例元数据服务 (IMDS) 请求的值，该值将显示为颁发的令牌中的 aud 声明。有关 Microsoft 设置步骤，请参阅 Microsoft Entra 指南，了解如何创建新的 Entra ID 应用程序和服务主体.

在 Microsoft Entra ID 中配置的 Application ID URI、IMDS resource 参数、生成令牌的 aud 声明以及 OpenAI 工作负载身份提供者的受众必须全部匹配。

创建 a managed identity, then 分配该托管标识到运行您的应用程序的 Azure 资源（例如虚拟机）。该资源必须在运行时能够调用 IMDS。有关 Azure 设置的详细信息，请参阅 Microsoft 的托管标识概述以及用于分配标识的相关 Azure 资源文档。

获取 Azure 托管标识令牌

从分配了托管标识的 Azure 资源中，使用 Application ID URI 作为 resource 参数从 IMDS 请求令牌。此令牌是 OpenAI 用于交换 OpenAI 颁发的访问令牌的主体令牌。

1
2
3
4
5
6
7
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)

如果资源具有多个用户分配的托管标识，请为您要使用的托管标识添加 client_id, object_id, or msi_res_id 查询参数。Microsoft 在中记录了 IMDS 令牌请求参数使用虚拟机上的托管标识获取访问令牌.

验证令牌

在配置工作负载身份联合之前，请在本地解码一个示例令牌并检查其声明：

1
2
3
4
5
6
7
8
9
TOKEN="$TOKEN" python3 - <<'PY'
import base64
import json
import os

payload = os.environ["TOKEN"].split(".")[1]
payload += "=" * (-len(payload) % 4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2))
PY

解码后的 AWS 颁发 OIDC 令牌类似于：

解码后的 Microsoft Entra ID 托管标识令牌类似于：

1
2
3
4
5
6
7
8
9
10
11
{
  "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（如果存在）。

托管标识令牌还可以包含如下声明： azp, oid, sub, or xms_mirid. 请使用解码后的令牌作为事实来源，并选择能够标识您所信任的确切托管标识和资源边界的声明。

声明中显现。 iss, aud, tid, 并在交换令牌之前检查托管标识声明,

在 OpenAI 中为 AWS 账户颁发者创建工作负载身份提供商，然后添加与 AWS 颁发令牌中的稳定声明相匹配的服务账户映射。

在 OpenAI 中为 Microsoft Entra ID 颁发者创建一个工作负载身份提供商，然后添加一个与托管标识令牌中的稳定声明相匹配的服务账号映射。

设置工作负载身份提供商

创建工作负载身份提供商。

为一个唯一的值，例如 设置名称设置颁发者和受众。 azure-managed-identity-prod值。使用描述，例如 Production Azure managed identity workloads，以帮助管理员识别该提供商。
OIDC 颁发者 URL 设置 设置为启用出站身份联合时返回的 AWS 特定于账户的颁发者 URL。此值必须与令牌的 到令牌的 iss 声明的确切值。首先获取一个示例托管标识令牌并检查其声明。例如，颁发者可能是 https://login.microsoftonline.com/<tenant-id>/v2.0。将 为传递给 到你配置的 Microsoft Entra 应用程序 ID URI，例如 api://<application-client-id>。此值必须与令牌的 aud claim.
使用 Microsoft Entra 令牌验证。 保持禁用 使用上传的 JWKS 进行令牌验证 已禁用。OpenAI 使用 Microsoft Entra 颁发者元数据和 JWKS 来验证托管标识令牌。
如果需要派生映射属性，请添加属性转换。 For example, enter managed_identity_client_id with expression assertion.appid to create openai.managed_identity_client_id 来自托管标识应用程序/客户端 ID 声明。仪表板会将 openai. 前缀。对于已经以以下内容开头的原始令牌声明： openai. 映射键，已以 openai. 开头的原始令牌声明将被忽略，除非配置了匹配的转换。

设置服务账户映射

创建服务账户映射。 设置名称设置为在该工作负载身份提供商内唯一的值，例如 vm-openai-wif值。使用描述，例如 Production VM Azure managed identity workload，以说明哪个工作负载可以使用此映射。
匹配稳定的托管标识声明。 为每个必须匹配的 GitHub 声明添加一行键 and 值行，用于每个必须匹配的声明。如果令牌包含 appid，请设置键 to appid and 值到托管标识客户端 ID。 appid 声明标识了托管标识的应用程序/客户端 ID，并且通常是将映射绑定到特定托管标识的最稳定声明。如果你的令牌不包含 appid, 请使用解码后令牌中的其他稳定声明，例如 azp, oid, sub, or xms_mirid. 要将映射绑定到单个租户，还需设置键 to tid and 值到 Microsoft Entra 租户 ID。从 IMDS 解码一个样本令牌，并使用对于您信任的托管标识和资源而言稳定的声明。
选择 OpenAI 目标。 设置项目指向拥有目标服务账户的 OpenAI 项目。将 服务账户 到 Azure 工作负载可以使用的 OpenAI 服务账户，例如 azure-managed-identity-prod-openai-wif.
根据需要缩小 API 权限范围。 选择适当的权限例如 api.model.request and api.vector_store.read 以进一步限制从此映射生成的访问令牌。将权限留空可避免添加特定于 WIF 的范围限制；该令牌仍会以映射的服务账户身份进行授权。

在代码中使用令牌

配置您的 OpenAI SDK 客户端，以从 IMDS 请求 Azure 托管标识令牌，并将其换取 OpenAI 颁发的访问令牌。

设置 OPENAI_WIF_AUDIENCE 到配置为 Workload Identity Provider 受众的 Microsoft Entra 应用程序 ID URI。SDK 会请求该受众的托管标识令牌，将其换取 OpenAI 颁发的访问令牌，并使用该 OpenAI 令牌对 API 请求进行身份验证。

使用 Azure 托管标识令牌进行身份验证

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
import OpenAI from "openai";
import type { SubjectTokenProvider } from "openai/auth";

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): SubjectTokenProvider {
  return {
    tokenType: "jwt",
    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()) as { access_token?: string };
      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-4.1-mini",
  input: "Say hello from Azure managed identity workload identity federation.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

from openai import OpenAI
from openai.auth import SubjectTokenProvider

IMDS_ENDPOINT = "http://169.254.169.254/metadata/identity/oauth2/token"


def azure_managed_identity_token_provider(resource: str) -> SubjectTokenProvider:
    def get_token() -> str:
        params = {
            "api-version": "2018-02-01",
            "resource": resource,
        }

        client_id = os.environ.get("AZURE_CLIENT_ID")
        if client_id:
            params["client_id"] = client_id

        request = Request(
            f"{IMDS_ENDPOINT}?{urlencode(params)}",
            headers={"Metadata": "true"},
        )

        with urlopen(request, timeout=10) as response:
            body = json.loads(response.read().decode("utf-8"))

        token = body.get("access_token", "")
        if not token:
            raise RuntimeError("Azure IMDS did not return an access token.")
        return token

    return {"token_type": "jwt", "get_token": get_token}

client = OpenAI(
    workload_identity={
        "identity_provider_id": os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        "service_account_id": os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
        "provider": azure_managed_identity_token_provider(
            os.environ["OPENAI_WIF_AUDIENCE"]
        ),
    },
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input="Say hello from Azure managed identity workload identity federation.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/auth"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

const azureIMDSEndpoint = "http://169.254.169.254/metadata/identity/oauth2/token"

type azureManagedIdentityTokenProvider struct {
	resource string
}

func (p azureManagedIdentityTokenProvider) TokenType() auth.SubjectTokenType {
	return auth.SubjectTokenTypeJWT
}

func (p azureManagedIdentityTokenProvider) GetToken(ctx context.Context, httpClient auth.HTTPDoer) (string, error) {
	values := url.Values{}
	values.Set("api-version", "2018-02-01")
	values.Set("resource", p.resource)
	if clientID := os.Getenv("AZURE_CLIENT_ID"); clientID != "" {
		values.Set("client_id", clientID)
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, azureIMDSEndpoint+"?"+values.Encode(), nil)
	if err != nil {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-managed-identity",
			Message:  "failed to build Azure IMDS token request",
			Cause:    err,
		}
	}
	req.Header.Set("Metadata", "true")

	resp, err := httpClient.Do(req)
	if err != nil {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-managed-identity",
			Message:  "failed to request Azure managed identity token",
			Cause:    err,
		}
	}
	defer resp.Body.Close()

	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-managed-identity",
			Message:  fmt.Sprintf("Azure IMDS token request failed with status %d", resp.StatusCode),
		}
	}

	var body struct {
		AccessToken string `json:"access_token"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-managed-identity",
			Message:  "failed to decode Azure IMDS token response",
			Cause:    err,
		}
	}
	if body.AccessToken == "" {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-managed-identity",
			Message:  "Azure IMDS did not return an access token",
		}
	}

	return body.AccessToken, nil
}

func main() {
	audience := os.Getenv("OPENAI_WIF_AUDIENCE")
	if audience == "" {
		log.Fatal("Set OPENAI_WIF_AUDIENCE")
	}

	client := openai.NewClient(
		option.WithWorkloadIdentity(auth.WorkloadIdentity{
			IdentityProviderID: os.Getenv("OPENAI_IDENTITY_PROVIDER_ID"),
			ServiceAccountID:   os.Getenv("OPENAI_SERVICE_ACCOUNT_ID"),
			Provider: azureManagedIdentityTokenProvider{
				resource: audience,
			},
		}),
	)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModelGPT4_1Mini,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Say hello from Azure managed identity workload identity federation."),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.openai.auth.SubjectTokenProvider;
import com.openai.auth.SubjectTokenType;
import com.openai.auth.WorkloadIdentity;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpClient;
import com.openai.errors.SubjectTokenProviderException;
import com.openai.models.ChatModel;
import com.openai.models.responses.ResponseCreateParams;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CompletableFuture;

public final class AzureManagedIdentityWorkloadIdentityExample {
    private static final String IMDS_ENDPOINT =
            "http://169.254.169.254/metadata/identity/oauth2/token";

    private AzureManagedIdentityWorkloadIdentityExample() {}

    static final class AzureManagedIdentityTokenProvider implements SubjectTokenProvider {
        private final String resource;

        AzureManagedIdentityTokenProvider(String resource) {
            this.resource = resource;
        }

        @Override
        public SubjectTokenType tokenType() {
            return SubjectTokenType.JWT;
        }

        @Override
        public String getToken(HttpClient httpClient, JsonMapper jsonMapper) {
            try {
                String query = "api-version=2018-02-01&resource="
                        + URLEncoder.encode(resource, StandardCharsets.UTF_8);
                String clientId = System.getenv("AZURE_CLIENT_ID");
                if (clientId != null && !clientId.isEmpty()) {
                    query += "&client_id="
                            + URLEncoder.encode(clientId, StandardCharsets.UTF_8);
                }

                HttpRequest request = HttpRequest.newBuilder()
                        .uri(URI.create(IMDS_ENDPOINT + "?" + query))
                        .header("Metadata", "true")
                        .GET()
                        .build();

                HttpResponse<String> response = java.net.http.HttpClient.newHttpClient()
                        .send(request, HttpResponse.BodyHandlers.ofString());
                if (response.statusCode() < 200 || response.statusCode() >= 300) {
                    throw new SubjectTokenProviderException(
                            "azure-managed-identity",
                            "Azure IMDS token request failed with status "
                                    + response.statusCode(),
                            null);
                }

                JsonNode body = jsonMapper.readTree(response.body());
                String token = body.path("access_token").asText();
                if (token.isEmpty()) {
                    throw new SubjectTokenProviderException(
                            "azure-managed-identity",
                            "Azure IMDS did not return an access token",
                            null);
                }

                return token;
            } catch (SubjectTokenProviderException e) {
                throw e;
            } catch (Exception e) {
                throw new SubjectTokenProviderException(
                        "azure-managed-identity",
                        "failed to request Azure managed identity token",
                        e);
            }
        }

        @Override
        public CompletableFuture<String> getTokenAsync(
                HttpClient httpClient, JsonMapper jsonMapper) {
            return CompletableFuture.supplyAsync(() -> getToken(httpClient, jsonMapper));
        }
    }

    public static void main(String[] args) {
        WorkloadIdentity workloadIdentity = WorkloadIdentity.builder()
                .identityProviderId(System.getenv("OPENAI_IDENTITY_PROVIDER_ID"))
                .serviceAccountId(System.getenv("OPENAI_SERVICE_ACCOUNT_ID"))
                .provider(new AzureManagedIdentityTokenProvider(
                        System.getenv("OPENAI_WIF_AUDIENCE")))
                .build();

        OpenAIClient client = OpenAIOkHttpClient.builder()
                .workloadIdentity(workloadIdentity)
                .build();

        ResponseCreateParams params = ResponseCreateParams.builder()
                .model(ChatModel.GPT_4_1_MINI)
                .input("Say hello from Azure managed identity workload identity federation.")
                .build();

        client.responses().create(params).output().stream()
                .flatMap(item -> item.message().stream())
                .flatMap(message -> message.content().stream())
                .flatMap(content -> content.outputText().stream())
                .forEach(outputText -> System.out.println(outputText.text()));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
require "json"
require "net/http"
require "openai"
require "uri"

class AzureManagedIdentityTokenProvider
  include OpenAI::Auth::SubjectTokenProvider

  IMDS_ENDPOINT = "http://169.254.169.254/metadata/identity/oauth2/token"

  def initialize(resource:)
    @resource = resource
  end

  def token_type
    OpenAI::Auth::TokenType::JWT
  end

  def get_token
    uri = URI(IMDS_ENDPOINT)
    params = {
      "api-version" => "2018-02-01",
      "resource" => @resource
    }
    params["client_id"] = ENV["AZURE_CLIENT_ID"] if ENV["AZURE_CLIENT_ID"]
    uri.query = URI.encode_www_form(params)

    request = Net::HTTP::Get.new(uri)
    request["Metadata"] = "true"

    response = Net::HTTP.start(uri.hostname, uri.port, read_timeout: 10) do |http|
      http.request(request)
    end

    unless response.is_a?(Net::HTTPSuccess)
      raise OpenAI::Errors::SubjectTokenProviderError.new(
        message: "Azure IMDS token request failed with status #{response.code}",
        provider: "azure-managed-identity"
      )
    end

    token = JSON.parse(response.body).fetch("access_token", "")
    if token.empty?
      raise OpenAI::Errors::SubjectTokenProviderError.new(
        message: "Azure IMDS did not return an access token",
        provider: "azure-managed-identity"
      )
    end
    token
  rescue JSON::ParserError, SystemCallError => e
    raise OpenAI::Errors::SubjectTokenProviderError.new(
      message: "Failed to request Azure managed identity token: #{e.message}",
      provider: "azure-managed-identity",
      cause: e
    )
  end
end

provider = AzureManagedIdentityTokenProvider.new(
  resource: ENV.fetch("OPENAI_WIF_AUDIENCE")
)

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
  identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),
  service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),
  provider: provider
)

client = OpenAI::Client.new(workload_identity: workload_identity)

response = client.responses.create(
  model: "gpt-4.1-mini",
  input: "Say hello from Azure managed identity workload identity federation."
)

puts(response.output_text)

Azure Kubernetes Service (AKS)

通过将 AKS 颁发的投影服务账户令牌换取短期 OpenAI 访问令牌，将 AKS 用作 Workload Identity Provider。

AKS 工作负载还可以使用 Azure Workload Identity 来获取附加到该工作负载的托管标识的 Microsoft Entra ID 访问令牌。在该配置中，OpenAI 会验证 Microsoft Entra 令牌，而不是投影的 Kubernetes 服务账户令牌。请使用以下步骤配置 OpenAI 工作负载身份联合： Azure 托管标识, 并按照 Microsoft 的文档配置 Azure Workload Identity。

设置 AKS

检索与 AKS 集群关联的 OIDC 颁发者 URL：

1
2
3
4
5
az aks show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "oidcIssuerProfile.issuerUrl" \
  --output tsv

如果颁发者 URL 为空，请为集群启用 AKS OIDC 颁发者。使用以下命令：

1
2
3
4
az aks update \
    --resource-group <resource-group> \
    --name <cluster-name> \
    --enable-oidc-issuer

您在 OpenAI 工作负载身份提供商中配置的颁发者必须与此颁发者 URL 以及投影的 EKS 服务账号令牌中的 iss 投影 AKS 服务账户令牌中的声明。

为需要调用 OpenAI API 的 EKS 工作负载使用一个 Kubernetes ServiceAccount 用于需要调用 OpenAI API 的 AKS 工作负载。如果您还没有服务账户，请创建一个：

kubectl create serviceaccount openai-wif --namespace default

使用 OpenAI 预期的受众和适合您工作负载的过期时间来配置投影服务账号令牌。OpenAI 会验证令牌的颁发者、签名、受众和过期时间。在此示例中，令牌文件挂载于 /var/run/secrets/tokens/token, 使用的受众为 https://api.openai.com/v1, 并在 3600 秒后过期。如果投影令牌受众与 OpenAI Workload Identity Provider 受众匹配，您可以使用不同的受众。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
apiVersion: v1
kind: Pod
metadata:
  name: openai-wif-app
  namespace: default
spec:
  serviceAccountName: openai-wif
  containers:
    - name: app
      image: my-image
      volumeMounts:
        - name: aks-sa-token
          mountPath: /var/run/secrets/tokens
          readOnly: true
  volumes:
    - name: aks-sa-token
      projected:
        sources:
          - serviceAccountToken:
              path: token
              audience: "https://api.openai.com/v1"
              expirationSeconds: 3600

验证令牌

在配置工作负载身份联合之前，请在本地解码一个示例投影服务账号令牌并检查其声明。在挂载了投影令牌的运行中的 Pod 上执行：

1
2
3
4
5
6
7
8
9
10
11
TOKEN=$(kubectl exec -n default openai-wif-app -- cat /var/run/secrets/tokens/token)

TOKEN="$TOKEN" python3 - <<'PY'
import base64
import json
import os

payload = os.environ["TOKEN"].split(".")[1]
payload += "=" * (-len(payload) % 4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2))
PY

解码后的 AWS 颁发 OIDC 令牌类似于：

解码后的 AKS 投影服务账户令牌类似于：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "iss": "https://eastus.oic.prod-aks.azure.com/11111111-2222-3333-4444-555555555555/22222222-3333-4444-5555-666666666666/",
  "aud": ["https://api.openai.com/v1"],
  "sub": "system:serviceaccount:default:openai-wif",
  "iat": 1716235422,
  "exp": 1716239022,
  "kubernetes.io": {
    "namespace": "default",
    "serviceaccount": {
      "name": "openai-wif",
      "uid": "11111111-2222-3333-4444-555555555555"
    }
  }
}

受众以及 OpenAI 工作负载身份提供商的受众。

iss: 必须与在 OpenAI Workload Identity Provider 中配置的 AKS 颁发者 URL 匹配。
aud: 必须与投影服务账户令牌受众以及 OpenAI Workload Identity Provider 受众匹配。
sub: 必须与您在服务账户映射中配置的 Kubernetes 服务账户主体匹配。

声明中显现。 iss, aud，且 sub 设置工作负载身份联合

在 OpenAI 中为 AWS 账户颁发者创建工作负载身份提供商，然后添加与 AWS 颁发令牌中的稳定声明相匹配的服务账户映射。

在 OpenAI 中为 AKS 颁发者创建一个 Workload Identity Provider，然后添加一个与投影令牌中的属性相匹配的服务账户映射。

设置工作负载身份提供商

创建工作负载身份提供商。

为一个唯一的值，例如 设置名称设置颁发者和受众。 azure-aks-prod值。使用描述，例如 Production AKS cluster, 以帮助管理员识别集群。
OIDC 颁发者 URL 设置 设置为启用出站身份联合时返回的 AWS 特定于账户的颁发者 URL。此值必须与令牌的 指向由 az aks show --query "oidcIssuerProfile.issuerUrl"返回的颁发者。此值必须与 iss 在已投射的 AKS 服务账号令牌中声明。设置 为传递给 与在 projected 服务账号令牌卷上配置的受众相同。在此示例中，该值为 https://api.openai.com/v1.
使用 AKS OIDC 发现。 保持禁用 使用上传的 JWKS 进行令牌验证 已禁用。OpenAI 使用 AKS 颁发者的 OIDC 发现元数据和 JWKS 来验证已投射的服务账号令牌。
如果需要派生映射属性，请添加属性转换。 For example, enter aks_subject with expression assertion.sub to create openai.aks_subject。控制台会应用 openai. 前缀。对于已经以以下内容开头的原始令牌声明： openai. 映射键，已以 openai. 开头的原始令牌声明将被忽略，除非配置了匹配的转换。

设置服务账户映射

创建服务账户映射。 设置名称设置为在该工作负载身份提供商内唯一的值，例如 default-openai-wif值。使用描述，例如 Default namespace AKS OpenAI API workload，以说明哪个工作负载可以使用此映射。
匹配 AKS 服务账号主体。 设置键 to sub and 值 to system:serviceaccount:default:openai-wif. 对于 AKS 服务账户，主体格式为 system:serviceaccount:<namespace>:<service-account-name>.

工作负载身份提供者将令牌限制为已配置的 AKS 颁发者。服务账号映射进一步将访问权限限制为指定的 Kubernetes 服务账号主体。
选择 OpenAI 目标。 设置项目指向拥有目标服务账户的 OpenAI 项目。将 服务账户 对应 AKS 工作负载可使用的 OpenAI 服务账号，例如 azure-aks-prod-openai-wif.
根据需要缩小 API 权限范围。 选择适当的权限例如 api.model.request and api.vector_store.read 以进一步限制从此映射生成的访问令牌。将权限留空可避免添加特定于 WIF 的范围限制；该令牌仍会以映射的服务账户身份进行授权。

在代码中使用令牌

配置您的 OpenAI SDK 客户端，使其读取已投射的 AKS 服务账号令牌，并将其换取 OpenAI 颁发的访问令牌。

使用已挂载的令牌路径（例如 /var/run/secrets/tokens/token, 作为 SDK Workload Identity Federation Provider 的主体令牌源。SDK 会将该 AKS 令牌交换为 OpenAI 颁发的访问令牌，并使用该 OpenAI 令牌对 API 请求进行身份验证。

以下示例使用自定义主体令牌提供者来初始化 OpenAI 客户端。该提供者从挂载的文件路径读取已投射的 AKS 服务账号令牌，并将其作为工作负载身份联合的主体令牌使用。

使用 AKS 投射的服务账号令牌进行身份验证

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import { readFile } from "node:fs/promises";
import OpenAI from "openai";
import type { SubjectTokenProvider } from "openai/auth";

const tokenPath = "/var/run/secrets/tokens/token";
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

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

function mountedAksServiceAccountTokenProvider(path: string): SubjectTokenProvider {
  return {
    tokenType: "jwt",
    getToken: async () => {
      const token = (await readFile(path, "utf8")).trim();
      if (!token) {
        throw new Error("The mounted AKS service account token file is empty.");
      }
      return token;
    },
  };
}

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

const response = await client.responses.create({
  model: "gpt-4.1-mini",
  input: "Say hello from AKS workload identity federation.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import os
from pathlib import Path

from openai import OpenAI
from openai.auth import SubjectTokenProvider

TOKEN_PATH = "/var/run/secrets/tokens/token"


def mounted_aks_service_account_token_provider(token_path: str) -> SubjectTokenProvider:
    def get_token() -> str:
        token = Path(token_path).read_text().strip()
        if not token:
            raise RuntimeError("The mounted AKS service account token file is empty.")
        return token

    return {"token_type": "jwt", "get_token": get_token}


client = OpenAI(
    workload_identity={
        "identity_provider_id": os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        "service_account_id": os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
        "provider": mounted_aks_service_account_token_provider(TOKEN_PATH),
    },
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input="Say hello from AKS workload identity federation.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/auth"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

const tokenPath = "/var/run/secrets/tokens/token"

type mountedAksServiceAccountTokenProvider struct {
	path string
}

func (p mountedAksServiceAccountTokenProvider) TokenType() auth.SubjectTokenType {
	return auth.SubjectTokenTypeJWT
}

func (p mountedAksServiceAccountTokenProvider) GetToken(_ context.Context, _ auth.HTTPDoer) (string, error) {
	data, err := os.ReadFile(p.path)
	if err != nil {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-aks",
			Message:  "failed to read mounted AKS service account token",
			Cause:    err,
		}
	}

	token := strings.TrimSpace(string(data))
	if token == "" {
		return "", &auth.SubjectTokenProviderError{
			Provider: "azure-aks",
			Message:  "mounted AKS service account token is empty",
		}
	}

	return token, nil
}

func main() {
	client := openai.NewClient(
		option.WithWorkloadIdentity(auth.WorkloadIdentity{
			IdentityProviderID: os.Getenv("OPENAI_IDENTITY_PROVIDER_ID"),
			ServiceAccountID:   os.Getenv("OPENAI_SERVICE_ACCOUNT_ID"),
			Provider: mountedAksServiceAccountTokenProvider{
				path: tokenPath,
			},
		}),
	)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModelGPT4_1Mini,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Say hello from AKS workload identity federation."),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.openai.auth.SubjectTokenProvider;
import com.openai.auth.SubjectTokenType;
import com.openai.auth.WorkloadIdentity;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpClient;
import com.openai.errors.SubjectTokenProviderException;
import com.openai.models.ChatModel;
import com.openai.models.responses.ResponseCreateParams;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;

public final class AzureAksWorkloadIdentityExample {
    private static final String TOKEN_PATH = "/var/run/secrets/tokens/token";

    private AzureAksWorkloadIdentityExample() {}

    static final class MountedAksServiceAccountTokenProvider implements SubjectTokenProvider {
        private final Path tokenPath;

        MountedAksServiceAccountTokenProvider(String tokenPath) {
            this.tokenPath = Path.of(tokenPath);
        }

        @Override
        public SubjectTokenType tokenType() {
            return SubjectTokenType.JWT;
        }

        @Override
        public String getToken(HttpClient httpClient, JsonMapper jsonMapper) {
            String token;
            try {
                token = Files.readString(tokenPath).trim();
            } catch (Exception e) {
                throw new SubjectTokenProviderException(
                        "azure-aks",
                        "failed to read mounted AKS service account token",
                        e);
            }

            if (token.isEmpty()) {
                throw new SubjectTokenProviderException(
                        "azure-aks",
                        "mounted AKS service account token is empty",
                        null);
            }

            return token;
        }

        @Override
        public CompletableFuture<String> getTokenAsync(
                HttpClient httpClient, JsonMapper jsonMapper) {
            return CompletableFuture.supplyAsync(() -> getToken(httpClient, jsonMapper));
        }
    }

    public static void main(String[] args) {
        WorkloadIdentity workloadIdentity = WorkloadIdentity.builder()
                .identityProviderId(System.getenv("OPENAI_IDENTITY_PROVIDER_ID"))
                .serviceAccountId(System.getenv("OPENAI_SERVICE_ACCOUNT_ID"))
                .provider(new MountedAksServiceAccountTokenProvider(TOKEN_PATH))
                .build();

        OpenAIClient client = OpenAIOkHttpClient.builder()
                .workloadIdentity(workloadIdentity)
                .build();

        ResponseCreateParams params = ResponseCreateParams.builder()
                .model(ChatModel.GPT_4_1_MINI)
                .input("Say hello from AKS workload identity federation.")
                .build();

        client.responses().create(params).output().stream()
                .flatMap(item -> item.message().stream())
                .flatMap(message -> message.content().stream())
                .flatMap(content -> content.outputText().stream())
                .forEach(outputText -> System.out.println(outputText.text()));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
require "openai"

TOKEN_PATH = "/var/run/secrets/tokens/token"

class MountedAksServiceAccountTokenProvider
  include OpenAI::Auth::SubjectTokenProvider

  def initialize(token_path:)
    @token_path = token_path
  end

  def token_type
    OpenAI::Auth::TokenType::JWT
  end

  def get_token
    token = File.read(@token_path).strip
    if token.empty?
      raise OpenAI::Errors::SubjectTokenProviderError.new(
        message: "Mounted AKS service account token is empty",
        provider: "azure-aks"
      )
    end
    token
  rescue SystemCallError => e
    raise OpenAI::Errors::SubjectTokenProviderError.new(
      message: "Failed to read mounted AKS service account token: #{e.message}",
      provider: "azure-aks",
      cause: e
    )
  end
end

provider = MountedAksServiceAccountTokenProvider.new(token_path: TOKEN_PATH)

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
  identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),
  service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),
  provider: provider
)

client = OpenAI::Client.new(workload_identity: workload_identity)

response = client.responses.create(
  model: "gpt-4.1-mini",
  input: "Say hello from AKS workload identity federation."
)

puts(response.output_text)

Microsoft Azure 最佳实践

尽可能使用托管标识。与手动分发凭据相比，托管标识提供了更简单、更安全的身份验证模型。
为不同的应用程序和环境使用独立的托管标识、Microsoft Entra 应用程序和 OpenAI 映射。避免在开发、预发布和生产工作负载之间共享同一身份。
限制接受的受众。仅配置 OpenAI 工作负载身份联合所需的受众。
为安全边界使用专用的 Microsoft Entra ID 应用程序。独立的应用程序可提供更清晰的所有权、审计和访问管理。
优先使用特定于工作负载的映射。根据特定于工作负载的声明进行匹配，而不是宽泛的租户级属性。
定期审查联合凭据配置。过时的联合凭据可能会在工作负载退役后很久仍无意中继续授予访问权限。
区分生产与非生产身份。生产工作负载应通过独立的联合身份和 OpenAI 服务账号进行身份验证。

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

Azure 托管标识

设置 Azure 托管标识

获取 Azure 托管标识令牌

验证令牌

在 OpenAI 中为 AWS 账户颁发者创建工作负载身份提供商，然后添加与 AWS 颁发令牌中的稳定声明相匹配的服务账户映射。

创建工作负载身份提供商。

设置服务账户映射

在代码中使用令牌

Azure Kubernetes Service (AKS)

设置 AKS

验证令牌

在 OpenAI 中为 AWS 账户颁发者创建工作负载身份提供商，然后添加与 AWS 颁发令牌中的稳定声明相匹配的服务账户映射。

创建工作负载身份提供商。

设置服务账户映射

在代码中使用令牌

Microsoft Azure 最佳实践