Data API 建立器中的授權和角色

數據 API 產生器會使用角色型授權工作流程。任何傳入的請求，無論是否已驗證，都會被指派給一個角色。角色可以是系統角色或使用者角色。然後，會根據組態中指定的已定義許可權檢查指派的角色，以確定該角色在所要求的實體上可以使用哪些動作、欄位和原則。

Data API 建構器如何選擇角色並評估請求權限的示意圖。

判斷使用者的角色

沒有任何角色擁有預設權限。一旦資料 API 建構器確定角色，實體 permissions 必須為該角色定義 actions ，請求才會成功。

以下角色評估矩陣適用於 JWT 承載提供者（例如，EntraID、/、AzureAD 和 Custom），當客戶端傳送 Authorization: Bearer <token> 時。

持有者令牌已提供	`X-MS-API-ROLE` 提供	在代幣 `roles` 認證聲明中要求的角色	有效角色/成效
否	否	N/A	`Anonymous`
是的（有效）	否	N/A	`Authenticated`
是的（有效）	是的	否	拒絕（403 禁忌）
是的（有效）	是的	是的	`X-MS-API-ROLE` 值
是（無效）	任意	N/A	拒絕（401 未授權）

若要使用除 Anonymous 或 Authenticated 以外的角色，則需要使用 X-MS-API-ROLE 標頭檔。

備註

請求可以在經身份驗證的主體中與多種角色相關聯。然而，Data API 建構器會根據一個有效角色的情境評估權限與政策。當提供標頭時，X-MS-API-ROLE 標頭會選擇要使用的角色。

醫師備註：

EasyAuth 提供者（例如 AppService）：可以由平台注入的標頭（如 X-MS-CLIENT-PRINCIPAL）來建立身份驗證，而不是使用承載令牌。
Simulator：在開發/測試階段，請求被視為已驗證，無需驗證真實的 token。

系統角色

系統角色是由數據 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 產生器會在運行時間組態中未參考資料庫物件時忽略資料庫物件。

必須明確設定許可權

若要允許未經驗證的實體存取權， Anonymous 必須在實體的許可權中明確定義角色。例如，實體 book 的權限明確設定為允許未經認證的讀取存取：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

如果你想讓未認證和已認證的使用者都能存取，請明確授權兩個系統角色（Anonymous 和 Authenticated）。

當讀取作業只限於已驗證的使用者時，應該設定下列許可權設定，以拒絕未經驗證的要求：

"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 查詢中的變異與過濾器，權限設定仍如前述強制存取控制。

行動

動作描述角色範圍內實體的存取範圍。動作可以個別指定，或使用通配符快捷方式來指定： * （星號）。通配符快捷方式代表實體類型支援的所有動作：

資料表和檢視表：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"
      }
    }
  ]
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-23