數據 API 產生器中的授權和角色

數據 API 產生器會使用角色型授權工作流程。 任何已驗證或未通過驗證的傳入要求，都指派給角色。 角色 可以是 系統角色 或 使用者角色。 指派的角色接著會根據組態檔中指定的定義許可權進行檢查，以瞭解要求實體上該角色可用的動作、欄位和原則。

角色

角色會設定應執行要求的許可權內容。 針對運行時間組態中定義的每個實體，您可以定義一組角色和相關聯的許可權，以決定如何在 REST 和 GraphQL 端點中存取實體。

數據 API 產生器會評估單一角色內容中的要求：

• anonymous 未顯示存取令牌時。
• authenticated 當顯示有效的存取令牌時。
• <CUSTOM_USER_ROLE>當顯示有效的存取令牌且X-MS-API-ROLE包含 HTTP 標頭時，會指定也包含在存取令牌宣告roles中的使用者角色。

角色 不是 加總的，這表示屬於兩者 Role1 成員的使用者，而且 Role2 不會繼承這兩個角色相關聯的許可權。

系統角色

系統角色是由數據 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" ]
        }
    ]
}

使用者角色

使用者角色是指派給您在運行時間設定中設定之識別提供者內的使用者的非系統角色。若要讓數據 API 產生器在使用者角色的內容中評估要求，必須符合兩個需求：

1. 用戶端應用程式提供的存取令牌必須包含列出使用者角色成員資格的角色宣告。
2. 用戶端應用程式必須包含具有要求的 HTTP 標頭 X-MS-API-ROLE ，並將標頭的值設定為所需的使用者角色。

角色評估範例

下列範例示範對 Book Data API 產生器運行時間組態中設定之實體提出的要求，如下所示：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

在 Static Web Apps 中，用戶預設為匿名角色的成員。 如果使用者經過驗證，則用戶同時是 和 authenticated 角色的成員anonymous。

當用戶端應用程式將已驗證的要求傳送至使用 Static Web Apps 資料庫連結 (Preview) 部署的數據 API 產生器時，用戶端應用程式會提供存取令牌，Static Web Apps 轉換成 JSON：

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

由於數據 API 產生器會評估單一角色內容中的要求，因此預設會在系統角色 authenticated 的內容中評估要求。

如果用戶端應用程式的要求也包含具有 值的 authorHTTP 標頭X-MS-API-ROLE，則會在角色的內容author中評估要求。 包含存取令牌和 X-MS-API-ROLE HTTP 標頭的範例要求：

curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book

權限

權限描述：

• 誰可以根據角色成員資格對實體提出要求？
• (建立、讀取、更新、刪除、執行) 用戶可以執行的動作為何？
• 特定動作可存取哪些欄位？
• 要求所傳回的結果上存在哪些額外限制？

定義許可權的語法會在運行時間組 態一文中說明。

預設保護

根據預設，實體沒有設定許可權，這表示沒有人可以存取實體。 此外，數據 API 產生器會在運行時間組態中未參考資料庫物件時忽略它們。

必須明確設定許可權

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

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

若要簡化實體的許可權定義，請假設角色沒有特定許可權 authenticated ，則會使用為 anonymous 角色定義的許可權。 先前顯示的組 book 態可讓任何匿名或已驗證的使用者對實體執行讀取作業 book 。

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

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

實體不需要，也不會預先設定 和 authenticated 角色的許可權anonymous。 您可以在實體的許可權設定中定義一或多個使用者角色，而所有其他未定義的角色、系統或使用者定義都會自動拒絕存取。

在下列範例中，使用者角色 administrator 是唯一為實體定義的角色 book 。 用戶必須是角色的成員， administrator 並在 HTTP 標頭中包含 X-MS-API-ROLE 該角色，才能在實體上 book 操作：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

動作

動作 描述角色範圍內實體的輔助功能。 您可以個別指定動作，或使用通配符快捷方式來指定： * (星號) 。 通配符快捷方式代表實體類型支援的所有動作：

• 數據表和檢視表：create、、、readupdate、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" ]
              }
            }
          ]
        }
      ]
    }

專案層級安全性

資料庫原則 表達式可進一步限制結果。 資料庫原則會將表達式轉譯為針對資料庫執行的查詢述詞。 下列動作支援資料庫原則表示式：

如需資料庫原則的詳細資訊，請參閱 配置檔 檔。

範例

限制角色上consumer動作的資料庫原則read只會傳回標題為「範例標題」的記錄。

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

相關內容

• Azure 驗證
• 本機驗證