Microsoft Foundry（經典版）中的認證與授權

目前正在觀看：Foundry（經典）入口版本 - 切換到新 Foundry 入口網站版本

註

本文中的連結可能會開啟新版 Microsoft Foundry 文件的內容，而非您目前正在瀏覽的 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 的適用範圍、使用者的典型操作、範例工具與功能，以及各自使用的授權面。

飛機	鑄造廠的範圍	典型操作	範例工具	授權範圍
控制層面	設定與配置資源、專案、網路、加密與連線	建立或刪除資源、指派角色、輪換金鑰、設定私有連結	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 內的資料平面動作包括：

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

下圖展示了 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 Cognitive Services scope
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>.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	註釋
基本模型推論（聊天、嵌入）	是的	是的	完全支援。
精細調整操作	是的	是的	Entra ID 新增了每個主體審核。
代理人服務	不	是的	使用 Entra ID 來存取管理身份工具。
評估	不	是的	使用 Entra ID。
內容安全分析通話	是的	是的	利用 RBAC 限制高風險操作。
批次分析工作（內容理解）	是的	是的	建議使用 Entra ID 以提升擴展性。
入口遊樂場的使用	是的	是的	Playground 使用專案連線模式。
利用私人連結進行網路隔離	是的	是的	Entra ID 新增了條件存取。
最低權限，內建與自訂角色	不	是的	每個資源的鑰匙都是全有或全無。
管理身份（系統或使用者指派）	不	是的	啟用無秘密認證。
按請求的使用者歸屬	不	是的	Token 包含租戶與物件 ID。
撤銷（立即）	旋轉鍵	移除角色或停用主體	代幣的有效期限很短。
自動化管線支援	是的（秘密）	是的（服務主體或管理身份）	Entra ID 減少了密鑰輪替。
助手 API	是的	是的	建議使用 Entra ID。
批次推論	是的	是的
工具箱	不	是的	使用 Entra ID 來存取管理身份工具。

身份類型

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

Azure 支援以下身份類型。

身份類型	描述
使用者主體	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://ai.azure.com/.default`。如果你使用基於金鑰的認證，請重新產生 API 金鑰。
403 禁忌	缺少的RBAC角色指派	在資源或專案範圍內指定適當的內建角色（例如 Azure AI 使用者）。
AADSTS700016	租戶中找不到申請表	確認應用程式註冊是否存在於正確的租戶中，且客戶端 ID 是否正確。
需要自訂子網域	Resource 使用區域端點而非自訂子域	在 Foundry 資源上設定一個自訂子網域。基於憑證的認證需要自訂的子網域。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-30