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

  • Artigo
  • 6 minutos para ler

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 um principal de serviço, considere utilizar identidades geridas para recursos do Azure para a identidade da sua aplicação. Se o código for executado num serviço que suporte identidades geridas e aceda a recursos que suportam a autenticação do Azure Active Directory (Azure AD), as identidades geridas são uma opção melhor para si. Para saber mais sobre identidades geridas para recursos do Azure, incluindo quais os serviços que atualmente o suportam, veja O que são identidades geridas 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, tem de ter permissões suficientes na Azure AD e na subscrição do Azure. Especificamente, tem de conseguir criar uma aplicação no Azure AD e atribuir o principal de serviço a uma função.

A forma mais fácil de verificar se a sua conta tem permissões adequadas é utilizar o portal. Veja Permissões obrigatórias.

Atribuir a aplicação a uma função

Para aceder aos recursos na sua subscrição, tem de atribuir a aplicação a uma função. Decida que função oferece as permissões certas para a aplicação. Para saber mais sobre as funções disponíveis, veja Funções incorporadas do Azure.

Pode definir o âmbito ao nível da subscrição, grupo de recursos ou recurso. As permissões são herdadas para níveis mais baixos de âmbito. Por exemplo, adicionar uma aplicação à função Leitor de um grupo de recursos significa que pode ler o grupo de recursos e quaisquer recursos que contenha. Para permitir que a aplicação execute ações como reiniciar, iniciar e parar instâncias, selecione a função Contribuidor .

Criar um principal de serviço com um certificado autoassinado

O exemplo seguinte inclui um cenário simples. Utiliza New-AzADServicePrincipal para criar um principal de serviço com um certificado autoassinado e utiliza New-AzRoleAssignment para atribuir a função leitor ao principal de serviço. A atribuição da função está confinada à sua subscrição do Azure atualmente selecionada. Para selecionar uma subscrição diferente, utilize Set-AzContext.

Nota

O cmdlet New-SelfSignedCertificate e o módulo PKI não são atualmente suportados 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 permanece suspenso durante 20 segundos para permitir algum tempo para a propagação do novo principal de serviço ao longo de Azure AD. Se o script não esperar o suficiente, verá um erro a indicar: "O principal {ID} não existe no diretório {DIR-ID}". Para resolver este erro, aguarde um momento e, em seguida, execute novamente o comando New-AzRoleAssignment .

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 não tiver Windows 10 ou Windows Server 2016, transfira o cmdlet New-SelfSignedCertificateEx a partir 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 principal de serviço, forneça o ID de inquilino do diretório para a sua aplicação do AD. Um inquilino é uma instância de Azure AD.

$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. Adiciona o principal 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 principal de serviço, forneça o ID de inquilino do diretório para a sua aplicação do AD. Um inquilino é uma instância de Azure AD.

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 uma aplicação do AD, devido a um compromisso de segurança ou à expiração de uma credencial, utilize 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 subscrição encontrada no contexto". – Verá este erro quando a sua conta não tem as permissões necessárias no Azure AD registar uma aplicação. Normalmente, vê este erro quando apenas os utilizadores administradores no Azure Active Directory podem registar aplicações e a sua conta não é um administrador. Peça ao administrador para o atribuir a uma função de administrador ou para permitir que os utilizadores registem aplicações.

  • A sua conta "não tem autorização para executar a ação "Microsoft.Authorization/roleAssignments/write" no âmbito "/subscriptions/{guid}"." - Verá este erro quando a 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.

Passos seguintes