Microsoft Entra ID を使用して Azure Cosmos DB アカウントのロールベースのアクセス制御を構成する

適用対象: NoSQL

Azure Cosmos DB では、次のことを可能にする組み込みのロールベースのアクセス制御システムを公開しています。

• Microsoft Entra ID を使用してデータ要求を認証します。
• きめ細かいロールベースのアクセス許可モデルを使用してデータ要求を認可する。

概念

Azure Cosmos DB データ プレーンのロールベースのアクセス制御は、Azure ロールベースのアクセス制御などの他のロールベースのアクセス制御システムでよく見られる概念に基づいて構築されています。

• アクセス許可モデルは、一連のアクションで構成されます。これらの各アクションは、1 つまたは複数のデータベース操作にマップされます。 アクションの例としては、アイテムの読み取り、アイテムの書き込み、クエリの実行などがあります。
• Azure Cosmos DB ユーザーは、許可されたアクションの一覧を含む ロールの定義 を作成します。
• ロールの定義は、ロールの割り当てによって特定の Microsoft Entra ID に割り当てられます。 ロールの割り当てでは、ロールの定義が適用されるスコープも定義されます。現在、3 つのスコープがあります。
  • Azure Cosmos DB アカウント、
  • Azure Cosmos DB データベース、
  • Azure Cosmos DB コンテナー。

権限モデル

次の表では、アクセス許可モデルによって公開されるすべてのアクションを示します。

ワイルドカードは、コンテナー レベルとアイテム レベルの両方でサポートされます。

• Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*
• Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*

メタデータ要求

Azure Cosmos DB SDK は初期化中に読み取り専用のメタデータ要求を発行し、特定のデータ要求を処理します。 これらの要求により、次のようなさまざまな構成の詳細がフェッチされます。

• アカウントのグローバル構成。アカウントが使用できる Azure リージョンが含まれます。
• コンテナーのパーティション キーまたはそのインデックス作成ポリシー。
• コンテナーとそのアドレスを作成する物理パーティションの一覧。

アカウントに格納されているデータは取得されません。

アクセス許可モデルで最大限の透明度を確保するため、これらのメタデータ要求は Microsoft.DocumentDB/databaseAccounts/readMetadata アクションによって明示的にカバーされます。 このアクションは、Azure Cosmos DB SDK のいずれかを使用して Azure Cosmos DB アカウントにアクセスするすべての状況で許可する必要があります。 これは、Azure Cosmos DB 階層内の任意のレベル (つまり、アカウント、データベース、またはコンテナー) で (ロールの割り当てによって) 割り当てることができます。

アクションによって許可される実際のメタデータ要求は、Microsoft.DocumentDB/databaseAccounts/readMetadata アクションが割り当てられているスコープによって異なります。

組み込みのロールの定義

Azure Cosmos DB では、次の 2 つの組み込みロール定義が公開されています。

カスタム ロールの定義の作成

カスタム ロールの定義を作成するときは、次の情報を指定する必要があります。

• Azure Cosmos DB アカウントの名前。
• アカウントを含むリソース グループ。
• ロールの定義の種類: CustomRole。
• ロールの定義名。
• ロールで許可する アクション の一覧。
• ロール定義を割り当てることができる 1 つまたは複数のスコープ。サポートされているスコープは次のとおりです。
  • / (アカウントレベル)、
  • /dbs/<database-name> (データベースレベル)、
  • /dbs/<database-name>/colls/<container-name> (コンテナーレベル)。

Azure PowerShell の使用

読み取りアクションのみを含む MyReadOnlyRole という名前のロールを作成します。

$resourceGroupName = "<myResourceGroup>"
$accountName = "<myCosmosAccount>"
New-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -Type CustomRole -RoleName MyReadOnlyRole `
    -DataAction @( `
        'Microsoft.DocumentDB/databaseAccounts/readMetadata',
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed') `
    -AssignableScope "/"

すべてのアクションを含む MyReadWriteRole という名前のロールを作成します。

New-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -Type CustomRole -RoleName MyReadWriteRole `
    -DataAction @( `
        'Microsoft.DocumentDB/databaseAccounts/readMetadata',
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*') `
    -AssignableScope "/"

ID を取得するために作成したロールの定義を一覧表示します。

Get-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName

RoleName         : MyReadWriteRole
Id               : /subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAcc
                   ounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>
Type             : CustomRole
Permissions      : {Microsoft.Azure.Management.CosmosDB.Models.Permission}
AssignableScopes : {/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAc
                   counts/<myCosmosAccount>}

RoleName         : MyReadOnlyRole
Id               : /subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAcc
                   ounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>
Type             : CustomRole
Permissions      : {Microsoft.Azure.Management.CosmosDB.Models.Permission}
AssignableScopes : {/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAc
                   counts/<myCosmosAccount>}

Azure CLI の使用

role-definition-ro.json という名前のファイルに読み取りアクションのみを含む MyReadOnlyRole という名前のロールを作成します。

{
    "RoleName": "MyReadOnlyRole",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed"
        ]
    }]
}

resourceGroupName='<myResourceGroup>'
accountName='<myCosmosAccount>'
az cosmosdb sql role definition create --account-name $accountName --resource-group $resourceGroupName --body @role-definition-ro.json 

role-definition-rw.json という名前のファイルにすべてのアクションを含む MyReadWriteRole という名前のロールを作成します。

{
    "RoleName": "MyReadWriteRole",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}

az cosmosdb sql role definition create --account-name $accountName --resource-group $resourceGroupName --body @role-definition-rw.json 

ID を取得するために作成したロールの定義を一覧表示します。

az cosmosdb sql role definition list --account-name $accountName --resource-group $resourceGroupName

[
  {
    "assignableScopes": [
      "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>"
    ],
    "id": "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>",
    "name": "<roleDefinitionId>",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "<myResourceGroup>",
    "roleName": "MyReadWriteRole",
    "sqlRoleDefinitionGetResultsType": "CustomRole",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions"
  },
  {
    "assignableScopes": [
      "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>"
    ],
    "id": "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>",
    "name": "<roleDefinitionId>",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "<myResourceGroup>",
    "roleName": "MyReadOnlyRole",
    "sqlRoleDefinitionGetResultsType": "CustomRole",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions"
  }
]

Azure リソース マネージャーのテンプレートを作成する

Azure Resource Manager テンプレートを使用してロールの定義を作成する方法のリファレンスと例については、Microsoft.DocumentDB databaseAccounts/sqlRoleDefinitions を参照してください。

ロールの割り当ての作成

組み込みまたはカスタムのロールの定義を、自身の Microsoft Entra に関連付けることができます。 ロールの割り当てを作成するときは、次の情報を指定する必要があります。

• Azure Cosmos DB アカウントの名前。

• アカウントを含むリソース グループ。

• 割り当てるロール定義の ID。

• ロールの定義を割り当てる必要がある ID のプリンシパル ID。

• ロールの割り当てのスコープ。サポートされるスコープは次のとおりです。

  • / (アカウントレベル)
  • /dbs/<database-name> (データベースレベル)
  • /dbs/<database-name>/colls/<container-name> (コンテナーレベル)

  スコープは、ロールの定義の割り当て可能なスコープの 1 つと一致するか、そのサブスコープである必要があります。

Azure PowerShell の使用

ID にロールを割り当てます。

$resourceGroupName = "<myResourceGroup>"
$accountName = "<myCosmosAccount>"
$readOnlyRoleDefinitionId = "<roleDefinitionId>" # as fetched above
# For Service Principals make sure to use the Object ID as found in the Enterprise applications section of the Azure Active Directory portal blade.
$principalId = "<aadPrincipalId>"
New-AzCosmosDBSqlRoleAssignment -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -RoleDefinitionId $readOnlyRoleDefinitionId `
    -Scope "/" `
    -PrincipalId $principalId

Azure CLI の使用

ID にロールを割り当てます。

resourceGroupName='<myResourceGroup>'
accountName='<myCosmosAccount>'
readOnlyRoleDefinitionId='<roleDefinitionId>' # as fetched above
# For Service Principals make sure to use the Object ID as found in the Enterprise applications section of the Azure Active Directory portal blade.
principalId='<aadPrincipalId>'
az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroupName --scope "/" --principal-id $principalId --role-definition-id $readOnlyRoleDefinitionId --principal-type "ServicePrincipal"

Bicep または Azure Resource Manager テンプレートの使用

Bicep テンプレートを使用した組み込みの割り当てについては、以下のとおりです。

resource sqlRoleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2023-04-15' = {
  name: guid(<roleDefinitionId>, <aadPrincipalId>, <databaseAccountResourceId>)
  parent: databaseAccount
  properties:{
    principalId: <aadPrincipalId>
    roleDefinitionId: '/${subscription().id}/resourceGroups/<databaseAccountResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>'
    scope: <databaseAccountResourceId>
  }
}

Azure Resource Manager テンプレートを使用してロールの割り当てを作成する方法のリファレンスと例については、Microsoft.DocumentDB databaseAccounts/sqlRoleAssignments を参照してください。

Microsoft Entra ID を使用して SDK を初期化する

Azure Cosmos DB ロールベースのアクセス制御をアプリケーションで使用するには、Azure Cosmos DB SDK を初期化する方法を更新する必要があります。 アカウントのプライマリ キーを渡す代わりに、TokenCredential クラスのインスタンスを渡す必要があります。 このインスタンスは、使用する ID に代わって、Microsoft Entra トークンをフェッチするために必要なコンテキストを Azure Cosmos DB SDK に提供します。

TokenCredential インスタンスの作成方法は、この記事では取り扱いません。 使用する Microsoft Entra ID の種類 (ユーザー プリンシパル、サービス プリンシパル、グループなど) に応じて、このようなインスタンスを作成するにはさまざまな方法があります。 最も重要なのは、TokenCredential インスタンスが自分のロールを割り当てた ID (プリンシパル ID) を解決できる必要があることです。 TokenCredential クラスを作成する例を次に示します。

• .NET の場合
• Java の場合
• JavaScript の場合
• Python を使用

次の例では、ClientSecretCredential インスタンスでサービス プリンシパルを使用しています。

.NET の場合

Azure Cosmos DB ロールベースのアクセス制御は現在、.NET SDK V3 でサポートされています。

TokenCredential servicePrincipal = new ClientSecretCredential(
    "<azure-ad-tenant-id>",
    "<client-application-id>",
    "<client-application-secret>");
CosmosClient client = new CosmosClient("<account-endpoint>", servicePrincipal);

Java の場合

Azure Cosmos DB のロールベースのアクセス制御は現在、Java SDK V4 でサポートされています。

TokenCredential ServicePrincipal = new ClientSecretCredentialBuilder()
    .authorityHost("https://login.microsoftonline.com")
    .tenantId("<azure-ad-tenant-id>")
    .clientId("<client-application-id>")
    .clientSecret("<client-application-secret>")
    .build();
CosmosAsyncClient Client = new CosmosClientBuilder()
    .endpoint("<account-endpoint>")
    .credential(ServicePrincipal)
    .build();

JavaScript の場合

Azure Cosmos DB ロールベースのアクセス制御は現在、JavaScript SDK V3 でサポートされています。

const servicePrincipal = new ClientSecretCredential(
    "<azure-ad-tenant-id>",
    "<client-application-id>",
    "<client-application-secret>");
const client = new CosmosClient({
    endpoint: "<account-endpoint>",
    aadCredentials: servicePrincipal
});

Python を使用

Azure Cosmos DB ロールベースのアクセス制御は、Python SDK バージョン 4.3.0b4 以降でサポートされています。

aad_credentials = ClientSecretCredential(
    tenant_id="<azure-ad-tenant-id>",
    client_id="<client-application-id>",
    client_secret="<client-application-secret>")
client = CosmosClient("<account-endpoint>", aad_credentials)

REST API で要求を認証

REST API 承認ヘッダーを構築するときは、次の例に示すように、type パラメーターを Microsoft Entra ID に設定し、ハッシュ署名 (sig) を OAuth トークンに設定します。

type=aad&ver=1.0&sig=<token-from-oauth>

データ エクスプローラーの使用

データ エクスプローラー内での Azure Cosmos DB ロールベースのアクセス制御の使用 (Azure portal または https://cosmos.azure.com のいずれかで公開) は、[Entra ID RBAC の有効化] 設定によって管理されます。 データ エクスプローラー インターフェイスの右上にある "ホイール" アイコンを介してこの設定にアクセスできます。

この設定には、次の 3 つの有効値があります。

• 自動 (既定): このモードでは、アカウントでキーの使用が無効になった場合、ロールベースのアクセス制御が自動的に使用されます。 それ以外の場合は、データ エクスプローラーでデータ要求にアカウント キーが使用されます。

• True: このモードでは、ロールベースのアクセスは常にデータ エクスプローラーのデータ要求に使用されます。 アカウントでロールベースのアクセスが有効になっていない場合、要求は失敗します。

• False: このモードでは、アカウント キーは常にデータ エクスプローラーのデータ要求に使用されます。 アカウントでキーの使用が無効になっている場合、要求は失敗します。

Azure portal データ エクスプローラーでロールベースのアクセスを有効にするモードを使用する場合は、データ要求を行う前に、[Entra ID RBAC のログイン] ボタン (データ エクスプローラーのコマンド バーにあります) をクリックする必要があります。 これは、cosmos.azure.com で Cosmos Explorer を使用する場合は必要ありません。 データ アクセスを有効にするために、サインインした ID に適切なロール定義が割り当てられていることを確認してください。

また、アカウント キーを使用するモードに変更すると、サインインしている ID の代わりに主キーを取得するための要求がトリガーされる可能性があることにも注意してください。

監査データの要求

Azure Cosmos DB ロールベースのアクセス制御を使用する場合、診断ログは各データ操作の ID と承認情報によって拡張されます。 この拡張により、詳細な監査を実行し、Azure Cosmos DB アカウントに送信されるすべてのデータ要求に使われる Microsoft Entra ID を取得できます。

この追加情報は DataPlaneRequests ログ カテゴリにあり、2 つの追加列で構成されています。

• aadPrincipalId_g は、要求を認証するために使われた Microsoft Entra ID のプリンシパル ID を表示します。
• aadAppliedRoleAssignmentId_g は、要求を認可するときに使用されたロール割り当てを表示します。

ロールベースのアクセス制御を唯一の認証方法として適用する

ロールベースのアクセス制御を介して排他的に Azure Cosmos DB に接続するようにクライアントに強制したい場合は、アカウントの主/セカンダリ キーを無効にすることができます。 その場合、主/セカンダリ キーまたはリソース トークンを使用する着信要求はアクティブに拒否されます。

Azure リソース マネージャー テンプレートの使用

Azure Resource Manager テンプレートを使用して Azure Cosmos DB アカウントを作成または更新する場合は、disableLocalAuth プロパティを true に設定します。

"resources": [
    {
        "type": " Microsoft.DocumentDB/databaseAccounts",
        "properties": {
            "disableLocalAuth": true,
            // ...
        },
        // ...
    },
    // ...
 ]

制限

• Azure Cosmos DB アカウントごとに、最大 100 のロール定義と 2000 のロール割り当てを作成できます。
• ロール定義は、Azure Cosmos DB アカウントと同じ Microsoft Entra テナントに属する Microsoft Entra ID にのみ割り当てることができます。
• 現在、Microsoft Entra グループの解決は、200 を超えるグループに属する ID ではサポートされていません。
• Microsoft Entra トークンは、現在、Azure Cosmos DB サービスに送信される個々の要求と共にヘッダーとして渡されるため、全体的なペイロード サイズが増加します。

よく寄せられる質問

このセクションには、ロールベースのアクセス制御と Azure Cosmos DB についてよくある質問を含んでいます。

データ プレーンのロールベースのアクセス制御をサポートしている Azure Cosmos DB API はどれですか?

現時点では、NoSQL API のみがサポートされています。

Azure portal からロールの定義とロールの割り当てを管理することはできますか。

ロール管理の Azure portal サポートはまだ利用できません。

Azure Cosmos DB API for NoSQL のどの SDK がロールベースのアクセス制御をサポートしていますか。

.NET V3、Java V4、JavaScript V3、Python V4.3+ SDKs が現在のところ、サポートされています。

Microsoft Entra トークンは、有効期限が切れると Azure Cosmos DB SDK によって自動的に更新されますか。

はい。

ロールベースのアクセス制御を使用する場合、アカウントの主/セカンダリ キーの使用を無効にすることはできますか。

はい。「ロールベースのアクセス制御を唯一の認証方法として適用する」を参照してください。

次のステップ

• Azure Cosmos DB 内のデータへのセキュリティで保護されたアクセスの概要を理解します。
• Azure Cosmos DB 管理のロールベースのアクセス制御の詳細について説明します。