如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

為 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 應信任的權杖對象。設定該應用程式的 應用程式識別碼 URI。工作負載向 Azure 執行個體中繼資料服務 (IMDS) 要求權杖時,會使用此 URI 作為 resource 的值。核發的權杖也會使用此 URI 作為 aud 宣告的值。如需 Microsoft 端的設定步驟,請參閱 Microsoft Entra 指南中的建立新的 Entra ID 應用程式與服務主體。

Microsoft Entra ID 中設定的應用程式識別碼 URI、IMDS 的 resource 參數、核發權杖中的 aud 宣告,以及 OpenAI 工作負載身分識別提供者設定的對象,四者必須完全相符。

建立受控識別,然後將該識別指派給執行應用程式的 Azure 資源,例如虛擬機器。該資源必須能在執行階段呼叫 IMDS。如需 Azure 的設定詳情,請參閱 Microsoft 的受控識別概觀,並查閱該 Azure 資源的文件,瞭解如何指派識別。

取得 Azure 受控識別權杖

在已獲指派受控識別的 Azure 資源上,向 IMDS 要求權杖,並以應用程式識別碼 URI 作為 resource 參數的值。取得的權杖就是主體權杖,可用來向 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 查詢參數,指定要使用的受控識別。Microsoft 在使用虛擬機器上的受控識別取得存取權杖中說明了 IMDS 權杖要求的參數。

驗證權杖

設定工作負載身分識別同盟前,請將 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:必須與應用程式識別碼 URI、IMDS 的 resource 參數,以及 OpenAI 工作負載身分識別提供者設定的對象相符。
  • tid:Microsoft Entra 租用戶識別碼。
  • appid:若權杖包含此宣告,其值就是受控識別的應用程式識別碼(用戶端識別碼)。
  • 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 應用程式識別碼 URI,例如 api://<application-client-id>。此值必須與權杖的 aud 宣告相符。

  3. 使用 Microsoft Entra 的權杖驗證機制。 將 使用已上傳的 JWKS 驗證權杖 維持在停用狀態。OpenAI 會使用 Microsoft Entra 發行者的中繼資料與 JWKS 驗證受控識別權杖。

  4. 如需衍生屬性來設定對應,請新增屬性轉換。 例如,輸入 managed_identity_client_id,並將運算式設為 assertion.appid,即可根據受控識別的應用程式識別碼(用戶端識別碼)宣告建立 openai.managed_identity_client_id。儀表板會自動加上 openai. 前綴。對於帶有 openai. 前綴的原始權杖宣告,除非設定相應的轉換,否則系統在比對 openai. 開頭的對應鍵時會忽略這些宣告。

設定服務帳戶對應

  1. 建立服務帳戶對應。 將 名稱 設為在該工作負載身分識別提供者內不重複的值,例如 vm-openai-wif。在 說明 中輸入 Production VM Azure managed identity workload 等文字,指出哪些工作負載可以使用此對應。

  2. 比對穩定的受控識別宣告。 為每個必須相符的宣告新增一列,填入 鍵 和 值。如果權杖包含 appid,請將 鍵 設為 appid,並將 值 設為受控識別的用戶端識別碼。appid 宣告的值是受控識別的應用程式識別碼(用戶端識別碼)。若要將對應繫結至特定受控識別,這通常是最穩定的宣告。如果權杖未包含 appid,請從解碼後的權杖中選擇其他穩定的宣告,例如 azp、oid、sub 或 xms_mirid。若要將對應繫結至單一租用戶,請另外將 鍵 設為 tid,並將 值 設為 Microsoft Entra 租用戶識別碼。請將從 IMDS 取得的權杖樣本解碼,並選用對於所信任的受控識別和資源而言穩定不變的宣告。

  3. 選擇 OpenAI 的目標專案和服務帳戶。 將 專案 設為目標服務帳戶所屬的 OpenAI 專案。將 服務帳戶 設為 Azure 工作負載可使用的 OpenAI 服務帳戶,例如 azure-managed-identity-prod-openai-wif。

  4. 視需要限縮 API 權限。 選取適當的 權限,例如 api.model.request 和 api.vector_store.read,即可進一步限縮透過此對應核發的存取權杖所具備的權限。若將權限留白,就不會額外套用 WIF 專屬的授權範圍限制。權杖仍會以對應的服務帳戶身分取得授權。

在程式碼中使用權杖

設定 OpenAI SDK 用戶端,讓它向 IMDS 要求 Azure 受控識別權杖,再換取 OpenAI 核發的存取權杖。

將 OPENAI_WIF_AUDIENCE 設為工作負載身分識別提供者用作對象的 Microsoft Entra 應用程式識別碼 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-5.6-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 服務帳戶進行身分驗證。