Partilhar via

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

  • Artigo

Quando tem uma aplicação ou script que precisa de aceder a recursos, pode configurar uma identidade para a aplicação e autenticar a aplicação com as suas próprias credenciais. Esta identidade é conhecida como um principal de serviço. Esta abordagem permite-lhe:

  • Atribuir permissões para a identidade da aplicação, que são diferentes das suas própria permissões. Normalmente, estas permissões estão restritas a exatamente aquilo que a aplicação precisa de fazer.
  • Utilize um certificado para autenticação ao executar um script automático.

Importante

Em vez de criar uma entidade de serviço, considere usar identidades gerenciadas para recursos do Azure para sua identidade de aplicativo. Se o seu código é executado em um serviço que oferece suporte a identidades gerenciadas e acessa recursos que suportam a autenticação do Microsoft Entra, as identidades gerenciadas são uma opção melhor para você. Para saber mais sobre identidades gerenciadas para recursos do Azure, incluindo quais serviços atualmente oferecem suporte a isso, consulte O que são identidades gerenciadas para recursos do Azure?.

Este artigo mostra como criar um principal de serviço que faz a autenticação com um certificado. Para configurar um principal de serviço com palavra-passe, veja Criar um principal de serviço do Azure com o Azure PowerShell.

Para este artigo, tem de ter a versão mais recente do PowerShell.

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Permissões obrigatórias

Para concluir este artigo, você deve ter permissões suficientes em sua ID do Microsoft Entra e na assinatura 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 sua conta tem permissões adequadas é através do 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 certas 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, grupo de recursos ou recurso. As permissões são herdadas para níveis mais baixos de escopo. Por exemplo, adicionar um aplicativo à função Leitor para um grupo de recursos significa que ele pode ler o grupo de recursos e quaisquer recursos que ele contém. Para permitir que o aplicativo execute ações como reinicializar, iniciar e parar instâncias, selecione a função de Colaborador .

Criar um principal de serviço com um certificado autoassinado

O exemplo seguinte inclui um cenário simples. Ele usa New-AzADServicePrincipal para criar uma entidade de serviço com um certificado autoassinado e usa New-AzRoleAssignment para atribuir a função Reader à entidade de serviço. A atribuição da função está confinada à sua subscrição do Azure atualmente selecionada. Para selecionar uma assinatura diferente, use Set-AzContext.

Nota

O cmdlet New-SelfSignedCertificate e o módulo PKI não são suportados atualmente no PowerShell Core.

$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 suspende por 20 segundos para permitir algum tempo para que a nova entidade de serviço se propague por toda a ID do Microsoft Entra. Se o script não esperar o suficiente, você verá um erro informando: "Principal {ID} não existe no diretório {DIR-ID}." Para resolver esse erro, aguarde um momento e execute o comando New-AzRoleAssignment novamente.

Pode definir o âmbito de atribuição da função para um grupo de recursos específico, utilizando o parâmetro ResourceGroupName. Pode definir o âmbito para um recurso específico, utilizando também os parâmetros ResourceType e ResourceName.

Se você não tiver o Windows 10 ou o Windows Server 2016, baixe o cmdlet New-SelfSignedCertificateEx da PKI Solutions. Extraia o respetivo conteúdo e importe o cmdlet de que precisa.

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

No script, substitua as duas linhas seguintes 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 o certificado através do script do PowerShell automatizado

Sempre que iniciar sessão como entidade de serviço, forneça o ID de inquilino do diretório para a sua aplicação 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 um principal de serviço com um certificado da Autoridade de Certificação

O exemplo seguinte utiliza um certificado emitido por uma Autoridade de Certificação para criar o principal de serviço. A atribuição é confinada à subscrição do Azure especificada. Ele adiciona a entidade de serviço à função Leitor . Se ocorrer um erro durante a atribuição da função, repete 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 o certificado através do script do PowerShell automatizado

Sempre que iniciar sessão como entidade de serviço, forneça o ID de inquilino do diretório para a sua aplicação 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

O ID da aplicação e o ID de inquilino não são sensíveis, pelo que pode incorporá-los diretamente no seu script. Se precisar de obter o ID do inquilino, utilize:

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

Se precisar de obter o ID da aplicação, utilize:

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

Alterar credenciais

Para alterar as credenciais de um aplicativo AD, devido a um comprometimento de segurança ou à expiração de uma credencial, use os cmdlets Remove-AzADAppCredential e New-AzADAppCredential .

Para remover todas as credenciais para uma aplicação, utilize:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

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

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

Depurar

Pode obter os seguintes erros ao criar um principal de serviço:

  • "Authentication_Unauthorized" ou "Nenhuma assinatura encontrada no contexto". - Você vê esse erro quando sua conta não tem as permissões necessárias no ID do Microsoft Entra para registrar um aplicativo. Normalmente, você vê esse erro quando apenas usuários administradores em sua ID do Microsoft Entra podem registrar aplicativos e sua conta não é um administrador. Peça ao administrador para atribuir você 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' sobre o escopo '/subscriptions/{guid}'." - Você vê esse erro quando sua conta não tem permissões suficientes para atribuir uma função a uma identidade. Peça ao administrador da sua subscrição para adicioná-lo à função Administrador de Acesso dos Utilizadores.

Próximos passos