Compartilhar via

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

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 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 um principal de serviço, considere o uso de identidades gerenciadas para recursos do Azure como a identidade do seu 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 para você como criar um principal 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, é necessário conseguir 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 sua conta tem permissões adequadas é pelo Centro de administração do Microsoft Entra.

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ões são herdadas para níveis inferiores de 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 entidade de serviço com certificado autoassinado

O exemplo a seguir aborda um cenário simples. Ele usa New-AzADEntidadede Serviço para criar uma entidade de serviço com um certificado autoassinado e usa New-AzRoleAssignment para atribuir a função Leitor à entidade de serviço. A atribuição de função está no escopo da 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 aguarda 20 segundos para permitir que a nova entidade de serviço se propague pelo Microsoft Entra ID. Se o seu script não esperar o tempo suficiente, você verá um erro informando: "A entidade {ID} não existe no diretório {DIR-ID}". Para resolver esse erro, aguarde um momento e execute novamente o comando New-AzRoleAssignment.

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, forneça a ID do locatário do diretório para seu aplicativo do AD. Um locatário é uma instância do 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 entidade de serviço com 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 está no escopo da assinatura do Azure especificada. 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, forneça a ID do locatário do diretório para seu aplicativo do AD. Um locatário é uma instância do 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 ID do locatário não são confidenciais, 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 de um aplicativo do AD, devido a uma violação de segurança ou expiração de credenciais, 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 obter 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 é uma conta de administrador. Peça ao administrador para atribuir a você uma função administrativa ou 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