Microsoft Foundry 中的認證與授權

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

Foundry 支援兩種認證方法：Microsoft Entra ID 與 API 金鑰。 Microsoft Entra ID 支援條件存取、管理身份及細緻的 RBAC。 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 的適用範圍、使用者的典型操作、範例工具與功能，以及各自使用的授權面。

飛機	Foundry 的範圍	典型操作	範例工具	授權層面
控制平面	設定與配置資源、專案、網路、加密與連線	建立或刪除資源、指派角色、輪替金鑰、設定私人連結	Azure portal，Azure CLI，ARM templates，Bicep，Terraform	Azure RBAC 操作
數據平面	執行和使用模型推論、客服專員互動、評估任務和內容安全呼叫	對話完成、內嵌產生、啟動精細調整任務、傳送代理訊息、分析器與分類器操作	SDK、REST API、Foundry 入口網站測試平台	Azure RBAC dataActions

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

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

鑄造廠資源建立
鑄造廠專案創建
帳號功能主機建立
專案主機能力建立
模型部署
帳號與專案連結建立

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

建置代理程式
評估的進行過程
追蹤與監控
Fine-tuning

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

身份驗證方法

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

Microsoft Entra ID

Microsoft Entra ID 使用 OAuth 2.0 持有者令牌，範圍為 https://cognitiveservices.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 Cognitive Services scope
token = credential.get_token("https://cognitiveservices.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>.cognitiveservices.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>.cognitiveservices.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())

警告

API 金鑰提供對資源的完整存取權限，且無法針對特定使用者或動作設限。定期輪換金鑰，避免將它們交給原始碼控制。

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

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

功能支援矩陣

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

功能或特徵	API 金鑰	Microsoft Entra ID	註釋
基本模型推論（聊天、內嵌）	Yes	Yes	完全支援。
微調操作	Yes	Yes	Entra ID 新增了逐個用戶的審核功能。
代理人服務	否	Yes	使用 Entra ID 進行受控識別工具存取。
Evaluations	否	Yes	使用 Entra ID。
內容安全分析通話	Yes	Yes	使用 RBAC 來限制高風險作業。
批次分析工作（內容理解）	Yes	Yes	推薦使用 Entra ID 以達成規模化。
入口網站遊樂場使用方式	Yes	Yes	Playground 使用專案連線模式。
使用 Private Link 進行網路隔離	Yes	Yes	Entra ID 新增了條件存取。
具有內建和自訂角色的最小權限	否	Yes	鑰匙對於每個資源而言，要不就完全授權，要不就毫無授權。
受控識別（系統或使用者指派）	否	Yes	啟用無秘密認證。
每個請求的使用者歸因	否	Yes	Token 包含租戶與物件 ID。
撤銷（立即）	旋轉鍵	移除角色或停用主體	短期代幣存活期適用。
自動化流程中的支援	是（秘密）	是（服務主體或受控識別）	Entra ID 減少了機密輪替。
小幫手 API	Yes	Yes	建議使用 Entra ID。
批次推斷	Yes	Yes

身分識別類型

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

Azure 支援以下身份類型。

身分類型	Description
使用者主體	Microsoft Entra ID 中的個人使用者
Service principal （應用程式註冊）	使用用戶端密碼或憑證的應用程式身分識別
管理識別（系統指派的）	Azure 資源綁定身份由平台自動管理。
受控識別（使用者指派）	獨立身份，連結多個資源。

內建角色概觀

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

情境	典型內建角色	註釋
用預先部署的模型建置代理	Azure AI 使用者	僅用於資料平面；沒有管理層寫入。
管理部署或微調模型	Azure AI 項目經理	包含模型部署建立與更新。
輪替金鑰或管理資源	Azure AI 帳戶擁有者	高特權;考慮自訂角色以獲得最低權限。
管理資源、管理部署、建置代理	Azure AI 擁有者	為需要同時存取控制平面與資料平面的使用者提供高度特權的自助角色。如果需要可觀察性，可以搭配 Azure Monitor Reader 一起使用。
可觀察性、追蹤、監控	Azure AI User （最低限度）	在應用程式洞察中新增 Azure Monitor Reader。

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

小提示

如果內建角色會為你的使用情境授予多餘權限，請建立一個自訂角色。

設定Microsoft Entra ID

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

請確保您的 Microsoft Foundry 資源已設定自訂子網域。請參閱自訂子網域。基於憑證的認證需要自訂子網域。
為每個主要負責人指派所需的內建或自訂角色。你必須在目標範圍內擁有 擁有者 或 使用者存取管理員 角色以指派角色。常見角色分配：
- Azure AI 使用者：適合需要用預先部署模型建置和測試的開發者。
- Azure AI 專案經理：適合需要建立專案和管理部署的團隊主管。
- Azure AI 帳戶擁有者：適合需要完整資源管理，且能條件指派 Azure AI 使用者存取資料平面的管理員。
- Azure AI 擁有者：適合需要完整資源管理與資料平面存取的使用者。指派 Azure AI User 角色的 CLI 指令範例：
```
az role assignment create \
  --assignee <principal-id> \
  --role "Azure AI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
```
要驗證角色指派，執行 az role assignment list --assignee <principal-id> --scope <resource-scope> 並確認該角色出現在輸出中。
（可選）對於服務主體，建立應用程式註冊，新增用戶端秘密或憑證，並記錄租戶 ID、用戶端 ID 及秘密或憑證。
(選用) 對於受控識別，請在呼叫服務上啟用系統指派的身分識別，或附加使用者指派的身分識別，然後在 Foundry 資源上指派一個角色給它。
在所有呼叫端使用權杖驗證之後，移除金鑰型驗證。選擇性地停用部署範本中的本機驗證。

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

排除常見的認證錯誤

錯誤	原因	解決辦法
401 未經授權	缺少或過期的代幣;API 金鑰無效	確認代幣獲取範圍為 `https://cognitiveservices.azure.com/.default`。如果你使用基於金鑰的認證，請重新產生 API 金鑰。
403 禁忌	缺少 RBAC 角色指派	在資源或專案範圍內指定適當的內建角色（例如 Azure AI 使用者）。
AADSTS700016	租戶中找不到申請表	確認應用程式註冊是否存在於正確的租戶中，且客戶端 ID 是否正確。
需要自訂子網域	Resource 使用區域端點而非自訂子域	在 Foundry 資源上設定一個自訂子網域。基於憑證的認證需要自訂的子網域。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-02-28