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

  • Articolo

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.

Importante

Anziché creare un'entità servizio, considerare l'uso delle identità gestite per le risorse di Azure per l'identità dell'applicazione. Se il codice viene eseguito in un servizio che supporta le identità gestite e accede alle risorse che supportano l'autenticazione di Microsoft Entra, le identità gestite sono un'opzione migliore. Per altre informazioni sulle identità gestite per le risorse di Azure, inclusi i servizi attualmente supportati, vedere Informazioni sulle identità gestite per le risorse di Azure.

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.

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Autorizzazioni necessarie

Per completare questo articolo, è necessario disporre di autorizzazioni sufficienti sia nell'ID Microsoft Entra che nella sottoscrizione di Azure. In particolare, è necessario essere in grado di 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 è tramite il portale. Vedere Controllare le autorizzazioni necessarie.

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. Ad esempio, l'aggiunta di un'applicazione al ruolo Lettore per un gruppo di risorse significa che può leggere il gruppo di risorse e tutte le risorse in esso contenute. Per consentire all'applicazione di eseguire azioni come il riavvio, avviare e arrestare le istanze, selezionare il ruolo Collaboratore .

Creare un'entità servizio con certificato autofirmato

L'esempio seguente illustra uno scenario semplice. Usa New-AzADServicePrincipal per creare un'entità servizio con un certificato autofirmato e usa 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.

Nota

Il cmdlet New-SelfSignedCertificate e il modulo PKI non sono attualmente supportati in 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

L'esempio rimane in sospensione per 20 secondi per consentire la propagazione della nuova entità servizio in Microsoft Entra ID. Se lo script non attende abbastanza a lungo, verrà visualizzato un errore che indica che "Principal {ID} non esiste nella directory {DIR-ID}". Per risolvere questo errore, attendere un momento e 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 non si dispone di Windows 10 o Windows Server 2016, scaricare il cmdlet New-SelfSignedCertificateEx da PKI Solutions. 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 entità servizio, specificare l'ID tenant della directory per l'app AD. Un tenant è un'istanza dell'ID Microsoft Entra.

$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 entità servizio, specificare l'ID tenant della directory per l'app AD. Un tenant è un'istanza dell'ID Microsoft Entra.

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 per l'ID Microsoft Entra per registrare un'app. In genere, questo errore viene visualizzato quando solo gli utenti amministratori nell'ID Microsoft Entra possono registrare le app e l'account non è un amministratore. Chiedere all'amministratore di assegnare un ruolo di amministratore o 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