Usare Azure PowerShell per creare un'entità servizio con un certificatoUse Azure PowerShell to create a service principal with a certificate

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.When you have an app or script that needs to access resources, you can set up an identity for the app and authenticate the app with its own credentials. Questa identità è nota come entità servizio.This identity is known as a service principal. Questo approccio consente di:This approach enables you to:

  • Assegnare all'identità dell'app autorizzazioni diverse rispetto a quelle dell'utente.Assign permissions to the app identity that are different than your own permissions. Tali autorizzazioni sono in genere limitate alle specifiche operazioni che devono essere eseguite dall'app.Typically, these permissions are restricted to exactly what the app needs to do.
  • Usare un certificato per l'autenticazione in caso di esecuzione di uno script automatico.Use a certificate for authentication when executing an unattended script.

Importante

Anziché creare un'entità servizio, considerare l'uso dell'identità del servizio gestito di Azure Active Directory per l'identità dell'applicazione.Instead of creating a service principal, consider using Azure AD Managed Service Identity for your application identity. MSI di Azure Active Directory è una funzionalità di anteprima pubblica di Azure Active Directory che semplifica la creazione di un'identità per il codice.Azure AD MSI is a public preview feature of Azure Active Directory that simplifies creating an identity for code. Se il codice viene eseguito in un servizio che supporta MSI di Azure Active Directory e accede alle risorse che supportano l'autenticazione di Azure Active Directory, MSI di Azure Active Directory è un'opzione migliore.If your code runs on a service that supports Azure AD MSI and accesses resources that support Azure Active Directory authentication, Azure AD MSI is a better option for you. Per altre informazioni su MSI di Azure Active Directory, inclusi i servizi che al momento lo supportano, vedere Identità del servizio gestito per le risorse di Azure.To learn more about Azure AD MSI, including which services currently support it, see Managed Service Identity for Azure resources.

Questo articolo illustra come creare un'entità servizio che esegue l'autenticazione con un certificato.This article shows you how to create a service principal that authenticates with a certificate. Per configurare un'entità servizio con password, vedere come creare un'entità servizio di Azure con Azure PowerShell.To set up a service principal with password, see Create an Azure service principal with Azure PowerShell.

Per questo articolo è necessaria la versione più recente di PowerShell.You must have the latest version of PowerShell for this article.

Autorizzazioni necessarieRequired permissions

Per completare questo articolo, è necessario avere autorizzazioni sufficienti sia nell'istanza di Azure Active Directory che nella sottoscrizione di Azure.To complete this article, you must have sufficient permissions in both your Azure Active Directory and Azure subscription. In particolare, è necessario poter creare un'app in Azure Active Directory e assegnare l'entità servizio a un ruolo.Specifically, you must be able to create an app in the Azure Active Directory, and assign the service principal to a role.

Il modo più semplice per verificare se l'account dispone delle autorizzazioni appropriate è tramite il portale.The easiest way to check whether your account has adequate permissions is through the portal. Vedere Controllare le autorizzazioni necessarie.See Check required permission.

Creare un'entità servizio con certificato autofirmatoCreate service principal with self-signed certificate

L'esempio seguente illustra uno scenario semplice.The following example covers a simple scenario. Viene usato New-AzureRmADServicePrincipal per creare un'entità servizio con un certificato autofirmato viene usato New-AzureRmRoleAssignment per assegnare il ruolo Collaboratore all'entità servizio.It uses New-AzureRmADServicePrincipal to create a service principal with a self-signed certificate, and uses New-AzureRmRoleAssignment to assign the Contributor role to the service principal. L'ambito di assegnazione del ruolo corrisponde alla sottoscrizione di Azure selezionata.The role assignment is scoped to your currently selected Azure subscription. Per selezionare un'altra sottoscrizione, usare Set-AzureRmContext.To select a different subscription, use Set-AzureRmContext.

$cert = New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" `
  -Subject "CN=exampleappScriptCert" `
  -KeySpec KeyExchange
$keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())

$sp = New-AzureRMADServicePrincipal -DisplayName exampleapp `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore
Sleep 20
New-AzureRmRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $sp.ApplicationId

L'esempio viene sospeso per 20 secondi per consentire la propagazione della nuova entità servizio in Azure Active Directory.The example sleeps for 20 seconds to allow some time for the new service principal to propagate throughout Azure Active Directory. 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}".If your script doesn't wait long enough, you'll see an error stating: "Principal {ID} does not exist in the directory {DIR-ID}." Per correggere l'errore, attendere qualche istante quindi eseguire di nuovo il comando New-AzureRmRoleAssignment.To resolve this error, wait a moment then run the New-AzureRmRoleAssignment command again.

È possibile definire l'ambito di assegnazione di ruolo a un gruppo di risorse specifico tramite il parametro ResourceGroupName.You can scope the role assignment to a specific resource group by using the ResourceGroupName parameter. È possibile definire l'ambito per una risorsa specifica usando anche i parametri ResourceType e ResourceName.You can scope to a specific resource by also using the ResourceType and ResourceName parameters.

Se non si dispone di Windows 10 o Windows Server 2016, è necessario scaricare il generatore di certificati autofirmati da Microsoft Script Center.If you do not have Windows 10 or Windows Server 2016, you need to download the Self-signed certificate generator from Microsoft Script Center. Estrarre i contenuti e importare il cmdlet necessario.Extract its contents and import the cmdlet you need.

# 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.In the script, substitute the following two lines to generate the certificate.

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 automatizzatoProvide certificate through automated PowerShell script

Ogni volta che si accede come un'entità servizio, è necessario fornire l'ID tenant della directory per l'app AD.Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. Un tenant è un'istanza di Azure Active Directory.A tenant is an instance of Azure Active Directory.

$TenantId = (Get-AzureRmSubscription -SubscriptionName "Contoso Default").TenantId
$ApplicationId = (Get-AzureRmADApplication -DisplayNameStartWith exampleapp).ApplicationId

 $Thumbprint = (Get-ChildItem cert:\CurrentUser\My\ | Where-Object {$_.Subject -match "CN=exampleappScriptCert" }).Thumbprint
 Connect-AzureRmAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

Creare un'entità servizio con certificato dell'autorità di certificazioneCreate service principal with certificate from Certificate Authority

L'esempio seguente usa un certificato emesso da un'autorità di certificazione per creare un'entità servizio.The following example uses a certificate issued from a Certificate Authority to create service principal. L'ambito dell'assegnazione corrisponde alla sottoscrizione di Azure specificata.The assignment is scoped to the specified Azure subscription. Viene aggiunta l'entità servizio al ruolo Collaboratore.It adds the service principal to the Contributor role. Se si verifica un errore durante l'assegnazione del ruolo, l'assegnazione viene ritentata.If an error occurs during the role assignment, it retries the assignment.

Param (
 [Parameter(Mandatory=$true)]
 [String] $ApplicationDisplayName,

 [Parameter(Mandatory=$true)]
 [String] $SubscriptionId,

 [Parameter(Mandatory=$true)]
 [String] $CertPath,

 [Parameter(Mandatory=$true)]
 [String] $CertPlainPassword
 )

 Connect-AzureRmAccount
 Import-Module AzureRM.Resources
 Set-AzureRmContext -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-AzureRMADServicePrincipal -DisplayName $ApplicationDisplayName
 New-AzureRmADSpCredential -ObjectId $ServicePrincipal.Id -CertValue $KeyValue -StartDate $PFXCert.NotBefore -EndDate $PFXCert.NotAfter
 Get-AzureRmADServicePrincipal -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-AzureRMRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $ServicePrincipal.ApplicationId | Write-Verbose -ErrorAction SilentlyContinue
    $NewRole = Get-AzureRMRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
    $Retries++;
 }

 $NewRole

Fornire il certificato tramite uno script di PowerShell automatizzatoProvide certificate through automated PowerShell script

Ogni volta che si accede come un'entità servizio, è necessario fornire l'ID tenant della directory per l'app AD.Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. Un tenant è un'istanza di Azure Active Directory.A tenant is an instance of Azure Active Directory.

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-AzureRmAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

Poiché l'ID applicazione e l'ID tenant non sono sensibili, è possibile incorporarli direttamente nello script.The application ID and tenant ID aren't sensitive, so you can embed them directly in your script. Se è necessario recuperare l'ID tenant, usare:If you need to retrieve the tenant ID, use:

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

Se è necessario recuperare l'ID applicazione, usare:If you need to retrieve the application ID, use:

(Get-AzureRmADApplication -DisplayNameStartWith {display-name}).ApplicationId

Modificare le credenzialiChange credentials

Per modificare le credenziali per un'app AD, a causa di una violazione della sicurezza o della scadenza delle credenziali, usare i cmdlet Remove-AzureRmADAppCredential e New-AzureRmADAppCredential.To change the credentials for an AD app, either because of a security compromise or a credential expiration, use the Remove-AzureRmADAppCredential and New-AzureRmADAppCredential cmdlets.

Per rimuovere tutte le credenziali per un'applicazione, usare:To remove all the credentials for an application, use:

Get-AzureRmADApplication -DisplayName exampleapp | Remove-AzureRmADAppCredential

Per aggiungere un valore del certificato, creare un certificato autofirmato come illustrato in questo articolo.To add a certificate value, create a self-signed certificate as shown in this article. Successivamente, usare:Then, use:

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

DebugDebug

Durante la creazione di un'entità servizio, è possibile riscontrare gli errori seguenti:You may get the following errors when creating a service principal:

  • "Authentication_Unauthorized" o "Nessuna sottoscrizione trovata nel contesto"."Authentication_Unauthorized" or "No subscription found in the context." - Questo errore viene visualizzato quando l'account non ha le autorizzazioni necessarie in Azure Active Directory per registrare un'app.- You see this error when your account does not have the required permissions on the Azure Active Directory to register an app. In genere, l'errore si verifica quando solo gli utenti amministratori di Azure Active Directory possono registrare le app e l'account in uso non è un account di amministratore. Chiedere all'amministratore di essere assegnati a un ruolo di amministratore oppure di consentire agli utenti di registrare le app.Typically, you see this error when only admin users in your Azure Active Directory can register apps, and your account is not an admin. Ask your administrator to either assign you to an administrator role, or to enable users to register apps.

  • 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à.Your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write' over scope '/subscriptions/{guid}'." - You see this error when your account does not have sufficient permissions to assign a role to an identity. Chiedere all'amministratore della sottoscrizione di essere aggiunti al ruolo Amministratore accessi utente.Ask your subscription administrator to add you to User Access Administrator role.

Passaggi successiviNext steps