Acesso seguro aos dados no Azure Cosmos DB
APLICA-SE A: 
NoSQL
Este artigo fornece uma visão geral do controle de acesso a dados no Azure Cosmos DB.
O Azure Cosmos DB fornece três maneiras de controlar o acesso aos seus dados.
| Tipo de controle de acesso | Características |
|---|---|
| Chaves primárias/secundárias | Segredo partilhado que permite qualquer gestão ou operação de dados. Ele vem em variantes de leitura-gravação e somente leitura. |
| Controle de acesso baseado em função (RBAC) | Modelo de permissão refinado e baseado em função usando identidades do Microsoft Entra para autenticação. |
| Tokens de recursos | Modelo de permissão refinado baseado em usuários e permissões nativos do Azure Cosmos DB. |
Chaves primárias/secundárias
As chaves primárias/secundárias fornecem acesso a todos os recursos administrativos da conta do banco de dados. Cada conta consiste em duas chaves: uma chave primária e uma chave secundária. O objetivo das chaves duplas é permitir que você regenere, ou role, chaves, fornecendo acesso contínuo à sua conta e dados. Para saber mais sobre chaves primárias/secundárias, consulte Visão geral da segurança do banco de dados no Azure Cosmos DB.
Para ver as chaves da sua conta, no menu à esquerda, selecione Chaves. Em seguida, selecione o ícone Exibir à direita de cada tecla. Selecione o botão Copiar para copiar a chave selecionada. Você pode ocultá-los depois, selecionando o mesmo ícone por chave, que atualiza o ícone para um botão Ocultar .
Rotação e regeneração de chaves
Nota
A seção a seguir descreve as etapas para girar e regenerar chaves para a API para NoSQL. Se você estiver usando uma API diferente, consulte as seções API para MongoDB, API para Cassandra, API para Gremlin ou API para Tabela.
Para monitorar sua conta em busca de atualizações e regeneração de chaves, consulte Monitorar sua conta do Azure Cosmos DB para atualizações de chaves e regeneração de chaves.
O processo de rotação e regeneração de chaves é simples. Primeiro, verifique se seu aplicativo está usando consistentemente a chave primária ou a chave secundária para acessar sua conta do Azure Cosmos DB. Em seguida, siga as etapas na próxima seção.
- Se o seu aplicativo estiver usando a chave primária no momento
- Se o seu aplicativo estiver usando a chave secundária no momento
Vá para sua conta do Azure Cosmos DB no portal do Azure.
Selecione Teclas no menu esquerdo e, em seguida, selecione Regenerar Chave Secundária nas reticências à direita da sua chave secundária.
Valide se a nova chave secundária funciona consistentemente na sua conta do Azure Cosmos DB. A regeneração de chaves pode levar de um minuto a várias horas, dependendo do tamanho da conta do Azure Cosmos DB.
Substitua sua chave primária pela chave secundária em seu aplicativo.
Volte para o portal do Azure e acione a regeneração da chave primária.
Exemplo de código para usar uma chave primária
O exemplo de código a seguir ilustra como usar um ponto de extremidade de conta do Azure Cosmos DB e uma chave primária para instanciar um CosmosClient:
// Read the Azure Cosmos DB endpointUrl and authorization keys from config.
// These values are available from the Azure portal on the Azure Cosmos DB account blade under "Keys".
// Keep these values in a safe and secure location. Together they provide Administrative access to your Azure Cosmos DB account.
private static readonly string endpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
private static readonly string authorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];
CosmosClient client = new CosmosClient(endpointUrl, authorizationKey);
Controlo de acesso baseado em funções
O Azure Cosmos DB expõe um sistema RBAC interno que permite:
- Autentique suas solicitações de dados com uma identidade do Microsoft Entra.
- Autorize suas solicitações de dados com um modelo de permissão refinado e baseado em funções.
O RBAC do Azure Cosmos DB é o método de controle de acesso ideal em situações em que:
- Você não quer usar um segredo compartilhado como a chave primária e prefere confiar em um mecanismo de autenticação baseado em token.
- Você deseja usar identidades do Microsoft Entra para autenticar suas solicitações.
- Você precisa de um modelo de permissão refinado para restringir rigorosamente quais operações de banco de dados suas identidades podem executar.
- Você deseja materializar suas políticas de controle de acesso como "funções" que você pode atribuir a várias identidades.
Para saber mais sobre o RBAC do Azure Cosmos DB, consulte Configurar o controle de acesso baseado em função para sua conta do Azure Cosmos DB.
Para obter informações e código de exemplo para configurar o RBAC para o Azure Cosmos DB para MongoDB, consulte Configurar controle de acesso baseado em função para seu Azure Cosmos DB para MongoDB.
Tokens de recursos
Os tokens de recursos fornecem acesso aos recursos do aplicativo em um banco de dados. Tokens de recursos:
- Forneça acesso a contêineres específicos, chaves de partição, documentos e anexos.
- São criados quando um usuário recebe permissões para um recurso específico.
- São recriados quando um recurso de permissão é acionado por uma chamada POST, GET ou PUT.
- Utilize um token de recurso hash criado especificamente para o utilizador, recurso e permissão.
- Estão vinculados ao tempo com um período de validade personalizável. O período de tempo válido padrão é de uma hora. O tempo de vida do token, no entanto, pode ser explicitamente especificado, até um máximo de 24 horas.
- Forneça uma alternativa segura para fornecer a chave primária.
- Permita que os clientes leiam, gravem e excluam recursos na conta do Azure Cosmos DB de acordo com as permissões que lhes foram concedidas.
Você pode usar um token de recurso (criando usuários e permissões do Azure Cosmos DB) quando quiser fornecer acesso a recursos em sua conta do Azure Cosmos DB para um cliente que não pode ser confiável com a chave primária.
Os tokens de recursos do Azure Cosmos DB fornecem uma alternativa segura que permite que os clientes leiam, gravem e excluam recursos em sua conta do Azure Cosmos DB de acordo com as permissões concedidas e sem a necessidade de uma chave primária ou somente leitura.
Aqui está um padrão de design típico pelo qual os tokens de recursos podem ser solicitados, gerados e entregues aos clientes:
Um serviço intermediário é configurado para servir um aplicativo móvel para compartilhar fotos do usuário.
O serviço de camada intermediária possui a chave primária da conta do Azure Cosmos DB.
O aplicativo de fotos é instalado em dispositivos móveis do usuário.
Ao entrar, o aplicativo de fotos estabelece a identidade do usuário com o serviço intermediário. Este mecanismo de estabelecimento da identidade depende exclusivamente da aplicação.
Depois que a identidade é estabelecida, o serviço de camada intermediária solicita permissões com base na identidade.
O serviço de camada intermediária envia um token de recurso de volta para o aplicativo do telefone.
O aplicativo de telefone pode continuar a usar o token de recurso para acessar diretamente os recursos do Azure Cosmos DB com as permissões definidas pelo token de recurso e para o intervalo permitido pelo token de recurso.
Quando o token de recurso expira, as solicitações subsequentes recebem uma exceção 401 não autorizada. Neste ponto, o aplicativo de telefone restabelece a identidade e solicita um novo token de recurso.
A geração e o gerenciamento de tokens de recursos são manipulados pelas bibliotecas de cliente nativas do Azure Cosmos DB. No entanto, se você usar REST, deverá construir os cabeçalhos de solicitação/autenticação. Para obter mais informações sobre como criar cabeçalhos de autenticação para REST, consulte Controle de acesso em recursos do Azure Cosmos DB ou o código-fonte do nosso SDK do .NET ou SDK do Node.js.
Para obter um exemplo de um serviço de camada intermediária usado para gerar ou intermediar tokens de recurso, consulte o aplicativo ResourceTokenBroker.
Utilizadores
Os usuários do Azure Cosmos DB estão associados a um banco de dados do Azure Cosmos DB. Cada banco de dados pode conter zero ou mais usuários do Azure Cosmos DB. O exemplo de código a seguir mostra como criar um usuário do Azure Cosmos DB usando o Azure Cosmos DB .NET SDK v3.
// Create a user.
Database database = client.GetDatabase("SalesDatabase");
User user = await database.CreateUserAsync("User 1");
Nota
Cada usuário do Azure Cosmos DB tem um ReadAsync() método que você pode usar para recuperar a lista de permissões associadas ao usuário.
Permissões
Um recurso de permissão é associado a um usuário e atribuído a um recurso específico. Cada usuário pode conter zero ou mais permissões. Um recurso de permissão fornece acesso a um token de segurança de que o usuário precisa ao tentar acessar um contêiner ou dados específicos em uma chave de partição específica. Há dois níveis de acesso disponíveis que podem ser fornecidos por um recurso de permissão:
- Todos: O usuário tem permissão total sobre o recurso.
- Ler: O usuário só pode ler o conteúdo do recurso, mas não pode executar operações de gravação, atualização ou exclusão no recurso.
Nota
Para executar procedimentos armazenados, o usuário deve ter a permissão Todos no contêiner no qual o procedimento armazenado será executado.
Se você habilitar os logs de diagnóstico em solicitações de plano de dados, as duas propriedades a seguir correspondentes à permissão serão registradas:
resourceTokenPermissionId: Esta propriedade indica a ID de permissão do token de recurso que você especificou.
resourceTokenPermissionMode: Esta propriedade indica o modo de permissão que você definiu quando criou o token de recurso. O modo de permissão pode ter valores como Tudo ou Leitura.
Exemplo de código para criar permissão
O exemplo de código a seguir mostra como criar um recurso de permissão, ler o token de recurso do recurso de permissão e associar as permissões ao usuário que você acabou de criar.
// Create a permission on a container and specific partition key value
Container container = client.GetContainer("SalesDatabase", "OrdersContainer");
await user.CreatePermissionAsync(
new PermissionProperties(
id: "permissionUser1Orders",
permissionMode: PermissionMode.All,
container: container,
resourcePartitionKey: new PartitionKey("012345")));
Exemplo de código para permissão de leitura para usuário
O trecho de código a seguir mostra como recuperar a permissão associada ao usuário que você criou e instanciar uma nova CosmosClient para o usuário, com escopo para uma única chave de partição.
// Read a permission, create user client session.
Permission permission = await user.GetPermission("permissionUser1Orders").ReadAsync();
CosmosClient client = new CosmosClient(accountEndpoint: "MyEndpoint", authKeyOrResourceToken: permission.Resource.Token);
Diferenças entre RBAC e tokens de recursos
| Assunto | RBAC | Tokens de recursos |
|---|---|---|
| Autenticação | Com o Microsoft Entra ID. | Com base nos usuários nativos do Azure Cosmos DB. A integração de tokens de recursos com o Microsoft Entra ID requer trabalho extra para fazer a ponte entre as identidades do Microsoft Entra e os usuários do Azure Cosmos DB. |
| Autorização | Baseado em funções: as definições de função mapeiam ações permitidas e podem ser atribuídas a várias identidades. | Baseado em permissão: para cada usuário do Azure Cosmos DB, você precisa atribuir permissões de acesso a dados. |
| Escopo do token | Um token Microsoft Entra carrega a identidade do solicitante. Essa identidade é comparada com todas as definições de função atribuídas para executar a autorização. | Um token de recurso carrega a permissão concedida a um usuário específico do Azure Cosmos DB em um recurso específico do Azure Cosmos DB. Solicitações de autorização em recursos diferentes podem exigir tokens diferentes. |
| Atualização de token | O token do Microsoft Entra é atualizado automaticamente pelos SDKs do Azure Cosmos DB quando expira. | Não há suporte para a atualização do token de recurso. Quando um token de recurso expira, um novo precisa ser emitido. |
Adicionar usuários e atribuir funções
Para adicionar o acesso de leitor de conta do Azure Cosmos DB à sua conta de usuário, peça a um proprietário de assinatura que execute as seguintes etapas no portal do Azure.
Abra o portal do Azure e selecione sua conta do Azure Cosmos DB.
Selecione Controlo de acesso (IAM) .
Selecione Adicionar atribuição de função para abrir a página Adicionar>atribuição de função.
Atribua a seguinte função. Para obter etapas detalhadas, consulte Atribuir funções do Azure usando o portal do Azure.
Definição Valor Função Leitor de contas do Cosmos DB. Atribuir acesso a Usuário, grupo ou entidade de serviço. Membros O usuário, grupo ou aplicativo em seu diretório ao qual você deseja conceder acesso. 
A entidade agora pode ler os recursos do Azure Cosmos DB.
Excluir ou exportar dados do usuário
Como um serviço de banco de dados, o Azure Cosmos DB permite pesquisar, selecionar, modificar e excluir quaisquer dados localizados em seu banco de dados ou contêineres. É sua responsabilidade usar as APIs fornecidas e definir a lógica necessária para encontrar e apagar quaisquer dados pessoais, se necessário.
Cada API multimodelo (SQL, MongoDB, Gremlin, Cassandra ou Table) fornece SDKs de linguagem diferentes que contêm métodos para pesquisar e excluir dados com base em predicados personalizados. Você também pode habilitar o recurso de tempo de vida (TTL) para excluir dados automaticamente após um período especificado, sem incorrer em mais custos.
Nota
Para obter informações sobre a visualização ou eliminação de dados pessoais, veja Azure Data Subject Requests for the GDPR (Pedidos de Titulares de Dados do Azure relativos aos RGPD). Para obter mais informações sobre o GDPR, consulte a seção GDPR da Central de Confiabilidade da Microsoft e a seção GDPR do portal Service Trust.
Próximos passos
- Para saber mais sobre a segurança do banco de dados do Azure Cosmos DB, consulte Segurança do banco de dados do Azure Cosmos DB.
- Para saber como construir tokens de autorização do Azure Cosmos DB, consulte Controle de acesso em recursos do Azure Cosmos DB.
- Para obter exemplos de gerenciamento de usuários com usuários e permissões, consulte Exemplos de gerenciamento de usuários do .NET SDK v3.
- Para obter informações e código de exemplo para configurar o RBAC para o Azure Cosmos DB para MongoDB, consulte Configurar controle de acesso baseado em função para seu Azure Cosmos DB para MongoDB.