承認の概要

承認によって、認証されたユーザーが Data API Builder アプリケーションで実行できる操作が決まります。認証ではユーザーが 誰であるかを 確認しますが、承認はユーザーがアクセスして変更できる内容を制御します。

データ API ビルダーは、 ロールベースの承認ワークフローを使用します。認証されたかどうかにかかわらず、すべての受信要求がロールに割り当てられます。ロールには、システムロールまたはユーザーロールを指定できます。割り当てられたロールは、構成で指定された定義済みのアクセス許可に対してチェックされ、要求されたエンティティでそのロールに対して使用できるアクション、フィールド、およびポリシーを理解します。

主要な承認の概念

エンティティのアクセス許可

エンティティレベルで CRUD 操作 (作成、読み取り、更新、削除) を制御します。各ロールは、特定のエンティティに対する特定のアクションを許可または拒否できます。

ロールベースのアクセス制御

ロールにユーザーを割り当て、ロールメンバーシップに基づいてアクセス許可を付与します。ロールを使用すると、同様のアクセスパターンで大規模なユーザーグループの管理が簡略化されます。

行レベルのセキュリティ (RLS)

ユーザー ID またはセッションコンテキストに基づいてデータをフィルター処理します。ユーザーには、アクセスが許可されている行のみが表示され、データベースレベルで適用されます。

API ポリシー

API 応答に OData 述語とフィルターを適用します。ポリシーは、ユーザーの要求と ID に基づいてクエリ結果を自動的に制限します。

要求ベースの認可

アクセスを決定するには、認証トークンからの要求 (グループ、ロール、カスタム属性など) を使用します。要求は、柔軟できめ細かいアクセス許可の決定を提供します。

どのように機能するのか

サポートされている認証 方法のいずれかを使用してユーザーが認証を行う
システムが 認証トークン (ロール、グループ、組織など) から要求を抽出する
承認規則は、 ユーザーの要求と要求されたリソースに対して評価されます
エンティティのアクセス許可、ポリシー、および行レベルのセキュリティ規則に基づいてアクセスが許可または拒否される

ユーザーのロールの決定

既定のアクセス許可を持つロールはありません。 Data API ビルダーがロールを決定したら、要求を成功させるには、エンティティの permissions でそのロールの actions を定義する必要があります。

次のロール評価マトリックスは、クライアントがEntraIDを送信する JSON Web トークン (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: 要求は、実際のトークンを検証せずに、開発/テスト用の authenticated として扱われます。

システムロール

システムロールは、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

Important

指定されたアクセストークンの roles 要求に、 X-MS-API-ROLE ヘッダーに一覧表示されているロールが含まれていない場合、クライアントアプリの要求は拒否されます。

アクセス許可

アクセス許可には、次の内容が記述されています。

ロールメンバーシップに基づいてエンティティに対して要求を行うことができるのは誰ですか?
ユーザーが実行できるアクション (作成、読み取り、更新、削除、実行)
特定のアクションでアクセスできるフィールドはどれですか?
要求によって返される結果には、どの追加の制限がありますか?

アクセス許可を定義するための構文については、ランタイム構成に関する記事を参照してください。

Important

1 つのエンティティのアクセス許可構成内に複数のロールが定義されている場合があります。ただし、要求は 1 つのロールのコンテキストでのみ評価されます。

既定では、システムロール Anonymous または Authenticated
含まれている場合は、 X-MS-API-ROLE HTTP ヘッダーにロールセットが設定されます。

デフォルトで安全が確保されています

既定では、エンティティにはアクセス許可が構成されていないため、誰もエンティティにアクセスできません。また、ランタイム構成でデータベースオブジェクトが参照されていない場合、データ API ビルダーはデータベースオブジェクトを無視します。

アクション

アクション は、ロールのスコープ内のエンティティのアクセシビリティを表します。アクションは、個別に指定することも、ワイルドカードショートカット ( * (アスタリスク) を使用して指定することもできます。ワイルドカードショートカットは、エンティティ型でサポートされているすべてのアクションを表します。

テーブルとビュー: 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"
      }
    }
  ]
}

ロールの継承

DAB 2.0 ではロールの継承が導入されているため、すべてのロールで同じアクセス許可ブロックを繰り返す必要はありません。継承チェーンは次のとおりです。

named-role → authenticated → anonymous

エンティティauthenticatedが明示的に構成されていない場合、anonymousから継承されます。
名前付きロールが構成されていない場合は、authenticatedから継承されるか、anonymousも存在しない場合はauthenticatedから継承されます。

anonymousに対してアクセス許可を 1 回定義すると、すべての広範なロールが同じアクセス権を自動的に取得し、重複は必要ありません。

注

このセクションで説明する Data API Builder 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 ロールのアクセス許可を必要とせず、事前構成されていません。エンティティのアクセス許可構成内で 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 の変更とフィルターの場合、アクセス許可の構成では、前に説明したようにアクセス制御が適用されます。

階層型セキュリティモデル

データ API ビルダーでは、複数の承認レイヤーが使用されます。

エンティティレベル: アクセス可能なエンティティと操作
ポリシーレベル: 返されるデータ (要求に基づくフィルター処理)
行レベル: データベースは RLS を使用して行フィルター処理を適用します
API レベル: HTTP ヘッダーと要求の検証

次のステップ

ロールの継承 - ロール階層の構築
API ポリシー - 要求に基づいて OData フィルターを適用する
行レベルのセキュリティ - データベースレベルでデータをフィルター処理する
ベストプラクティス - セキュリティ強化のガイダンス

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-04