Usar o Azure PowerShell para criar uma entidade de serviço com um certificado

  • Artigo

Quando você tiver um aplicativo ou script que precisa acessar recursos, poderá configurar uma identidade para o aplicativo e autenticá-lo com suas próprias credenciais. Essa identidade é conhecida como uma entidade de serviço. Essa abordagem permite:

  • Atribua permissões à identidade do aplicativo que sejam diferentes das suas próprias permissões. Normalmente, essas permissões são restritas a exatamente o que o aplicativo precisa fazer.
  • Use um certificado para a autenticação ao executar um script autônomo.

Importante

Em vez de criar uma entidade de serviço, considere o uso de identidades gerenciadas para recursos do Azure para a identidade do aplicativo. Se o código for executado em um serviço que dá suporte a identidades gerenciadas e acessa recursos que dão suporte à autenticação do Microsoft Entra, as identidades gerenciadas serão uma opção melhor. Para saber mais sobre identidades gerenciadas dos recursos do Azure, incluindo os serviços atualmente com suporte, consulte O que são identidades gerenciadas para recursos do Azure?.

Este artigo mostra como criar uma entidade de serviço que autentica com um certificado. Para configurar uma entidade de serviço com a senha, consulte Criar uma entidade de serviço do Azure com o Azure PowerShell.

Você deve ter a versão mais recente do PowerShell para esse artigo.

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Confira Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.

Permissões necessárias

Para concluir esse artigo, você deve ter permissões suficientes na sua assinatura do Microsoft Entra ID e do Azure. Especificamente, você deve ser capaz de criar um aplicativo no Microsoft Entra ID e atribuir a entidade de serviço a uma função.

A maneira mais fácil de verificar se a sua conta tem as permissões adequadas é por meio do portal. Consulte Verificar permissão necessária.

Atribuir o aplicativo a uma função

Para acessar recursos em sua assinatura, você deve atribuir o aplicativo a uma função. Decida qual função oferece as permissões corretas para o aplicativo. Para saber mais sobre as funções disponíveis, consulte Funções internas do Azure.

Você pode definir o escopo no nível da assinatura, do grupo de recursos ou do recurso. As permissão são herdadas para níveis inferiores do escopo. Por exemplo, adicionar um aplicativo à função Leitor de um grupo de recursos significa que ele pode ler o grupo de recursos e todos os recursos nele contidos. Para permitir que o aplicativo execute ações como reinicializar, iniciar e parar instâncias, selecione a função de Colaborador.

Criar a entidade de serviço com um certificado autoassinado

O exemplo a seguir aborda um cenário simples. Ele usa New-AzADServicePrincipal para criar uma entidade de serviço com um certificado autoassinado e New-AzRoleAssignment para atribuir a função de Leitor a ela. A atribuição de função está abrangida na sua assinatura do Azure selecionada no momento. Para selecionar uma assinatura diferente, use Set-AzContext.

Observação

No momento, não há suporte no PowerShell Core para o cmdlet New-SelfSignedCertificate e o módulo PKI.

$cert = New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" `
  -Subject "CN=exampleappScriptCert" `
  -KeySpec KeyExchange
$keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())

$sp = New-AzADServicePrincipal -DisplayName exampleapp `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore
Sleep 20
New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $sp.AppId

O exemplo fica suspenso por 20 segundos para dar tempo para a nova entidade de serviço propagar-se pelo Microsoft Entra ID. Se o seu script não esperar o tempo suficiente, você verá um erro informando: "A {ID} da entidade não existe no diretório {DIR-ID}". Para resolver esse erro, aguarde um momento e execute o comando New-AzRoleAssignment novamente.

Você pode definir o escopo da atribuição de função para um grupo de recursos específico usando o parâmetro ResourceGroupName. Você pode definir o escopo para um recurso específico também usando os parâmetros ResourceType e ResourceName.

Se você não tiver o Windows 10 ou o Windows Server 2016, baixe o cmdlet New-SelfSignedCertificateEx das soluções PKI. Extraia seu conteúdo e importe o cmdlet necessário.

# Only run if you could not use New-SelfSignedCertificate
Import-Module -Name c:\ExtractedModule\New-SelfSignedCertificateEx.ps1

No script, substitua as duas linhas a seguir para gerar o certificado.

New-SelfSignedCertificateEx -StoreLocation CurrentUser `
  -Subject "CN=exampleapp" `
  -KeySpec "Exchange" `
  -FriendlyName "exampleapp"
$cert = Get-ChildItem -path Cert:\CurrentUser\my | where {$PSitem.Subject -eq 'CN=exampleapp' }

Fornecer certificado por meio do script PowerShell automatizado

Sempre que você entrar como uma entidade de serviço, precisará fornecer a ID do locatário do diretório do aplicativo do AD. Um locatário é uma instância de Microsoft Entra ID.

$TenantId = (Get-AzSubscription -SubscriptionName "Contoso Default").TenantId
$ApplicationId = (Get-AzADApplication -DisplayNameStartWith exampleapp).AppId

$Thumbprint = (Get-ChildItem cert:\CurrentUser\My\ | Where-Object {$_.Subject -eq "CN=exampleappScriptCert" }).Thumbprint
Connect-AzAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

Criar a entidade de serviço com um certificado da Autoridade de Certificação

O exemplo a seguir usa um certificado emitido por uma Autoridade de Certificação para criar a entidade de serviço. A atribuição é abrangida pela assinatura do Azure especificada. Ela adiciona a entidade de serviço à função Leitor. Se ocorrer um erro durante a atribuição de função, ele tentará novamente a atribuição.

Param (
 [Parameter(Mandatory=$true)]
 [String] $ApplicationDisplayName,

 [Parameter(Mandatory=$true)]
 [String] $SubscriptionId,

 [Parameter(Mandatory=$true)]
 [String] $CertPath,

 [Parameter(Mandatory=$true)]
 [String] $CertPlainPassword
 )

 Connect-AzAccount
 Import-Module Az.Resources
 Set-AzContext -Subscription $SubscriptionId

 $CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force

 $PFXCert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList @($CertPath, $CertPassword)
 $KeyValue = [System.Convert]::ToBase64String($PFXCert.GetRawCertData())

 $ServicePrincipal = New-AzADServicePrincipal -DisplayName $ApplicationDisplayName
 New-AzADSpCredential -ObjectId $ServicePrincipal.Id -CertValue $KeyValue -StartDate $PFXCert.NotBefore -EndDate $PFXCert.NotAfter
 Get-AzADServicePrincipal -ObjectId $ServicePrincipal.Id 

 $NewRole = $null
 $Retries = 0;
 While ($NewRole -eq $null -and $Retries -le 6)
 {
    # Sleep here for a few seconds to allow the service principal application to become active (should only take a couple of seconds normally)
    Sleep 15
    New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $ServicePrincipal.AppId | Write-Verbose -ErrorAction SilentlyContinue
    $NewRole = Get-AzRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
    $Retries++;
 }

 $NewRole

Fornecer certificado por meio do script PowerShell automatizado

Sempre que você entrar como uma entidade de serviço, precisará fornecer a ID do locatário do diretório do aplicativo do AD. Um locatário é uma instância de Microsoft Entra ID.

Param (

 [Parameter(Mandatory=$true)]
 [String] $CertPath,

 [Parameter(Mandatory=$true)]
 [String] $CertPlainPassword,

 [Parameter(Mandatory=$true)]
 [String] $ApplicationId,

 [Parameter(Mandatory=$true)]
 [String] $TenantId
 )

 $CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force
 $PFXCert = New-Object `
  -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 `
  -ArgumentList @($CertPath, $CertPassword)
 $Thumbprint = $PFXCert.Thumbprint

 Connect-AzAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

A ID do aplicativo e a ID de locatário não diferenciam maiúsculas de minúsculas e, portanto, você pode inseri-las diretamente no script. Se precisar recuperar a ID de locatário, use:

(Get-AzSubscription -SubscriptionName "Contoso Default").TenantId

Se precisar recuperar a ID do aplicativo, use:

(Get-AzADApplication -DisplayNameStartWith {display-name}).AppId

Alterar credenciais

Para alterar as credenciais para um aplicativo do AD, por causa de uma violação de segurança ou término de credencial, use os cmdlets Remove-AzADAppCredential e New-AzADAppCredential.

Para remover todas as credenciais de um aplicativo, use:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Para adicionar um valor de certificado, crie um certificado autoassinado conforme mostrado neste artigo. Em seguida, use:

Get-AzADApplication -DisplayName exampleapp | New-AzADAppCredential `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore

Depurar

Você pode receber os seguintes erros ao criar uma entidade de serviço:

  • "Authentication_Unauthorized" ou "Nenhuma assinatura encontrada no contexto.": você verá esse erro quando sua conta não tiver as permissões necessárias no Microsoft Entra ID para registrar um aplicativo. Normalmente, você vê esse erro quando somente usuários administradores no seu Microsoft Entra ID podem registrar aplicativos e sua conta não é um administrador. Peça ao administrador para atribuí-lo a uma função de administrador ou para permitir que os usuários registrem aplicativos.

  • Sua conta "não tem autorização para executar a ação 'Microsoft.Authorization/roleAssignments/write' no escopo '/subscriptions/{guid}'". – Você verá esse erro quando sua conta não tiver permissões suficientes para atribuir uma função a uma identidade. Solicite ao administrador da assinatura para adicioná-lo à função Administrador de Acesso do Usuário.

Próximas etapas