データ API ビルダーでの承認とロール
データ API ビルダーでは、ロールベースの承認ワークフローが使用されます。 認証されたかどうかにかかわらず、受信要求はロールに割り当てられます。 ロール には、 システム ロール または ユーザー ロールを指定できます。 その後、割り当てられたロールが構成ファイルで指定された定義済みのアクセス許可に対してチェックされ、要求されたエンティティでそのロールに対して使用できるアクション、フィールド、およびポリシーが理解されます。
ロール
ロールは、要求を実行する必要があるアクセス許可コンテキストを設定します。 ランタイム構成で定義されているエンティティごとに、REST エンドポイントと GraphQL エンドポイントの両方でエンティティにアクセスする方法を決定する一連のロールと関連するアクセス許可を定義できます。
データ API ビルダーは、1 つのロールのコンテキストで要求を評価します。
anonymousアクセス トークンが提示されない場合。authenticated有効なアクセス トークンが提示されたとき。<CUSTOM_USER_ROLE>有効なアクセス トークンが提示され、アクセス トークンrolesのX-MS-API-ROLE要求にも含まれるユーザー ロールを指定する HTTP ヘッダーが含まれている場合。
ロールは追加的ではありません。つまり、両方のメンバーであり、両方Role1Role2のロールに関連付けられているアクセス許可を継承しないユーザーです。
システムの役割
システム ロールは、データ API ビルダーによって認識される組み込みロールです。 システム ロールは、アクセス トークンで示されるリクエスタのロール メンバーシップに関係なく、要求者に自動割り当てられます。 と の 2 つのシステム ロールがあります anonymousauthenticated。
匿名システム ロール
anonymousシステム ロールは、認証されていないユーザーによって実行される要求に割り当てられます。 認証されていないアクセスが必要な場合は、ランタイム構成定義エンティティにロールの anonymous アクセス許可を含める必要があります。
例
次の Data API ビルダーのランタイム構成は、Book エンティティへの読み取りアクセスを含むようにシステム ロールanonymousを明示的に構成する方法を示しています。
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
}
]
}
認証されていないユーザーの代わりに、クライアント アプリケーションが Book エンティティにアクセスする要求を送信する場合、アプリには HTTP ヘッダーを Authorization 含めてはいけません。
認証済みシステム ロール
authenticatedシステム ロールは、認証されたユーザーによって実行される要求に割り当てられます。
例
次の Data API ビルダーのランタイム構成は、Book エンティティへの読み取りアクセスを含むようにシステム ロールauthenticatedを明示的に構成する方法を示しています。
"Book": {
"source": "books",
"permissions": [
{
"role": "authenticated",
"actions": [ "read" ]
}
]
}
ユーザー ロール
ユーザー ロールは、ランタイム構成で設定した ID プロバイダー内のユーザーに割り当てられる非システム ロールです。データ API ビルダーがユーザー ロールのコンテキストで要求を評価するには、次の 2 つの要件を満たす必要があります。
- クライアント アプリから提供されるアクセス トークンには、ユーザーのロール メンバーシップを一覧表示するロール要求が含まれている必要があります。
- クライアント アプリには、要求を含む HTTP ヘッダー
X-MS-API-ROLEを含め、ヘッダーの値を目的のユーザー ロールとして設定する必要があります。
ロールの評価の例
次の例では、Data API Builder ランタイム構成で構成されているエンティティに対する Book 要求を次のように示します。
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
},
{
"role": "authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}
Static Web Appsでは、ユーザーは既定で匿名ロールのメンバーです。 ユーザーが認証されている場合、ユーザーは ロールと authenticated ロールの両方anonymousのメンバーになります。
クライアント アプリが、Static Web Apps データベース接続 (プレビュー) を使用してデプロイされた Data API ビルダーに認証済み要求を送信すると、クライアント アプリは JSON に変換Static Web Appsアクセス トークンを提供します。
{
"identityProvider": "azuread",
"userId": "d75b260a64504067bfc5b2905e3b8182",
"userDetails": "username",
"userRoles": ["anonymous", "authenticated", "author"]
}
Data API ビルダーは、1 つのロールのコンテキストで要求を評価するため、既定ではシステム ロール authenticated のコンテキストで要求を評価します。
クライアント アプリケーションの要求に 値 authorを持つ HTTP ヘッダー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
重要
指定されたアクセス トークンの要求にヘッダーに一覧表示されているX-MS-API-ROLEロールが含まれていない場合、クライアント アプリのroles要求は拒否されます。
アクセス許可
アクセス許可の説明:
- ロール メンバーシップに基づいてエンティティに対して要求を行うことができるのは誰ですか?
- ユーザーが実行できるアクション (作成、読み取り、更新、削除、実行)
- 特定のアクションでアクセスできるフィールドはどれですか?
- 要求によって返される結果には、どの追加の制限がありますか?
アクセス許可を定義するための構文については、ランタイム構成に関する 記事を参照してください。
重要
1 つのエンティティのアクセス許可構成内に複数のロールが定義されている場合があります。 ただし、要求は 1 つのロールのコンテキストでのみ評価されます。
- 既定では、システム ロール
anonymousまたはauthenticated - 含まれている場合は、HTTP ヘッダーにロール セットが
X-MS-API-ROLE設定されます。
既定でのセキュリティ保護
既定では、エンティティにはアクセス許可が構成されていません。つまり、誰もエンティティにアクセスできません。 また、ランタイム構成でデータベース オブジェクトが参照されていない場合、データ 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が必要で、事前構成されていません。 エンティティのアクセス許可構成内で 1 つ以上のユーザー ロールを定義でき、他のすべての未定義のロール、システム、またはユーザー定義は、自動的にアクセスを拒否されます。
次の例では、ユーザー ロール administrator がエンティティに対して定義されている唯一の book ロールです。 エンティティを操作するには、ユーザーが administrator ロールのメンバーであり、 X-MS-API-ROLE HTTP ヘッダーにそのロールを book 含める必要があります。
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}
注意
Azure Cosmos DB で Data API ビルダーを使用するときにGraphQLクエリのアクセス制御を適用するには、指定した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 で Data API ビルダーを使用するときにGraphQLクエリのアクセス制御を適用するには、指定したGraphQL スキーマ ファイルで ディレクティブを使用@authorizeする必要があります。 ただし、GraphQL クエリの変更とフィルター GraphQL場合でも、アクセス制御は、ここで説明するようにアクセス許可の構成によって適用されます。
アイテム レベルのセキュリティ
データベース ポリシー 式を使用すると、結果をさらに制限できます。 データベース ポリシーは、式をデータベースに対して実行されるクエリ述語に変換します。 データベース ポリシー式は、次のアクションでサポートされています。
- create
- 読み取り
- update
- 削除
警告
ストアド プロシージャで使用される 実行 アクションは、データベース ポリシーを サポートしていません 。
注意
データベース ポリシーは現在、CosmosDB for NoSQL ではサポートされていません。
データベース ポリシーの詳細については、 構成ファイル のドキュメントを参照してください。
例
タイトルが "サンプル タイトル" のレコードのみを返すようにロールに対consumerするアクションを制限readするデータベース ポリシー。
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.title eq 'Sample Title'"
}
}
]
}