Usare Azure PowerShell per creare un'entità servizio con un certificato

Quando si ha un'app o uno script che deve accedere alle risorse, è possibile configurare un'identità per l'app ed eseguirne l'autenticazione con credenziali specifiche. Questa identità è nota come entità servizio. Questo approccio consente di:

• Assegnare all'identità dell'app autorizzazioni diverse rispetto a quelle dell'utente. Tali autorizzazioni sono in genere limitate alle specifiche operazioni che devono essere eseguite dall'app.
• Usare un certificato per l'autenticazione in caso di esecuzione di uno script automatico.

Questo articolo illustra come creare un'entità servizio che esegue l'autenticazione con un certificato. Per configurare un'entità servizio con password, vedere come creare un'entità servizio di Azure con Azure PowerShell.

Per questo articolo è necessaria la versione più recente di PowerShell.

Autorizzazioni necessarie

Per completare questo articolo, è necessario avere autorizzazioni sufficienti sia in Microsoft Entra ID che nella sottoscrizione di Azure. In particolare, è necessario poter creare un'app in Microsoft Entra ID e assegnare l'entità servizio a un ruolo.

Il modo più semplice per verificare se l'account dispone delle autorizzazioni appropriate è l’interfaccia di amministrazione di Microsoft Entra.

Assegnare l'applicazione a un ruolo

Per accedere alle risorse della propria sottoscrizione è necessario assegnare l'applicazione a un ruolo. Decidere quale ruolo offre le autorizzazioni appropriate per l'applicazione. Per informazioni sui ruoli disponibili, vedere Ruoli predefiniti di Azure.

È possibile impostare l'ambito al livello della sottoscrizione, del gruppo di risorse o della risorsa. Le autorizzazioni vengono ereditate a livelli inferiori dell'ambito. Se ad esempio si aggiunge un'applicazione al ruolo Lettore per un gruppo di risorse, l'applicazione può leggere il gruppo di risorse e le risorse in esso contenute. Per consentire all'applicazione di eseguire azioni quali istanze di riavvio, avvio e arresto, selezionare il ruolo Collaboratore.

Creare un'entità servizio con certificato autofirmato

L'esempio seguente illustra uno scenario semplice. Viene usato New-AzAD​Service​Principal per creare un'entità servizio con un certificato autofirmato viene usato New-AzRoleAssignment per assegnare il ruolo Lettore all'entità servizio. L'ambito di assegnazione del ruolo corrisponde alla sottoscrizione di Azure selezionata. Per selezionare un'altra sottoscrizione, usare Set-AzContext.

$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

L'esempio viene sospeso per 20 secondi per consentire la propagazione della nuova entità servizio in Microsoft Entra ID. Se la durata dell'attesa dello script non è sufficiente, verrà visualizzato un errore simile al seguente: "L'entità di sicurezza {ID} non esiste nella directory {DIR-ID}". Per correggere l'errore, attendere qualche istante quindi eseguire di nuovo il comando New-AzRoleAssignment.

È possibile definire l'ambito di assegnazione di ruolo a un gruppo di risorse specifico tramite il parametro ResourceGroupName. È possibile definire l'ambito per una risorsa specifica usando anche i parametri ResourceType e ResourceName.

Se si non si dispone di Windows 10 o Windows Server 2016, scaricare il cmdlet New-SelfSignedCertificateEx da soluzioni PKI. Estrarre i contenuti e importare il cmdlet necessario.

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

Nello script sostituire le due righe seguenti per generare il certificato.

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

Fornire il certificato tramite uno script di PowerShell automatizzato

Ogni volta che si accede come un'entità servizio, fornire l'ID tenant della directory per l'app AD. Un tenant è un'istanza di 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

Creare un'entità servizio con certificato dell'autorità di certificazione

L'esempio seguente usa un certificato emesso da un'autorità di certificazione per creare un'entità servizio. L'ambito dell'assegnazione corrisponde alla sottoscrizione di Azure specificata. Aggiunge l'entità servizio al ruolo Lettore. Se si verifica un errore durante l'assegnazione del ruolo, l'assegnazione viene ritentata.

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

Fornire il certificato tramite uno script di PowerShell automatizzato

Ogni volta che si accede come un'entità servizio, fornire l'ID tenant della directory per l'app AD. Un tenant è un'istanza di 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

Poiché l'ID applicazione e l'ID tenant non sono sensibili, è possibile incorporarli direttamente nello script. Se è necessario recuperare l'ID tenant, usare:

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

Se è necessario recuperare l'ID applicazione, usare:

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

Modificare le credenziali

Per modificare le credenziali per un'app AD, a causa di una violazione della sicurezza o della scadenza delle credenziali, usare i cmdlet Remove-AzADAppCredential e New-AzADAppCredential.

Per rimuovere tutte le credenziali per un'applicazione, usare:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Per aggiungere un valore del certificato, creare un certificato autofirmato come illustrato in questo articolo. Successivamente, usare:

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

Debug

Durante la creazione di un'entità servizio, è possibile riscontrare gli errori seguenti:

• "Authentication_Unauthorized" o "Nessuna sottoscrizione trovata nel contesto". : questo errore viene visualizzato quando l'account non dispone delle autorizzazioni necessarie su Microsoft Entra ID per registrare un'app. L'errore si verifica in genere quando solo gli utenti amministratori di Microsoft Entra ID possono registrare le app e l'account in uso non è un account amministratore. Chiedere all'amministratore di essere assegnati a un ruolo di amministratore oppure di consentire agli utenti di registrare le app.

• L'account "non è autorizzato a eseguire l'azione 'Microsoft.Authorization/roleAssignments/write' nell'ambito '/subscriptions/{guid}'." - Questo errore viene visualizzato quando l'account non dispone di autorizzazioni sufficienti per assegnare un ruolo a un'identità. Chiedere all'amministratore della sottoscrizione di essere aggiunti al ruolo Amministratore accessi utente.

Passaggi successivi

• Per configurare un'entità servizio con password, vedere come creare un'entità servizio di Azure con Azure PowerShell o Creare un’entità servizio Azure con l’interfaccia della riga di comando di Azure.
• Per una spiegazione più dettagliata delle applicazioni e delle entità servizio, vedere Oggetti applicazione e oggetti entità servizio.
• Per altre informazioni sull'autenticazione di Microsoft Entra ID, vedere Scenari di autenticazione per Microsoft Entra ID.
• Per informazioni sull'uso delle registrazioni delle app tramite Microsoft Graph, vedere le informazioni di riferimento API delle Applicazioni.