Como usar uma identidade gerenciada atribuída pelo usuário para uma conta da Automação do Azure

Este artigo mostra como adicionar uma identidade gerenciada atribuída pelo usuário para uma conta da Automação do Azure e como usá-la para acessar outros recursos. Para obter mais informações sobre como as identidades gerenciadas funcionam com a Automação do Azure, confira Identidades gerenciadas.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

• Uma conta de Automação do Azure. Veja as instruções em Criar uma conta de Automação do Azure.

• O identidade gerenciada atribuída pelo usuário e os recursos do Azure de destino que seu runbook gerencia usando essa identidade podem estar em assinaturas diferentes do Azure.

• A versão mais recente dos módulos da Conta do Azure. No momento, é 2.2.8. (Confira Az.Accounts para obter detalhes sobre esta versão.)

• Um recurso do Azure que você deseja acessar no runbook de automação. Esse recurso precisa ter uma função definida para a identidade gerenciada atribuída pelo usuário, o que ajuda o runbook de Automação a autenticar o acesso ao recurso. Para adicionar funções, você precisa ser um proprietário para o recurso no locatário do Microsoft Entra correspondente.

• Para atribuir uma função do Azure, você precisa ter permissões Microsoft.Authorization/roleAssignments/write, como Administrador de Acesso do Usuário ou Proprietário.

Adicionar uma identidade gerenciada atribuída pelo usuário a uma conta da Automação do Azure

Adicione uma identidade gerenciada atribuída pelo usuário a uma conta da Automação do Azure usando o portal do Azure, o PowerShell, a API REST do Azure ou o modelo do ARM. Para obter os exemplos que envolvem o PowerShell, primeiro, entre no Azure de modo interativo usando o cmdlet Connect-AzAccount e siga as instruções.

# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}

# If you have multiple subscriptions, set the one to use
# Select-AzSubscription -SubscriptionId "<SUBSCRIPTIONID>"

Em seguida, inicialize um conjunto de variáveis que serão usadas em todos os exemplos. Examine os valores abaixo e execute

$subscriptionID = "subscriptionID"
$resourceGroup = "resourceGroupName"
$automationAccount = "automationAccountName"
$userAssignedOne = "userAssignedIdentityOne"
$userAssignedTwo = "userAssignedIdentityTwo"

Adicionar pelo portal do Azure

Execute as etapas a seguir:

1. Entre no portal do Azure.

2. No portal do Azure, abra sua Conta de Automação.

3. Em Configurações da Conta, selecione Identidade.

4. Selecione a guia Atribuído pelo usuário e selecione Adicionar.

5. Escolha sua identidade gerenciada atribuída pelo usuário existente e selecione Adicionar. Em seguida, você será direcionado à guia Atribuído pelo usuário.

   

Adicionar pelo PowerShell

Use o cmdlet Set-AzAutomationAccount do PowerShell para adicionar as identidades gerenciadas atribuídas pelo usuário. Primeiro, você precisa considerar se há uma identidade gerenciada atribuída pelo sistema existente. O exemplo abaixo adiciona duas identidades gerenciadas atribuídas pelo usuário existentes a uma conta de Automação existente e desabilitará uma identidade gerenciada atribuída pelo sistema se houver uma.

$output = Set-AzAutomationAccount `
    -ResourceGroupName $resourceGroup `
    -Name $automationAccount `
    -AssignUserIdentity "/subscriptions/$subscriptionID/resourcegroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedOne", `
        "/subscriptions/$subscriptionID/resourcegroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedTwo"

$output

Para manter uma identidade gerenciada atribuída pelo sistema existente, use o seguinte:

$output = Set-AzAutomationAccount `
    -ResourceGroupName $resourceGroup `
    -Name $automationAccount `
    -AssignUserIdentity "/subscriptions/$subscriptionID/resourcegroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedOne", `
        "/subscriptions/$subscriptionID/resourcegroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedTwo" `
    -AssignSystemIdentity

$output

O resultado deve ser semelhante ao seguinte:

Para obter uma saída adicional, execute $output.identity | ConvertTo-Json.

Adicionar por meio de uma API REST

A sintaxe e as etapas de exemplo são fornecidas abaixo.

Sintaxe

A sintaxe do corpo de exemplo abaixo habilita uma identidade gerenciada atribuída pelo sistema se ela ainda não está habilitada e atribui duas identidades gerenciadas atribuídas pelo usuário existentes à conta de Automação existente.

PATCH

{
  "identity": {
    "type": "SystemAssigned, UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0/resourceGroups/resource-group-name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/firstIdentity": {},
      "/subscriptions/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0/resourceGroups/resource-group-name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/secondIdentity": {}
    }
  }
}

A sintaxe da API é a seguinte:

https://management.azure.com/subscriptions/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0/resourceGroups/resource-group-name/providers/Microsoft.Automation/automationAccounts/automation-account-name?api-version=2020-01-13-preview 

Exemplo

Execute as etapas a seguir.

1. Examine a sintaxe do corpo acima em um arquivo chamado body_ua.json. Salve o arquivo no seu computador local ou em uma conta de armazenamento do Azure.

2. Examine o valor da variável abaixo e execute-a.

   $file = "path\body_ua.json"
   

3. Este exemplo usa o cmdlet Invoke-RestMethod do PowerShell para enviar a solicitação PATCH à conta de Automação.

   # build URI
   $URI = "https://management.azure.com/subscriptions/$subscriptionID/resourceGroups/$resourceGroup/providers/Microsoft.Automation/automationAccounts/$automationAccount`?api-version=2020-01-13-preview"
   
   # build body
   $body = Get-Content $file
   
   # obtain access token
   $azContext = Get-AzContext
   $azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
   $profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
   $token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
   $authHeader = @{
       'Content-Type'='application/json'
       'Authorization'='Bearer ' + $token.AccessToken
   }
   
   # Invoke the REST API
   $response = Invoke-RestMethod -Uri $URI -Method PATCH -Headers $authHeader -Body $body
   
   # Review output
   $response.identity | ConvertTo-Json
   

   O resultado deve ser semelhante ao seguinte:

   {
   "type": "SystemAssigned, UserAssigned",
   "principalId": "ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0",
   "tenantId": "ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0",
   "userAssignedIdentities":  {
       "/subscriptions/ContosoID/resourcegroups/ContosoLab/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ContosoUAMI1":  {
               "PrincipalId":  "ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0",
               "ClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
                   },
       "/subscriptions/ContosoID/resourcegroups/ContosoLab/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ContosoUAMI2":  {
               "PrincipalId":  "ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0",
               "ClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
                   }
       }
   }
   

Adicionar por meio de um modelo do ARM

A sintaxe e as etapas de exemplo são fornecidas abaixo.

Sintaxe do modelo

A sintaxe do modelo de exemplo abaixo habilita uma identidade gerenciada atribuída pelo sistema se ela ainda não está habilitada e atribui duas identidades gerenciadas atribuídas pelo usuário existentes à conta de Automação existente.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "automationAccountName": {
     "defaultValue": "YourAutomationAccount",
      "type": "String",
      "metadata": {
        "description": "Automation account name"
      }
    },
    "userAssignedOne": {
     "defaultValue": "userAssignedOne",
      "type": "String",
      "metadata": {
        "description": "User-assigned managed identity"
      }
	  },
    "userAssignedTwo": {
     "defaultValue": "userAssignedTwo",
      "type": "String",
      "metadata": {
        "description": "User-assigned managed identity"
      }
	  }
   },
  "resources": [
    {
      "type": "Microsoft.Automation/automationAccounts",
      "apiVersion": "2020-01-13-preview",
      "name": "[parameters('automationAccountName')]",
      "location": "[resourceGroup().location]",
      "identity": {
        "type": "SystemAssigned, UserAssigned",
        "userAssignedIdentities": {
          "[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities/',parameters('userAssignedOne'))]": {},
          "[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities/',parameters('userAssignedTwo'))]": {}
        }
      },
      "properties": {
        "sku": {
          "name": "Basic"
        },
        "encryption": {
          "keySource": "Microsoft.Automation",
          "identity": {}
        }
      }
    }
  ]
}

Exemplo

Execute as etapas a seguir.

1. Copie e cole o modelo em um arquivo chamado template_ua.json. Salve o arquivo no seu computador local ou em uma conta de armazenamento do Azure.

2. Examine o valor da variável abaixo e execute-a.

   $templateFile = "path\template_ua.json"
   

3. Use o cmdlet New-AzResourceGroupDeployment do PowerShell para implantar o modelo.

   New-AzResourceGroupDeployment `
       -Name "UserAssignedDeployment" `
       -ResourceGroupName $resourceGroup `
       -TemplateFile $templateFile `
       -automationAccountName $automationAccount `
       -userAssignedOne $userAssignedOne `
       -userAssignedTwo $userAssignedTwo
   

   O comando não produzirá uma saída; no entanto, você poderá usar o código abaixo para verificar isso:

   (Get-AzAutomationAccount `
   -ResourceGroupName $resourceGroup `
   -Name $automationAccount).Identity | ConvertTo-Json
   

   A saída será semelhante à saída mostrada para o exemplo da API REST, acima.

Atribuir uma função a uma identidade gerenciada atribuída pelo usuário

Uma conta de Automação pode usar a respectiva identidade gerenciada atribuída pelo usuário para obter tokens a fim de acessar outros recursos protegidos pelo Microsoft Entra ID, como o Cofre de Chaves do Azure Esses tokens não representam nenhum usuário específico do aplicativo. Em vez disso, eles representam o aplicativo que está acessando o recurso. Nesse caso, por exemplo, o token representa uma conta de automação.

Para usar a identidade gerenciada atribuída pelo usuário para autenticação, configure o acesso para essa identidade no recurso do Azure em que pretende usar a identidade. Para concluir essa tarefa, atribua a função apropriada a essa identidade no recurso do Azure de destino.

Siga a entidade de segurança de privilégios mínimos e atribua cuidadosamente as permissões necessárias apenas para executar o runbook. Por exemplo, se a conta de Automação for necessária apenas para iniciar ou parar uma VM do Azure, as permissões atribuídas à conta Executar como ou à identidade gerenciada precisarão ser apenas para iniciar ou parar a VM. Da mesma forma, se um runbook estiver lendo do armazenamento de blob, atribua permissões somente leitura.

Este exemplo usa o Azure PowerShell para mostrar como atribuir a função Colaborador na assinatura ao recurso de destino do Azure. A função Colaborador é usada como exemplo e pode ou não ser necessária no seu caso. Como alternativa, você também pode atribuir a função ao recurso de destino do Azure no portal do Azure.

New-AzRoleAssignment `
    -ObjectId <automation-Identity-object-id> `
    -Scope "/subscriptions/<subscription-id>" `
    -RoleDefinitionName "Contributor"

Verificar a atribuição de função para uma identidade gerenciada pelo usuário

Para verificar uma função para uma identidade gerenciada atribuída pelo usuário da conta de Automação, siga estas etapas:

1. Entre no portal do Azure.

2. Vá para sua conta de Automação.

3. Em Configurações da Conta, selecione Identidade, Atribuída pelo usuário.

4. Clique em Nome da identidade atribuída pelo usuário.

   

   Se as funções já estiverem atribuídas à identidade gerenciada atribuída pelo usuário selecionada, você verá uma lista de atribuições de função. Essa lista inclui todas as atribuições de função que você tem permissão para ler.

   

5. Para alterar a assinatura, clique na lista suspensa Assinatura e selecione a assinatura apropriada.

6. Clique em Adicionar uma atribuição de função (versão prévia)

7. Na lista suspensa, entre as seguintes opções, selecione o conjunto de recursos ao qual a atribuição de função se aplica: Assinatura, Grupo de recursos, Função e Escopo.
   Se você não tiver a atribuição de função, poderá exibir as permissões de gravação para o escopo selecionado como uma mensagem embutida.

8. Na lista suspensa Função, selecione uma função, por exemplo, Colaborador da Máquina Virtual.

9. Clique em Save (Salvar).

   

Após alguns minutos, a identidade gerenciada é atribuída à função no escopo selecionado.

Autenticar o acesso com a identidade gerenciada atribuída pelo usuário

Depois de habilitar a identidade gerenciada atribuída pelo usuário para a conta de Automação e permitir acesso de identidade ao recurso de destino, você poderá especificar essa identidade em runbooks nos recursos que dão suporte à identidade gerenciada. Para obter suporte de identidade, use o cmdlet Connect-AzAccount do Az.

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with user-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity -AccountId <user-assigned-identity-ClientId>).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

Gerar um token de acesso sem usar os cmdlets do Azure

Para pontos de extremidade HTTP, verifique o seguinte.

• O cabeçalho de metadados precisa estar presente e ser definido como "true".
• Um recurso deve ser passado junto com a solicitação, como parâmetro de consulta para uma solicitação GET e como dados de formulário para uma solicitação POST.
• Defina o valor da variável de ambiente IDENTITY_HEADER como X-IDENTITY-HEADER.
• O tipo de conteúdo para a solicitação POST precisa ser application/x-www-form-urlencoded.

Obter um token de acesso para a identidade gerenciada atribuída pelo usuário usando HTTP Get

$resource= "?resource=https://management.azure.com/"
$client_id="&client_id=<ClientId of USI>"
$url = $env:IDENTITY_ENDPOINT + $resource + $client_id 
$Headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"  
$Headers.Add("Metadata", "True")
$headers.Add("X-IDENTITY-HEADER", $env:IDENTITY_HEADER) 
$accessToken = Invoke-RestMethod -Uri $url -Method 'GET' -Headers $Headers
Write-Output $accessToken.access_token 

Obter um token de acesso para a identidade gerenciada atribuída pelo usuário usando HTTP Post

$url = $env:IDENTITY_ENDPOINT
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Metadata", "True")
$headers.Add("X-IDENTITY-HEADER", $env:IDENTITY_HEADER) 
$body = @{'resource'='https://management.azure.com/' 
'client_id'='<ClientId of USI>'}
$accessToken = Invoke-RestMethod $url -Method 'POST' -Headers $headers -ContentType 'application/x-www-form-urlencoded' -Body $body
Write-Output $accessToken.access_token 

Como usar a identidade gerenciada atribuída pelo usuário no Azure PowerShell

Write-Output "Connecting to azure via  Connect-AzAccount -Identity -AccountId <ClientId of USI>"  
Connect-AzAccount -Identity -AccountId <ClientId of USI> 
Write-Output "Successfully connected with Automation account's Managed Identity"  
Write-Output "Trying to fetch value from key vault using User Assigned Managed identity. Make sure you have given correct access to Managed Identity"  
$secret = Get-AzKeyVaultSecret -VaultName '<KVname>' -Name '<KeyName>'  
$ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret.SecretValue)  
try {  
  $secretValueText = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr)  
    Write-Output $secretValueText  
} finally {  
    [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr)  
} 

Como usar a identidade gerenciada atribuída pelo usuário em um runbook do Python

#!/usr/bin/env python3  
import os  
import requests   

resource = "?resource=https://management.azure.com/" 
client_id = "&client_id=<ClientId of USI>" 
endPoint = os.getenv('IDENTITY_ENDPOINT')+ resource +client_id 
identityHeader = os.getenv('IDENTITY_HEADER') 
payload={}  
headers = {  
  'X-IDENTITY-HEADER': identityHeader,
  'Metadata': 'True' 
}  
response = requests.request("GET", endPoint, headers=headers, data=payload)  
print(response.text) 

Próximas etapas

• Se os runbooks não estiverem sendo concluídos com êxito, consulte Solucionar problemas de identidade gerenciada da Automação do Azure.

• Se você precisar desabilitar uma identidade gerenciada, confira Desabilitar a identidade gerenciada da conta de Automação do Azure.

• Para obter uma visão geral de segurança da conta de automação do Azure, confira Visão geral de autenticação da conta de automação.