Udostępnij za pośrednictwem

Używanie kontroli dostępu opartej na rolach płaszczyzny danych w usłudze Azure Cosmos DB for NoSQL

  • Artykuł

DOTYCZY: NoSQL

Diagram bieżącej lokalizacji (kontrola dostępu oparta na rolach) w sekwencji przewodnika wdrażania.

Napiwek

Odwiedź naszą nową galerię przykładów, aby zapoznać się z najnowszymi przykładami dotyczącymi tworzenia nowych aplikacji

W tym artykule opisano kroki udzielania tożsamości dostępu do zarządzania danymi na koncie usługi Azure Cosmos DB for NoSQL.

Ważne

Kroki opisane w tym artykule obejmują tylko dostęp do płaszczyzny danych w celu wykonywania operacji na poszczególnych elementach i uruchamiania zapytań. Aby dowiedzieć się, jak zarządzać rolami, definicjami i przypisaniami dla płaszczyzny sterowania, zobacz Udzielanie dostępu opartemu na rolach płaszczyzny sterowania.

Wymagania wstępne

  • Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
  • Istniejące konto usługi Azure Cosmos DB for NoSQL.
  • Co najmniej jedna istniejąca tożsamość w identyfikatorze Entra firmy Microsoft.

Przygotowywanie definicji roli

Najpierw należy przygotować definicję roli z listą dataActions , aby udzielić dostępu do odczytu, wykonywania zapytań i zarządzania danymi w usłudze Azure Cosmos DB for NoSQL.

Ważne

Uzyskanie istniejącej definicji roli płaszczyzny danych wymaga następujących uprawnień płaszczyzny sterowania:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Aby uzyskać więcej informacji, zobacz udzielanie dostępu opartemu na rolach płaszczyzny sterowania.

Wyświetl listę wszystkich definicji ról skojarzonych z kontem usługi Azure Cosmos DB for NoSQL przy użyciu polecenia az cosmosdb sql role definition list. Przejrzyj dane wyjściowe i znajdź definicję roli o nazwie Współautor danych wbudowanych w usłudze Cosmos DB. Dane wyjściowe zawierają unikatowy identyfikator definicji roli we id właściwości . Zapisz tę wartość, ponieważ jest ona wymagana do użycia w kroku przypisania w dalszej części tego przewodnika.

az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

[
  ...,
  {
    "assignableScopes": [
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    ],
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "msdocs-identity-example",
    "roleName": "Cosmos DB Built-in Data Contributor",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
    "typePropertiesType": "BuiltInRole"
  }
  ...
]

Uwaga

W tym przykładzie id wartość to /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. W tym przykładzie użyto fikcyjnych danych, a identyfikator będzie inny niż w tym przykładzie.

Użyj Get-AzCosmosDBSqlRoleDefinition polecenia , aby wyświetlić listę wszystkich definicji ról skojarzonych z kontem usługi Azure Cosmos DB for NoSQL. Przejrzyj dane wyjściowe i znajdź definicję roli o nazwie Współautor danych wbudowanych w usłudze Cosmos DB. Dane wyjściowe zawierają unikatowy identyfikator definicji roli we Id właściwości . Zapisz tę wartość, ponieważ jest ona wymagana do użycia w kroku przypisania w dalszej części tego przewodnika.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters

Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName                   : Cosmos DB Built-in Data Contributor
Type                       : BuiltInRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions :

Uwaga

W tym przykładzie Id wartość to /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. W tym przykładzie użyto fikcyjnych danych, a identyfikator będzie inny niż w tym przykładzie. Jednak identyfikator (00000000-0000-0000-0000-000000000002) jest unikatowy we wszystkich definicjach ról na twoim koncie.

Przypisywanie roli do tożsamości

Teraz przypisz nowo zdefiniowaną rolę do tożsamości, aby aplikacje mogły uzyskiwać dostęp do danych w usłudze Azure Cosmos DB for NoSQL.

Ważne

Utworzenie nowego przypisania roli płaszczyzny danych wymaga następujących uprawnień płaszczyzny sterowania:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write

Aby uzyskać więcej informacji, zobacz udzielanie dostępu opartemu na rolach płaszczyzny sterowania.

  1. Użyj az cosmosdb show polecenia , aby uzyskać unikatowy identyfikator bieżącego konta.

    az cosmosdb show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-nosql-account>" \
    --query "{id:id}"

  2. Zwróć uwagę na dane wyjściowe poprzedniego polecenia. Zapisz wartość id właściwości dla tego konta, ponieważ jest ona wymagana do użycia w następnym kroku.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
}

    Uwaga

    W tym przykładzie id wartość to /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. W tym przykładzie użyto fikcyjnych danych, a identyfikator będzie inny niż w tym przykładzie.

  3. Przypisz nową rolę przy użyciu polecenia az cosmosdb sql role assignment create. Użyj wcześniej zarejestrowanych identyfikatorów definicji roli do argumentu --role-definition-id i unikatowego identyfikatora tożsamości do argumentu --principal-id . Na koniec użyj identyfikatora konta dla argumentu --scope .

    az cosmosdb sql role assignment create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --role-definition-id "<id-of-new-role-definition>" \
    --principal-id "<id-of-existing-identity>" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"

  4. Użyj az cosmosdb sql role assignment list polecenia , aby wyświetlić listę wszystkich przypisań ról dla konta usługi Azure Cosmos DB for NoSQL. Przejrzyj dane wyjściowe, aby upewnić się, że przypisanie roli zostało utworzone.

    az cosmosdb sql role assignment list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

  1. Utwórz nowy plik Bicep, aby zdefiniować przypisanie roli. Nadaj plikowi nazwę data-plane-role-assignment.bicep.

    metadata description = 'Assign RBAC role for data plane access to Azure Cosmos DB for NoSQL.'

@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string

@description('Id of the role definition to assign to the targeted principal in the context of the account.')
param roleDefinitionId string

@description('Id of the identity/principal to assign this role in the context of the account.')
param identityId string

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
  name: accountName
}

resource assignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = {
  name: guid(roleDefinitionId, identityId, account.id)
  parent: account
  properties: {
    principalId: identityId
    roleDefinitionId: roleDefinitionId
    scope: account.id
  }
}

output assignmentId string = assignment.id

  2. Utwórz nowy plik parametrów Bicep o nazwie data-plane-role-assignment.bicepparam. W tym pliku parametrów przypisz nazwę istniejącego konta usługi Azure Cosmos DB for NoSQL do accountName parametru, wcześniej zarejestrowanych identyfikatorów definicji roli do parametru roleDefinitionId i unikatowy identyfikator tożsamości do parametru identityId .

    using './data-plane-role-assignment.bicep'

param accountName = '<name-of-existing-nosql-account>'
param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

  3. Wdróż szablon Bicep przy użyciu polecenia az deployment group create.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-assignment.bicepparam \
    --template-file data-plane-role-assignment.bicep

  4. Powtórz te kroki, aby udzielić dostępu do konta z innych tożsamości, których chcesz użyć.

    Napiwek

    Możesz powtórzyć te kroki dla dowolnej liczby tożsamości. Zazwyczaj te kroki są co najmniej powtarzane w celu umożliwienia deweloperom dostępu do konta przy użyciu tożsamości ludzkiej i umożliwienia aplikacjom dostępu przy użyciu tożsamości zarządzanej.

  1. Użyj Get-AzCosmosDBAccount polecenia , aby pobrać metadane dla bieżącego konta.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-nosql-account>"
}    
Get-AzCosmosDBAccount @parameters | Select -Property Id

  2. Zwróć uwagę na dane wyjściowe poprzedniego polecenia. Zapisz wartość Id właściwości dla tego konta, ponieważ jest ona wymagana do użycia w następnym kroku.

    Id
--    
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql

    Uwaga

    W tym przykładzie Id wartość to /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. W tym przykładzie użyto fikcyjnych danych, a identyfikator będzie inny niż w tym przykładzie.

  3. Użyj polecenia New-AzCosmosDBSqlRoleAssignment , aby przypisać nową rolę. Użyj wcześniej zarejestrowanych identyfikatorów definicji roli do parametru RoleDefinitionId i unikatowego identyfikatora tożsamości do parametru PrincipalId . Na koniec użyj identyfikatora konta dla parametru Scope .

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleDefinitionId = "<id-of-new-role-definition>"
    PrincipalId = "<id-of-existing-identity>"
    Scope = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
}    
New-AzCosmosDBSqlRoleAssignment @parameters

  4. Wyświetl listę wszystkich przypisań ról dla konta usługi Azure Cosmos DB for NoSQL przy użyciu polecenia Get-AzCosmosDBSqlRoleAssignment. Przejrzyj dane wyjściowe, aby upewnić się, że przypisanie roli zostało utworzone.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleAssignment @parameters

Weryfikowanie dostępu do płaszczyzny danych w kodzie

Na koniec sprawdź, czy prawidłowo udzielono dostępu przy użyciu kodu aplikacji i zestawu Azure SDK w preferowanym języku programowania.

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Ważne

W tym przykładzie kodu są używane biblioteki Microsoft.Azure.Cosmos i Azure.Identity z narzędzia NuGet.