データ API ビルダーは、ロールベースの承認ワークフローを使用します。 認証されたかどうかにかかわらず、すべての受信要求がロールに割り当てられます。 ロールには、 システム ロール または ユーザー ロールを指定できます。 割り当てられたロールは、構成で指定された定義済みの アクセス許可 に対してチェックされ、要求されたエンティティでそのロールに対して使用できるアクション、フィールド、およびポリシーを理解します。
ユーザーのロールの決定
既定のアクセス許可を持つロールはありません。 Data API ビルダーがロールを決定したら、要求を成功させるには、エンティティの permissions でそのロールの actions を定義する必要があります。
次のロール評価マトリックスは、クライアントがEntraIDを送信する JWT ベアラー プロバイダー (/AzureADCustomやAuthorization: Bearer <token>など) に適用されます。
| ベアラー トークンが指定されました |
X-MS-API-ROLE 提供 |
トークンの中のクレームに存在するリクエストされたロール | 効果的な役割/成果 |
|---|---|---|---|
| いいえ | いいえ | N/A | Anonymous |
| はい (有効) | いいえ | N/A | Authenticated |
| はい (有効) | イエス | いいえ | 拒否 (403 禁止) |
| はい (有効) | イエス | イエス |
X-MS-API-ROLE 値 |
| はい (無効) | [任意] | N/A | 拒否されました (401 Unauthorized) |
AnonymousまたはAuthenticated以外のロールを使用するには、X-MS-API-ROLE ヘッダーが必要です。
注
要求は、認証されたプリンシパルの多くのロールに関連付けることができます。 ただし、Data API ビルダーは、1 つの有効なロールのコンテキストでアクセス許可とポリシーを評価します。 指定すると、 X-MS-API-ROLE ヘッダーによって、使用するロールが選択されます。
プロバイダーに関する注意事項:
- EasyAuth プロバイダー (
AppServiceなど): ベアラー トークンではなく、プラットフォームによって挿入されたヘッダー (X-MS-CLIENT-PRINCIPALなど) によって認証を確立できます。 -
Simulator: 要求は、実際のトークンを検証することなく、開発/テスト用に認証済みとして扱われます。
システム ロール
システム ロールは、Data API ビルダーによって認識される組み込みロールです。 システム ロールは、アクセス トークンに示されているリクエスタのロール メンバーシップに関係なく、要求者に自動割り当てされます。 システムロールには、 Anonymous と Authenticatedの 2 つがあります。
匿名システム役割
Anonymous システム ロールは、認証されていないユーザーによって実行される要求に割り当てられます。 認証されていないアクセスが必要な場合は、ランタイム構成定義エンティティに Anonymous ロールのアクセス許可を含める必要があります。
例
次の Data API Builder ランタイム構成は、Book エンティティへのAnonymousアクセスを含むようにシステム ロール を明示的に構成する方法を示しています。
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
}
]
}
認証されていないユーザーの代わりに、クライアント アプリケーションが Book エンティティにアクセスする要求を送信する場合、アプリには Authorization HTTP ヘッダーを含めてはなりません。
認証済みシステムの役割
Authenticated システム ロールは、認証されたユーザーによって実行される要求に割り当てられます。
例
次の Data API Builder ランタイム構成は、Book エンティティへのAuthenticatedアクセスを含むようにシステム ロール を明示的に構成する方法を示しています。
"Book": {
"source": "books",
"permissions": [
{
"role": "Authenticated",
"actions": [ "read" ]
}
]
}
ユーザー ロール
ユーザー ロールは、ランタイム構成で設定した ID プロバイダー内のユーザーに割り当てられる非システム ロールです。データ API ビルダーがユーザー ロールのコンテキストで要求を評価するには、次の 2 つの要件を満たす必要があります。
- 認証されたプリンシパルには、ユーザーのロール メンバーシップを一覧表示するロール要求 (JWT
roles要求など) が含まれている必要があります。 - クライアント アプリには、要求を含む HTTP ヘッダー
X-MS-API-ROLEを含め、ヘッダーの値を目的のユーザー ロールとして設定する必要があります。
ロールの評価の例
次の例では、データ API ビルダーのランタイム構成で構成されている Book エンティティに対して行われた要求を次に示します。
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
},
{
"role": "Authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}
データ API ビルダーは、1 つの有効なロールのコンテキストで要求を評価します。 要求が認証され、 X-MS-API-ROLE ヘッダーが指定されていない場合、Data API ビルダーは、既定で Authenticated システム ロールのコンテキストで要求を評価します。
クライアント アプリケーションの要求に値がX-MS-API-ROLEの HTTP ヘッダー authorも含まれている場合、要求はauthor ロールのコンテキストで評価されます。 アクセス トークンと HTTP ヘッダー X-MS-API-ROLE 含む要求の例:
curl -k -X GET \
-H 'Authorization: Bearer ey...' \
-H 'X-MS-API-ROLE: author' \
https://localhost:5001/api/Book
Von Bedeutung
指定されたアクセス トークンの roles 要求に、 X-MS-API-ROLE ヘッダーに一覧表示されているロールが含まれていない場合、クライアント アプリの要求は拒否されます。
権限
アクセス許可には、次の内容が記述されています。
- ロールメンバーシップに基づいてエンティティに対して要求を行うことができるのは誰ですか?
- ユーザーが実行できるアクション (作成、読み取り、更新、削除、実行)
- 特定のアクションでアクセスできるフィールドはどれですか?
- 要求によって返される結果には、どの追加の制限がありますか?
アクセス許可を定義するための構文については、 ランタイム構成に関する記事を参照してください。
Von Bedeutung
1 つのエンティティのアクセス許可構成内に複数のロールが定義されている場合があります。 ただし、要求は 1 つのロールのコンテキストでのみ評価されます。
- 既定では、システム ロール
AnonymousまたはAuthenticated - 含まれている場合は、
X-MS-API-ROLEHTTP ヘッダーにロール セットが設定されます。
デフォルトで安全が確保されています
既定では、エンティティにはアクセス許可が構成されていないため、誰もエンティティにアクセスできません。 また、ランタイム構成でデータベース オブジェクトが参照されていない場合、データ 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 ロールのアクセス許可を必要とせず、事前構成されていません。 エンティティのアクセス許可構成内で 1 つ以上のユーザー ロールを定義でき、他のすべての未定義のロール、システム、またはユーザー定義は自動的にアクセスを拒否されます。
次の例では、ユーザー ロール administrator が、 book エンティティに対して定義されている唯一のロールです。
administrator エンティティを操作するには、ユーザーが X-MS-API-ROLE ロールのメンバーであり、そのロールを book HTTP ヘッダーに含める必要があります。
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}
注
Azure Cosmos DB でデータ API ビルダーを使用するときに GraphQL クエリのアクセス制御を適用するには、指定した @authorizeで ディレクティブを使用する必要があります。 ただし、GraphQL クエリでの GraphQL の変更とフィルターの場合、アクセス許可の構成では、前に説明したようにアクセス制御が適用されます。
アクション
アクション は、ロールのスコープ内のエンティティのアクセシビリティを表します。 アクションは、個別に指定することも、ワイルドカード ショートカット ( * (アスタリスク) を使用して指定することもできます。 ワイルドカード ショートカットは、エンティティ型でサポートされているすべてのアクションを表します。
- テーブルとビュー:
create、read、update、delete - ストアド プロシージャ:
execute
アクションの詳細については、 構成ファイル のドキュメントを参照してください。
フィールド アクセス
アクションにアクセスできるフィールドを構成できます。 たとえば、 アクションに含めるフィールドとreadするフィールドを設定できます。
次の例では、 free-access ロールのユーザーが Column3に対して読み取り操作を実行できないようにします。 GET 要求 (REST エンドポイント) またはクエリ (GraphQL エンドポイント) で Column3 を参照すると、要求が拒否されます。
"book": {
"source": "dbo.books",
"permissions": [
{
"role": "free-access",
"actions": [
"create",
"update",
"delete",
{
"action": "read",
"fields": {
"include": [ "Column1", "Column2" ],
"exclude": [ "Column3" ]
}
}
]
}
]
}
注
Azure Cosmos DB でデータ API ビルダーを使用するときに 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"
}
}
]
}