Udostępnij za pośrednictwem

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

  • Dotyczy: ✅ NoSQL

DOTYCZY: NoSQL

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ć bazami danych i kontenerami dla płaszczyzny sterowania, zobacz Udzielanie dostępu opartemu na rolach płaszczyzny sterowania.

Wymagania wstępne

  • Konto 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 właściwości id. 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 / Notatka

W tym przykładzie wartość id byłaby /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 właściwości Id. 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 / Notatka

W tym przykładzie wartość Id byłaby /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, 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 / Notatka

    W tym przykładzie wartość id byłaby /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"

    Wskazówka

    Jeśli próbujesz udzielić kontroli dostępu opartej na rolach płaszczyzny danych do własnej tożsamości, możesz użyć tego polecenia, aby uzyskać tożsamość:

    az ad signed-in-user show

    Aby uzyskać więcej informacji, zobacz az ad signed-in-user.

  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. Sprawdź 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 = deployer().objectId

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>'

    Wskazówka

    Jeśli próbujesz udzielić dostępu do płaszczyzny danych opartego na kontroli roli dla własnej tożsamości, możesz pominąć parametr identityId. Następnie szablon Bicep użyje deployer().objectId do uzyskania tożsamości podmiotu, który wdrożył ten szablon. Aby uzyskać więcej informacji, zobacz deployer.

  3. Wdróż szablon Bicep za pomocą 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 dowolnych innych tożsamości, które chcesz używać.

    Wskazówka

    Możesz powtórzyć te kroki dla dowolnej liczby tożsamości. Zazwyczaj te kroki są co najmniej powtarzane, aby umożliwić deweloperom dostęp do konta przy użyciu ich tożsamości ludzkiej. Możesz również powtórzyć te kroki, aby umożliwić aplikacjom dostęp do zasobów przy użyciu tożsamości zarządzanej.

  1. Użyj Get-AzCosmosDBAccount aby uzyskać 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 / Notatka

    W tym przykładzie wartość Id byłaby /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

    Wskazówka

    Jeśli próbujesz udzielić kontroli dostępu opartej na rolach warstwy danych do własnej tożsamości, możesz użyć tego polecenia, aby uzyskać informacje o tożsamości:

    Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName

    Aby uzyskać więcej informacji, zobacz Get-AzADUser.

  4. Wyświetl listę wszystkich przypisań ról dla konta usługi Azure Cosmos DB for NoSQL przy użyciu polecenia Get-AzCosmosDBSqlRoleAssignment. Sprawdź 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);

Container container = client.GetContainer("<database-name>", "<container-name>");

await container.ReadItemAsync<dynamic>("<item-id>", new PartitionKey("<partition-key>"));

Ważne

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

Powiązana treść