Microsoft Foundry 中的認證與授權

Microsoft Foundry 中的認證與授權控制主體如何證明身份並取得執行操作的權限。 Foundry 將操作劃分為控制平面（資源管理）與資料平面（執行時使用），每個平面都有自己的認證與基於角色的存取控制（RBAC）介面。

Foundry 支援兩種認證方法：Microsoft Entra ID 與 API 金鑰。 Microsoft Entra ID 支援條件存取、管理身份及細緻的 RBAC。 API 金鑰仍可快速原型開發，但缺乏逐用戶追蹤性。 本文比較這些方法，將身份與角色對應，並描述常見的最低權限情境。

先決條件

• Azure 訂閱。 如果你沒有，請 建立一個免費帳號。
• 一個 Microsoft Foundry 資源，且已設定 自訂子網域。
• 了解 Azure RBAC 的概念。
• 要指派角色，你需要在適當的範圍內使用 擁有者 角色或 使用者存取管理員 角色。
• （可選）安裝 Azure CLI 或 Azure SDK for Python 用於程式化認證。
• （可選）Python 範例套件： pip install azure-identity requests

控制平面與資料平面

Azure 操作分為兩類：控制平面與資料平面。 Azure 將資源管理（控制平面）與運作執行時（資料平面）分離。 因此，你用控制平面來管理訂閱中的資源，而資料平面則用來利用你實例中某一資源類型所暴露的能力。 欲了解更多關於控制平面與資料平面的資訊，請參閱 Azure 控制平面與資料平面。 在 Foundry 中，控制平面操作與資料平面操作有明顯區分。 下表說明兩者的差異、Foundry 的適用範圍、使用者的典型操作、範例工具與功能，以及各自使用的授權面。

關於所有 Bicep、Terraform 和 SDK 範例，請參考 GitHub 上的 Foundry-samples 倉庫 。

以下列表與圖表詳細說明控制平面與資料平面動作的分離。 Foundry 內的控制平面動作包括：

• 鑄造廠資源建立
• 鑄造廠專案創建
• 帳號與專案能力設定設定
• 模型部署
• 帳號與專案連結建立

Foundry 內的資料平面動作包括：

• 建築代理
• 進行評估
• 追蹤與監控
• 微調

下圖展示了 Foundry 中控制平面與資料平面的分離，以及基於角色的存取控制（RBAC）指派，以及使用者在控制平面或資料平面或兩者中可能擁有的存取權限。 如圖所示，RBAC「動作」與控制平面相關聯，而RBAC「dataActions」則與資料平面相關聯。

認證方法

Foundry 支援 Microsoft Entra ID（基於令牌、無密鑰）及 API 金鑰。

Microsoft Entra ID

Microsoft Entra ID 使用 OAuth 2.0 持有者令牌，範圍為 https://ai.azure.com/.default。

使用 Microsoft Entra ID 用於：

• 生產工作量。
• 條件存取、多重驗證（MFA）及即時存取。
• 最低權限 RBAC 和受控識別整合。

優點：微調的角色指派、每個主體稽核、可控制的權杖存留時間、自動祕密安全防衛，以及服務的受控識別。

限制：初始設定複雜度較高。 需要了解基於角色的存取控制（RBAC）。 欲了解更多 Foundry 中的 RBAC，請參閱 Microsoft Foundry 的角色基礎存取控制。

API 金鑰

API 金鑰是靜態秘密，作用範圍為 Foundry 資源。

API 金鑰可用於：

• 快速原型製作。
• 隔離的測試環境，可接受單一機密輪替。

優點：簡單、語言無關，且不需代幣取得。

限制：無法表達使用者身份，難以細緻範圍，且較難審核。 企業生產工作負載通常不接受，Microsoft也不推薦。

欲了解更多啟用無金鑰認證的資訊，請參閱「 使用 Microsoft Entra ID 配置無金鑰認證」。

使用 Microsoft Entra ID 驗證（Python）

以下範例展示了如何利用 azure-identity Microsoft Entra ID 函式庫進行認證，並向 Foundry 端點提出請求：

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Foundry scope (https://ai.azure.com/.default)
token = credential.get_token("https://ai.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.services.ai.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

預期輸出：一個列出模型部署的 JSON 回應，或如果缺少憑證或角色分配未設定，則會發出認證錯誤。

Reference： DefaultAzureCredential | azure-identity library

用 API 金鑰認證（Python）

以下範例展示了如何使用 API 金鑰進行認證。 此方法僅用於快速原型製作;建議使用 Microsoft Entra ID 用於生產環境。

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.services.ai.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

預期輸出：一個列出你模型部署的 JSON 回應，或如果 API 金鑰無效則會收到 401 錯誤。

參考資料： 輪換 API 存取金鑰

功能支援矩陣

清參考以下矩陣來了解 Foundry 中哪些功能支援 API 金鑰，哪些支援 Microsoft Entra ID。

身份類型

Azure 資源與應用程式透過不同的身份類型進行驗證，每種身份類型都針對特定情境設計。 使用者主體代表人類使用者，服務主體代表應用程式或自動化流程，而受管理身份則提供一種安全且無需憑證的方式，讓 Azure 資源能夠存取其他服務。 了解這些區別，有助於你選擇適合互動登入、應用程式間溝通或工作負載自動化的正確身份。

Azure 支援以下身份類型。

內建角色概述

在 Foundry 中，利用內建的角色來區分使用者允許的動作。 大多數企業希望其內建角色能將控制與資料平面動作分離。 另一些則期望結合資料與控制平面的角色，以減少所需的角色分配數量。 下表列出了各種情境及其最適合每個情境的內建 Foundry 角色。

為了了解內建角色的分解以及控制平面和資料平面的動作，請參考以下圖表。

設定 Microsoft Entra ID

關於在 Foundry 中設定 Entra ID 認證的高階指引，請參見 「配置無金鑰認證」。

1. 請確保您的 Microsoft Foundry 資源已設定自訂子網域。 請參見 自訂子網域。 基於憑證的認證需要自訂子網域。

2. 為每個主要負責人指派所需的內建或自訂角色。 你必須在目標範圍中擁有擁有者或使用者存取管理員角色，才能指派角色。 常見角色分配：

   • Foundry 使用者：供需要使用預先部署的模型進行建置與測試的開發者使用。
   • Foundry Project Manager：適合需要建立專案和管理部署的團隊領導。
   • Foundry 帳戶擁有者：適合需要完整資源管理並能視情況指派資料平面的 Foundry 使用者存取權的管理員。
   • Foundry Owner：適合需要完整資源管理與資料平面存取的使用者。 指派 Foundry User 角色的 CLI 指令範例：

   az role assignment create \
     --assignee <principal-id> \
     --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

要驗證角色指派，執行 az role assignment list --assignee <principal-id> --scope <resource-scope> 並確認該角色出現在輸出中。

1. （可選）對於服務主體，建立應用程式註冊，新增用戶端秘密或憑證，並記錄租戶 ID、用戶端 ID 及秘密或憑證。
2. (選用) 對於受控識別，請在呼叫服務上啟用系統指派的身分識別，或附加使用者指派的身分識別，然後在 Foundry 資源上指派一個角色給它。
3. 在所有呼叫者使用令牌驗證後，移除基於金鑰的驗證。 可選擇性地在部署範本中關閉本地認證。

參考資料： 指派 Azure 角色 | Foundry 以角色為基礎的存取控制

排除常見的認證錯誤

相關內容

• Foundry 的基於角色的存取控制
• 設定使用 Microsoft Entra ID 的無金鑰認證
• 輪換 API 存取金鑰
• Azure 內建角色（AI + 機器學習）
• 認證與授權（Microsoft Entra ID）
• 身份基本概念