Proteger o acesso aos dados no Azure Cosmos DB
APLICA-SE A: 
NoSQL
Este artigo fornece uma visão geral do controle de acesso aos 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ária e secundária | Segredo compartilhado que permite qualquer operação de gerenciamento ou de dados. Ele é fornecido em variantes de leitura/gravação e somente leitura. |
| RBAC (controle de acesso baseado em função) | Modelo de permissão refinada e baseado em função usando identidades do Microsoft Entra para autenticação. |
| Tokens de recurso | Modelo de permissão refinada baseado em permissões e usuários nativos do Azure Cosmos DB. |
Chaves primária/secundária
As chaves primária/secundária fornecem acesso a todos os recursos administrativos para a conta de banco de dados. Cada conta é formada por duas chaves: uma chave primária e uma chave secundária. A finalidade das chaves duplas é permitir que você regenere ou role as chaves, fornecendo acesso contínuo à sua conta e aos 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 conta, no menu à esquerda, selecione Chaves. Em seguida, selecione o ícone Exibir à direita de cada chave. Selecione o botão Copiar para copiar a chave selecionada. Você pode ocultá-los posteriormente selecionando o mesmo ícone por chave, que atualiza o ícone para um botão Ocultar.
Rotação e regeneração de chaves
Observação
A seção a seguir descreve as etapas para fazer a rotação e a regeneração das chaves da API do NoSQL. Se você estiver usando uma API diferente, veja as seções API do MongoDB, API do Cassandra, API do Gremlin e API de Tabela.
Para monitorar sua conta para atualizações de chave e regeneração de chave, consulte Monitorar sua conta do Azure Cosmos DB para obter atualizações de chave e regeneração de chave.
O processo de rotação e regeneração de chave é simples. Primeiro, configure seu aplicativo para usar a chave primária ou 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
Acesse sua conta do Azure Cosmos DB no portal do Azure.
Selecione Chaves no menu à esquerda e selecione Regenerar Chave Secundária nas reticências à direita da chave secundária.
Valide se a nova chave secundária funciona corretamente em sua conta do Azure Cosmos DB. A regeneração de chaves pode demorar menos de um minuto ou até algumas horas, dependendo do tamanho da conta do Azure Cosmos DB.
Substitua a chave primária pela chave secundária em seu aplicativo.
Volte para o portal do Azure e dispare a regeneração da chave primária.
Exemplo de código para uso de 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);
Controle de acesso baseado em função
O Azure Cosmos DB expõe um sistema RBAC interno que permite:
- Autentique suas solicitações de dados com uma identidade do Microsoft Entra.
- Autorizar as solicitações de dados com um modelo de permissão refinado e baseado em função.
O RBAC do Azure Cosmos DB é o método de controle de acesso ideal em situações em que:
- Você não deseja usar um segredo compartilhado como a chave primária e prefere contar com um mecanismo de autenticação baseado em token.
- Você deseja usar as 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 têm permissão para 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 for MongoDB, consulte Configurar o controle de acesso baseado em função para o Azure Cosmos DB for MongoDB.
Tokens de recurso
Os tokens de recurso fornecem acesso aos recursos do aplicativo em um banco de dados. Tokens de recurso:
- Forneça acesso a contêineres, chaves de partição, documentos e anexos específicos.
- 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.
- Use um token de recurso de hash construído especificamente para o usuário, o recurso e a permissão.
- São associados a um período de validade personalizável. O intervalo de tempo válido padrão é de uma hora. O tempo de vida do token, no entanto, pode ser especificado explicitamente, até um máximo de 24 horas.
- Fornecem uma alternativa segura para o fornecimento da chave primária.
- Permitir que os clientes leiam, escrevam e excluam recursos na conta do Azure Cosmos DB de acordo com as permissões concedidas.
Você pode usar um token de recurso (criando usuários e permissões do Azure Cosmos DB) quando quiser fornecer acesso aos 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 recurso do Azure Cosmos DB fornecem uma alternativa segura que permite que os clientes leiam, escrevam 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 recurso podem ser solicitados, gerados e entregues aos clientes:
Um serviço de camada intermediária é configurado para atender a um aplicativo móvel de compartilhamento de fotos do usuário.
O serviço de camada intermediária tem 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 de camada intermediária. Esse mecanismo de estabelecimento de identidade depende apenas do aplicativo.
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 móvel.
O aplicativo de telefone pode continuar usando o token de recurso para acessar diretamente recursos do Azure Cosmos DB com as permissões definidas pelo token de recurso e no intervalo permitido por ele.
Quando o token de recurso expira, as solicitações seguintes recebem uma exceção 401 de não autorizado. Neste ponto, o aplicativo de telefone restabelece a identidade e solicita um novo token de recurso.
A geração e o gerenciamento de token de recurso são tratados pelas bibliotecas de clientes 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 o controle de acesso em recursos do Azure Cosmos DB ou o código-fonte do SDK do .NET ou do 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.
Usuários
Os usuários do Azure Cosmos DB são associados a um banco de dados do Azure Cosmos DB. Cada banco de dados pode conter usuários do Azure Cosmos DB ou não conter nenhum. O exemplo de código a seguir mostra como criar um usuário do Azure Cosmos DB usando o SDK do .NET do Azure Cosmos DB v3.
// Create a user.
Database database = client.GetDatabase("SalesDatabase");
User user = await database.CreateUserAsync("User 1");
Observação
Cada usuário do Azure Cosmos DB tem um método ReadAsync() 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 dado específico em uma chave da partição específica. Há dois níveis de acesso disponíveis que podem ser fornecidos por um recurso de permissão:
- Tudo: o usuário tem permissão total no recurso.
- Leia: 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.
Observação
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 em log:
resourceTokenPermissionId: essa propriedade indica a ID de permissão do token de recurso que você especificou.
resourceTokenPermissionMode: essa propriedade indica o modo de permissão definido quando você criou o token de recurso. O modo de permissão pode ter valores como All ou Read.
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 snippet de código a seguir mostra como recuperar a permissão associada ao usuário que você criou e instanciar um novo 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 o RBAC e os tokens de recurso
| Assunto | RBAC | Tokens de recurso |
|---|---|---|
| Autenticação | Com o Microsoft Entra ID. | Com base nos usuários nativos do Azure Cosmos DB. A integração de tokens de recurso ao Microsoft Entra ID requer trabalho extra para estabelecer uma ponte com as identidades do Microsoft Entra e os usuários do Azure Cosmos DB. |
| Autorização | Baseado em função: 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 do Microsoft Entra carrega a identidade do solicitante. Essa identidade é correspondida 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 do token | O token do Microsoft Entra é atualizado automaticamente pelos SDKs do Azure Cosmos DB quando ele 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 ao proprietário de uma assinatura que execute as seguintes etapas no portal do Azure.
Abra o portal do Azure e selecione sua conta do Azure Cosmos DB.
Selecione IAM (Controle de acesso) .
Selecione Adicionar>Adicionar atribuição de função para abrir a página Adicionar atribuição de função.
Atribua a função a seguir. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.
Configuração Valor Função Leitor de Conta do Cosmos DB. Atribuir acesso a usuário, grupo ou entidade de serviço. Membros O usuário, o grupo ou o aplicativo em seu diretório ao qual você deseja conceder acesso. 
A entidade agora poderá ler 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 que você pesquise, selecione, modifique e exclua todos os dados localizados em seu banco de dados ou contêineres. É sua responsabilidade usar as APIs fornecidas e definir a lógica necessária para localizar e apagar quaisquer dados pessoais, se necessário.
Cada API de vários modelos (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 TTL (tempo de vida útil) para excluir dados automaticamente após um período especificado, sem incorrer em mais custos.
Observação
Para obter informações sobre como exibir ou excluir dados pessoais, confira Solicitações do titular dos dados do Azure para RGPD. Para obter mais informações sobre o GDPR, confira a seção GDPR da Central de Confiabilidade da Microsoft e a seção GDPR do Portal de Confiança do Serviço.
Próximas etapas
- Para saber mais sobre a segurança do banco de dados do Azure Cosmos DB, consulte a segurança do banco de dados do Azure Cosmos DB.
- Para saber como construir tokens de autorização do Azure Cosmos DB, consulte o controle de acesso nos 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 SDK do .NET v3.
- Para obter informações e código de exemplo para configurar o RBAC para o Azure Cosmos DB for MongoDB, consulte Configurar o controle de acesso baseado em função para o Azure Cosmos DB for MongoDB.