Como usar identidades gerenciadas com serviços do Azure para se conectar ao Azure Cosmos DB for NoSQL
APLICA-SE A: NoSQL
Diagrama da sequência do guia de implantação, incluindo estes locais, em ordem: Visão geral, Conceitos, Preparação, Controle de acesso baseado em função, Rede e Referência. O local "Preparar" está realçado no momento.
Este artigo analisa as etapas necessárias para criar identidades gerenciadas a serem usadas com um aplicativo implantado conectado ao Azure Cosmos DB for NoSQL.
As identidades gerenciadas são um dos muitos tipos de recursos de identidade no Microsoft Entra ID para os aplicativos usarem ao se conectar a serviços que oferecem suporte à autenticação do Microsoft Entra. As identidades gerenciadas podem ser usadas no lugar de credenciais tradicionais pertencentes a recursos, como chaves. No Azure, as identidades gerenciadas fornecem uma maneira para seus aplicativos obterem um token do Microsoft Entra para autenticar nos serviços do Azure sem que você precise escrever uma grande quantidade de código de autenticação.
Você pode usar o Microsoft Entra para se autenticar em serviços do Azure que incluem, entre outros:
- SQL do Azure
- IA do Azure
- Azure Cosmos DB
- Armazenamento do Azure
- Hubs de eventos do Azure
- Registro de Contêiner do Azure
Você pode usar identidades gerenciadas para representar a entidade de segurança que se autentica em um serviço do Azure de outros serviços do Azure que incluem, entre outros:
- Serviço de Kubernetes do Azure
- Aplicativos de Contêiner do Azure
- Máquinas Virtuais do Azure
- Azure Functions
- Serviço de Aplicativo do Azure
- Azure Spring Apps
- Azure Service Fabric
As identidades gerenciadas habilitam vários cenários seguros em que vários serviços do Azure podem se conectar uns aos outros. Alguns exemplos incluem:
- Criando uma identidade gerenciada atribuída pelo sistema para um aplicativo nos Aplicativos Spring do Azure para se conectar e consultar uma conta SQL do Azure
- Usando uma única identidade gerenciada atribuída pelo usuário com o Serviço de Kubernetes do Azure e o Azure Functions para emitir solicitações para uma conta de IA do Azure
- Usando uma identidade gerenciada para uma conta do Azure Cosmos DB para armazenar chaves no Azure Key Vault
Para saber mais, confira identidades gerenciadas para recursos do Azure.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
- Se você optar por usar o Azure PowerShell localmente:
- Instale a versão mais recente do módulo do Az PowerShell.
- Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
- Se você optar por usar o Azure Cloud Shell:
- Confira Visão geral do Azure Cloud Shell para obter mais informações.
Criar um serviço do Azure com uma identidade gerenciada atribuída pelo sistema
Criar um novo serviço do Azure com uma identidade gerenciada atribuída pelo sistema. Esta seção cria um recurso de Instâncias de Contêiner do Azure.
Use
az container create
para criar uma nova instância de contêiner. Configure a conta para usar uma identidade gerenciada atribuída pelo sistema usandoassign-identity
parâmetro .az container create \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-new-container>" \ --image mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled \ --cpu 1 \ --memory 2 \ --assign-identity
Obtenha os detalhes da identidade gerenciada atribuída pelo sistema usando
az container show
e uma consulta JMESPath.az container show \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-existing-container>" \ --query "identity"
Revise a saída do comando. Ele deve incluir os identificadores exclusivos para a identidade e o locatário.
{ "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222", "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "type": "SystemAssigned", "userAssignedIdentities": null }
Crie um novo arquivo Bicep para definir uma nova instância de contêiner. Nomeie o arquivo como container-instance.bicep. Defina as propriedades para a instância de contêiner:
Valor name
Use um parâmetro chamado instanceName
location
Defina-o para a localização do grupo de recursos identity.type
SystemAssigned
properties.osType
Linux
properties.containers[0].name
aspnet-sample
properties.containers[0].properties.image
mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled
properties.containers[0].properties.resources.requests.cpu
1
properties.containers[0].properties.resources.requests.memoryInGB
2
metadata description = 'Create Azure Container Instance resource with system-assigned managed identity.' @description('Name of the Azure Container Instances resource.') param instanceName string resource instance 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = { name: instanceName location: resourceGroup().location identity: { type: 'SystemAssigned' } properties: { osType: 'Linux' containers: [ { name: 'aspnet-sample' properties: { image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled' resources: { requests: { cpu: 1 memoryInGB: 2 } } } } ] } } output systemAssignedIdentity object = instance.identity
Crie um novo arquivo de parâmetros de Bicep chamado container-instance.
bicepparam
. Nesse arquivo de parâmetros, crie um nome exclusivo para sua instância de contêiner usando o parâmetroinstanceName
.using './container-instance.bicep' param instanceName = '<name-of-new-container-instance>'
Implante o modelo Bicep usando o
az deployment group create
. Especifique o nome do modelo Bicep, do arquivo de parâmetros e do grupo de recursos do Azure.az deployment group create \ --resource-group "<name-of-existing-resource-group>" \ --parameters "container-instance.bicepparam" \ --template-file "container-instance.bicep"
Revise a saída da implantação. A saída contém o objeto de identidade da instância de contêiner na propriedade
properties.outputs.systemAssignedIdentity.value
.{ "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222", "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "type": "SystemAssigned" }
Entre no portal do Azure (https://portal.azure.com).
Insira Instâncias de Contêiner do Azure na barra de pesquisa global.
Em Serviços, selecione Instâncias de contêiner.
No painel Instâncias de contêiner, selecione Criar.
No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:
Valor Assinatura Selecione sua Assinatura do Azure. Grupo de Recursos Crie um novo grupo de recursos ou escolha um grupo de recursos existente Nome do contêiner Forneça um nome global exclusivo Região Escolha uma região do Azure compatível com sua assinatura Dica
Você pode deixar as opções não especificadas com os valores padrão.
No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Depois que a implantação for concluída, escolha Ir para o recurso para navegar até o novo recurso de Instâncias de Contêiner do Azure.
No painel da nova instância de contêiner, selecione Identidade na seção Configurações do menu de serviço.
No painel Identidade, habilite a identidade gerenciada atribuída pelo sistema definindo a opção Status como Ativada. Em seguida, selecione Salvar e resolva todos os prompts para confirmar a alteração.
Depois que a identidade gerenciada atribuída pelo sistema estiver pronta, examine o valor da propriedade ID do objeto (entidade de segurança). O valor dessa propriedade é um identificador exclusivo da identidade.
Dica
Nesta captura de tela de exemplo, o identificador exclusivo para a identidade gerenciada atribuída pelo sistema é
bbbbbbbb-1111-2222-3333-cccccccccccc
.
Crie um objeto que represente um contêiner usando
New-AzContainerInstanceObject
e armazene-o em uma variável chamada$container
. Em seguida, use esse objeto de contêiner para criar uma nova instância de contêiner comNew-AzContainerGroup
. Configure a conta para usar uma identidade gerenciada atribuída pelo sistema definindo o parâmetroIdentityType
comoSystemAssigned
.$parameters = @{ Name = "aspnet-sample" Image = "mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled" RequestCpu = 1 RequestMemoryInGb = 2 } $container = New-AzContainerInstanceObject @parameters $parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-new-container>" Container = $container OsType = "Linux" Location = "<azure-region>" IdentityType = "SystemAssigned" } New-AzContainerGroup @parameters
Obtenha os detalhes da identidade gerenciada atribuída pelo sistema usando
Get-AzContainerGroup
eFormat-List
selecionando apenas a propriedadeIdentity
.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-existing-container>" } Get-AzContainerGroup @parameters | Format-List Identity
Revise a saída do comando. Ele deve incluir os identificadores exclusivos para a identidade e o locatário.
Identity : { "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222", "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "type": "SystemAssigned" }
Criar uma identidade gerenciada atribuída ao usuário
Crie uma identidade gerenciada atribuída pelo usuário que possa ser usada com um ou mais serviços do Azure de maneira portátil.
Use
az identity create
para criar uma nova identidade gerenciada atribuída pelo usuário em seu grupo de recursos do Azure.az identity create \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-new-managed-identity>"
Obtenha a lista de identidades gerenciadas atribuídas pelo usuário em seu grupo de recursos usando
az identity list
az identity list \ --resource-group "<name-of-existing-resource-group>"
Revise a saída do comando. Registre o valor do campo
id
à medida que esse identificador de recurso totalmente qualificado é usado para atribuir a identidade gerenciada atribuída pelo usuário ao recurso do Azure.{ "clientId": "11112222-bbbb-3333-cccc-4444dddd5555", "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned", "location": "<azure-location>", "name": "msdocs-identity-example-user-assigned", "principalId": "cccccccc-dddd-eeee-3333-444444444444", "resourceGroup": "msdocs-identity-example", "systemData": null, "tags": {}, "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "type": "Microsoft.ManagedIdentity/userAssignedIdentities" }
Observação
Por exemplo, neste exemplo, o valor de
id
seria/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo.
Crie um arquivo Bicep para definir uma identidade gerenciada atribuída pelo usuário e nomeie o arquivo como user-assigned-managed-identity.bicep. Defina estas propriedades mínimas:
Valor name
Use um parâmetro opcional chamado identityName
e gere um valor padrão exclusivolocation
Defina-o para a localização do grupo de recursos metadata description = 'Create a user-assigned managed identity.' param identityName string = uniqueString(subscription().id, resourceGroup().id) resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { name: identityName location: resourceGroup().location } output id string = identity.id output name string = identity.name
Implante o modelo Bicep usando o
az deployment group create
. Especifique o nome do modelo Bicep e do grupo de recursos do Azure.az deployment group create \ --resource-group "<name-of-existing-resource-group>" \ --template-file "user-assigned-managed-identity.bicep"
Revise a saída da implantação. A saída contém o identificador exclusivo da identidade gerenciada na propriedade
properties.outputs.name.value
. Registre esse valor como ele deve ser usado ao criar um novo recurso do Azure posteriormente neste guia.{ "type": "String", "value": "msdocs-identity-example-user-assigned" }
Observação
Neste exemplo,
name.value
seriamsdocs-identity-example-user-assigned
. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo.
Insira Identidade gerenciada na barra de pesquisa global.
Em Serviços, selecione Identidades gerenciadas.
No painel Instâncias de contêiner, selecione Criar.
No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:
Valor Assinatura Selecione sua Assinatura do Azure. Grupo de Recursos Crie um novo grupo de recursos ou escolha um grupo de recursos existente Região Escolha uma região do Azure compatível com sua assinatura Nome Forneça um nome global exclusivo No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Aguarde a conclusão da implantação da identidade gerenciada.
Crie uma identidade gerenciada atribuída pelo usuário usando
New-AzUserAssignedIdentity
em seu grupo de recursos do Azure.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-new-managed-identity>" Location = "<azure-region>" } New-AzUserAssignedIdentity @parameters
Use
Get-AzUserAssignedIdentity
para obter uma lista de identidades gerenciadas atribuídas pelo usuário em seu grupo de recursos.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" } Get-AzUserAssignedIdentity @parameters | Format-List Name, Id
Revise a saída do comando. Registre o valor do campo
Id
à medida que esse identificador de recurso totalmente qualificado é usado para atribuir a identidade gerenciada atribuída pelo usuário ao recurso do Azure.Name : msdocs-identity-example-user-assigned Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
Observação
Por exemplo, neste exemplo, o valor de
Id
seria/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo.
Criar um serviço do Azure com uma identidade gerenciada atribuída pelo usuário
Atribua a identidade gerenciada atribuída pelo usuário criada anteriormente a um novo serviço de host do Azure. Esta seção cria um recurso de aplicativo Web dos Serviços de Aplicativos do Azure.
Crie um novo plano de serviço de aplicativo usando
az appservice plan create
.az appservice plan create \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-new-plan>"
Atribua a identidade gerenciada atribuída pelo usuário a um novo aplicativo Web com
az webapp create
. Use o campoid
registrado anteriormente neste guia como o valor do parâmetrossign-identity
.az webapp create \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-existing-web-app>" \ --plan "<name-of-existing-plan>" \ --assign-identity "<resource-id-recorded-earlier>"
Obtenha os detalhes de todas as identidades atribuídas a essa conta usando
az webapp show
e uma consulta JMESPath.az webapp show \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-existing-account>" \ --query "identity"
Revise a saída do comando. Ele deve incluir a identidade gerenciada atribuída pelo usuário.
{ "principalId": null, "tenantId": null, "type": "UserAssigned", "userAssignedIdentities": { "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": { "clientId": "11112222-bbbb-3333-cccc-4444dddd5555", "principalId": "cccccccc-dddd-eeee-3333-444444444444" } } }
Crie outro arquivo Bicep chamado app-service-web-app.bicep e defina um plano e um aplicativo Web do Serviço de Aplicativo do Azure. Defina estas propriedades para esses recursos:
Recurso Valor name
Identidade gerenciada existente Use um parâmetro chamado identityName
name
Plano de serviço de aplicativo Use um parâmetro chamado planName
location
Plano de serviço de aplicativo Defina-o para a localização do grupo de recursos name
Aplicativo Web Use um parâmetro chamado webAppName
location
Aplicativo Web Defina-o para a localização do grupo de recursos identity.type
UserAssigned
identity.userAssignedIdentities.{identity.id}
{}
properties.serverFarmId
plan.id
metadata description = 'Creates an Azure App Service plan and web app with a user-assigned managed identity.' @description('The name of the app service plan.') param planName string @description('The name of the web app.') param webAppName string @description('The name of the user-assigned managed identity.') param identityName string resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = { name: identityName } resource plan 'Microsoft.Web/serverfarms@2023-12-01' = { name: planName location: resourceGroup().location } resource webApp 'Microsoft.Web/sites@2023-12-01' = { name: webAppName location: resourceGroup().location identity: { type: 'UserAssigned' userAssignedIdentities: { '${identity.id}': {} } } properties: { serverFarmId: plan.id } } output userAssignedIdentity object = webApp.identity
Crie um arquivo de parâmetros Bicep chamado app-service-web-app.
bicepparam
. Neste arquivo de parâmetros, crie um nome exclusivo para seu aplicativo Web e planeje usando os parâmetrosplanName
ewebAppName
, respectivamente. Em seguida, forneça o nome da identidade gerenciada atribuída pelo usuário como o valor do parâmetroidentityName
.using './app-service-web-app.bicep' param planName = '<name-of-new-app-service-plan>' param webAppName = '<name-of-new-web-app>' param identityName = '<name-of-existing-managed-identity>'
Implante o modelo Bicep usando o
az deployment group create
. Especifique o nome do modelo Bicep, do arquivo de parâmetros e do grupo de recursos do Azure.az deployment group create \ --resource-group "<name-of-existing-resource-group>" \ --parameters "app-service-web-app.bicepparam" \ --template-file "app-service-web-app.bicep"
Revise a saída da implantação. A saída contém o objeto de identidade da instância de contêiner na propriedade
properties.outputs.userAssignedIdentity.value
.{ "type": "UserAssigned", "userAssignedIdentities": { "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": { "clientId": "11112222-bbbb-3333-cccc-4444dddd5555", "principalId": "cccccccc-dddd-eeee-3333-444444444444" } } }
Insira Aplicativo Web na barra de pesquisa global.
Em Serviços, selecione Serviços de Aplicativos.
No painel Serviços de Aplicativos, selecione Criar e, em seguida, Aplicativo Web.
No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:
Valor Assinatura Selecione sua Assinatura do Azure. Grupo de Recursos Crie um novo grupo de recursos ou escolha um grupo de recursos existente Nome Forneça um nome global exclusivo Plano Crie um novo plano ou selecione um plano existente No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Depois que a implantação for concluída, escolha Ir para o recurso para navegar até o novo recurso de Instâncias de Contêiner do Azure.
No painel da nova instância de contêiner, selecione Identidade na seção Configurações do menu de serviço.
No painel Identidade, selecione a opção Atribuído pelo usuário.
Selecione Adicionar para abrir uma caixa de diálogo para atribuir identidades gerenciadas atribuídas pelo usuário existentes. Na caixa de diálogo, escolha sua identidade gerenciada atribuída pelo usuário existente e selecione Adicionar.
Por fim, examine a lista de identidades gerenciadas atribuídas pelo usuário associadas ao seu aplicativo Web. Ela deve incluir o nome da identidade, o nome do grupo de recursos e o identificador de assinatura.
Use
New-AzWebApp
para criar um novo aplicativo Web do Serviço de Aplicativo do Azure.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-new-web-app>" Location = "<azure-region>" } New-AzWebApp @parameters
Corrija o aplicativo Web recém-criado para definir a propriedade
identity.type
comoUserAssigned
e adicionar sua identidade gerenciada atribuída pelo usuário existente à propriedadeidentity.userAssignedIdentities
. Para realizar essa tarefa, primeiro forneça o campoid
registrado anteriormente neste guia como o valor da variável de shellidentityId
. Em seguida, construa um objeto de payload e converta-o em JSON. Por fim, useInvoke-AzRestMethod
com o verbo HTTPPATCH
para atualizar o aplicativo Web existente.$identityId = "<resource-id-recorded-earlier>" $payload = @{ identity = @{ type = "UserAssigned" userAssignedIdentities = @{ "$identityId" = @{} } } } | ConvertTo-Json -Depth 3 $parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-existing-web-app>" ResourceProviderName = 'Microsoft.Web' ResourceType = 'sites' ApiVersion = '2023-12-01' Method = 'PATCH' Payload = $payload } Invoke-AzRestMethod @parameters
Obtenha os detalhes de todas as identidades atribuídas ao aplicativo Web usando
Get-AzWebApp
,Select-Object
eConvertTo-Json
selecionando somente a propriedadeIdentity
.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-existing-web-app>" } Get-AzWebApp @parameters | Select-Object Identity | ConvertTo-Json -Depth 3
Revise a saída do comando. Ele deve incluir os identificadores exclusivos para a identidade e o locatário.
{ "Identity": { "Type": "UserAssigned", "TenantId": null, "PrincipalId": null, "UserAssignedIdentities": { "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": { "PrincipalId": "cccccccc-dddd-eeee-3333-444444444444", "ClientId": "11112222-bbbb-3333-cccc-4444dddd5555" } } } }