授權決定了經過認證的使用者在你的資料 API 建置器應用程式中被允許做什麼。 認證用來驗證使用者 身份 ，而授權則控制他們能存取和修改 的內容 。
Data API 建構器採用 基於角色的授權工作流程。 任何傳入的請求，無論是否已驗證，都會被指派給一個角色。 角色可以是系統角色或使用者角色。 然後，會根據組態中指定的已定義 許可權 檢查指派的角色，以確定該角色在所要求的實體上可以使用哪些動作、欄位和原則。
關鍵授權概念
實體權限
在實體層級控制 CRUD 操作（建立、讀取、更新、刪除）。 每個角色可以執行或拒絕特定實體的特定行動。
角色型存取控制
根據角色成員身份分配使用者角色並授予權限。 角色簡化了管理具有相似存取模式的大型使用者群組。
資料列層級安全性（RLS）
根據使用者身份或會話情境過濾資料。 使用者只能看到其被授權存取的資料列，這些限制是在資料庫層級強制執行的。
API 原則
對 API 回應套用 OData 的謂詞與過濾器。 政策會自動根據使用者主張與身份限制查詢結果。
聲明式授權
要判斷存取權限，請使用驗證權杖中的聲明（例如群組、角色、自訂屬性）。 申請提供靈活且細緻的許可決定。
運作方式
- 使用者使用支援的認證方法之一進行驗證
- 系統會從認證權杖（角色、群組、組織等）中提取宣稱。
- 授權規則會 根據使用者的主張及所請求的資源進行評估
- 依據實體權限、政策及列級安全規則 來決定是否授予或拒絕存取權限
判斷使用者的角色
沒有任何角色擁有預設權限。 一旦資料 API 建構器確定角色，實體 permissions 必須為該角色定義 actions ，請求才會成功。
以下角色評估矩陣適用於 JSON Web Token（JWT）承載提供者（例如，EntraID/AzureAD和Custom），其中用戶端傳送Authorization: Bearer <token>。
| 持有者令牌已提供 |
X-MS-API-ROLE 提供 |
在代幣 roles 認證聲明中要求的角色 |
有效角色/成效 |
|---|---|---|---|
| No | No | 不適用 | Anonymous |
| 是的（有效） | No | 不適用 | Authenticated |
| 是的（有效） | 是的 | No | 拒絕（403 禁止存取） |
| 是的（有效） | 是的 | 是的 |
X-MS-API-ROLE 值 |
| 是（無效） | 任意 | 不適用 | 拒絕（401 未授權） |
若要使用除 Anonymous 或 Authenticated 以外的角色，則需要使用 X-MS-API-ROLE 標頭檔。
備註
請求可以在經身份驗證的主體中與多種角色相關聯。 然而，Data API 建構器會根據一個有效角色的情境評估權限與政策。 當提供標頭時，X-MS-API-ROLE 標頭會選擇要使用的角色。
醫師備註：
- EasyAuth 提供者（例如
AppService）：平台注入的標頭（例如X-MS-CLIENT-PRINCIPAL）用來建立認證，而不是使用持有人憑證。 -
Simulator： 請求被視為authenticated開發/測試，未驗證真實的標記。
系統角色
系統角色是由數據 API 產生器所辨識的內建角色。 系統角色會自動指派給要求者，無論其角色成員資格是否在其存取令牌中顯示。 有兩個系統角色： Anonymous 和 Authenticated。
匿名系統角色
Anonymous 系統角色會被指派給未經驗證的使用者所執行的要求。 如果需要未經驗證的存取權， Anonymous 定義的運行時間設定實體必須包含角色的許可權。
範例
下列 Data API 建立器執行時設定示範明確設定系統角色 Anonymous，來包括對 Book 實體的 讀取 許可權：
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
}
]
}
當用戶端應用程式代表未經驗證的用戶傳送存取 Book 實體的要求時，應用程式不應該包含 Authorization HTTP 標頭。
已驗證的系統角色
已驗證使用者執行的要求會被指派Authenticated系統角色。
範例
下列 Data API 建立器執行時設定示範明確設定系統角色 Authenticated，來包括對 Book 實體的 讀取 許可權：
"Book": {
"source": "books",
"permissions": [
{
"role": "Authenticated",
"actions": [ "read" ]
}
]
}
使用者角色
使用者角色是非系統角色，會指派給您在執行時組態中設定之身份提供者內的使用者。若要讓 Data API 建構器在使用者角色的情境中評估請求，必須符合兩個需求：
- 經過認證的主體必須包含列出使用者角色成員資格的角色聲明（例如 JWT
roles聲明）。 - 用戶端應用程式必須包含具有要求的 HTTP 標頭
X-MS-API-ROLE，並將標頭的值設定為所需的使用者角色。
角色評估範例
下列範例示範對 Book Data API 建立器運行時間組態中設定之實體提出的要求，如下所示：
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
},
{
"role": "Authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}
Data API 建構器在單一有效角色的情境下評估請求。 若請求已認證且未提供 X-MS-API-ROLE 標頭，Data API 建構器將在預設的 Authenticated 系統角色上下文中評估該請求。
如果用戶端應用程式的要求也包含 HTTP 標頭X-MS-API-ROLE，且具有author值，則會在角色author的內容中評估該要求。 包含存取令牌和 X-MS-API-ROLE HTTP 標頭的範例要求：
curl -k -X GET \
-H 'Authorization: Bearer ey...' \
-H 'X-MS-API-ROLE: author' \
https://localhost:5001/api/Book
這很重要
當提供的存取令牌 roles 宣告不包含標頭中 X-MS-API-ROLE 所列的角色時，用戶端應用程式的要求就會遭到拒絕。
許可
權限描述：
- 誰可以根據角色成員資格對實體提出要求？
- 使用者可以執行的動作（建立、讀取、更新、刪除、執行）
- 特定動作可以存取哪些欄位？
- 要求所傳回的結果存在哪些額外限制？
定義許可權的語法會在 運行時間組態一文中說明。
這很重要
在同一實體的權限設定中，可能會定義多個角色。 不過，請求只會在單一角色的範圍內進行評估。
- 根據預設，系統角色
Anonymous或Authenticated - 如果包含，則在 HTTP 標頭中設定的角色為
X-MS-API-ROLE。
預設安全
根據預設，實體未設定任何許可權，這表示沒有人可以存取實體。 此外，數據 API 產生器會在運行時間組態中未參考資料庫物件時忽略資料庫物件。
行動
動作 描述角色範圍內實體的存取範圍。 動作可以個別指定，或使用通配符快捷方式來指定： * （星號）。 通配符快捷方式代表實體類型支援的所有動作：
- 資料表和檢視表：
create、read、update、delete - 預存程式：
execute
如需動作的詳細資訊，請參閱 組態檔 檔。
欄位存取
您可以設定哪些欄位可供動作存取。 例如，您可以設定要在動作中 包含 和 排除 的 read 欄位。
下列範例會防止具有 free-access 角色的使用者針對 Column3 執行讀取作業。
Column3 GET 請求（REST 端點）或查詢（GraphQL 端點）中的參考會導致請求被拒絕：
"book": {
"source": "dbo.books",
"permissions": [
{
"role": "free-access",
"actions": [
"create",
"update",
"delete",
{
"action": "read",
"fields": {
"include": [ "Column1", "Column2" ],
"exclude": [ "Column3" ]
}
}
]
}
]
}
備註
要在使用 Data API 建構器搭配 Azure Cosmos DB 時強制執行 GraphQL 查詢的存取控制，您必須使用 @authorize 所提供的 GraphQL 架構檔案中的指令。 然而，對於 GraphQL 查詢中的變異與過濾器，權限設定仍會強制執行存取控制，如此處所述。
資料庫政策（項目層級安全）
資料庫政策允許你在列層級過濾結果。 政策轉化為資料庫評估的查詢謂詞，確保使用者僅存取授權紀錄。
| 支援的動作 | 不支援 |
|---|---|
read、update、delete |
create、execute |
備註
Azure Cosmos DB for NoSQL 目前不支援資料庫政策。
如需詳細設定步驟、語法參考及範例，請參閱 「配置資料庫政策」。
快速範例
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.ownerId eq @claims.userId"
}
}
]
}
角色繼承
DAB 2.0 引入了角色繼承，因此你不必在每個角色重複相同的權限區塊。 繼承鏈為：
named-role → authenticated → anonymous
- 如果
authenticated沒有明確設定給某個實體，則會繼承自anonymous。 - 若未設定命名角色，則繼承自
authenticated，或若anonymous亦不存在，則繼承自authenticated。
你可以在anonymous一次定義權限，每個更上層的角色都能自動獲得相同的存取權限，無需重複設定。
備註
本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。 欲了解更多資訊，請參閱 2.0 版本的新內容。
{
"entities": {
"Book": {
"source": "dbo.books",
"permissions": [
{ "role": "anonymous", "actions": [ "read" ] }
]
}
}
}
在此配置下， anonymous， ， authenticated及任何未設定的命名角色皆可讀取 Book。
使用 dab configure --show-effective-permissions 來顯示應用繼承後每個實體的已解決權限。
必須明確設定許可權
若要允許未經驗證的實體存取權， Anonymous 必須在實體的許可權中明確定義角色。 例如，實體 book 的權限明確設定為允許未經認證的讀取存取：
"book": {
"source": "dbo.books",
"permissions": [{
"role": "Anonymous",
"actions": [ "read" ]
}]
}
當讀取作業只限於已驗證的使用者時，應該設定下列許可權設定，以拒絕未經驗證的要求：
"book": {
"source": "dbo.books",
"permissions": [{
"role": "Authenticated",
"actions": [ "read" ]
}]
}
實體不需要且未預先設定與Anonymous和Authenticated角色相關的許可權。 一或多個使用者角色可以在實體的許可權設定內定義，而所有其他未定義的角色、系統或使用者定義，都會自動拒絕存取。
在下列範例中，administrator 是 book 實體唯一已定義的使用者角色。 用戶必須是 administrator 角色的成員，並在 X-MS-API-ROLE HTTP 標頭中包含該角色，才能操作 book 實體。
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}
備註
要在使用 Data API 建構器搭配 Azure Cosmos DB 時強制執行 GraphQL 查詢的存取控制，您必須使用 @authorize 所提供的 GraphQL 架構檔案中的指令。 然而，對於 GraphQL 查詢中的變異與過濾器，權限設定仍如前述強制存取控制。
分層安全模型
Data API 建構器使用多種授權層：
- 實體層級：哪些實體與操作可存取
- 保單層級：回傳哪些資料（根據理賠篩選）
- 列層級：資料庫透過 RLS 進行列篩選
- API 層級：HTTP 標頭與請求驗證