Creare un'entità servizio di Azure con Azure PowerShellCreate an Azure service principal with Azure PowerShell

Gli strumenti automatici che usano i servizi di Azure devono sempre avere autorizzazioni limitate.Automated tools that use Azure services should always have restricted permissions. Invece di consentire alle applicazioni l'accesso come utenti con privilegi completi, Azure offre le identità servizio.Instead of having applications sign in as a fully privileged user, Azure offers service principals.

Un'entità servizio di Azure è un'identità creata per l'uso con applicazioni, servizi in hosting e strumenti automatici per l'accesso alle risorse di Azure.An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Questo accesso è limitato dai ruoli assegnati all'entità servizio e consente quindi di definire quali risorse siano accessibili e a quale livello.This access is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level. Per motivi di sicurezza è sempre consigliabile usare le identità servizio per gli strumenti automatici, invece di consentire loro di accedere con un'identità utente.For security reasons, it's always recommended to use service principals with automated tools rather than allowing them to log in with a user identity.

Questo articolo illustra i passaggi per la creazione, l'acquisizione di informazioni correlate e il ripristino di un'entità servizio con Azure PowerShell.This article shows you the steps for creating, getting information about, and resetting a service principal with Azure PowerShell.

Creare un'entità servizioCreate a service principal

Creare un'entità servizio con il cmdlet New-AzADServicePrincipal.Create a service principal with the New-AzADServicePrincipal cmdlet. Quando si crea un'entità servizio, si sceglie il tipo di autenticazione per l'accesso che verrà usata dall'entità.When creating a service principal, you choose the type of sign-in authentication it uses.

Nota

Se l'account in uso non è autorizzato a creare un'entità servizio, New-AzADServicePrincipal restituirà un messaggio di errore contenente "I privilegi non sono sufficienti per completare l'operazione".If your account doesn't have permission to create a service principal, New-AzADServicePrincipal will return an error message containing "Insufficient privileges to complete the operation." Per creare un'entità servizio, contattare l'amministratore di Azure Active Directory.Contact your Azure Active Directory admin to create a service principal.

Sono disponibili due tipi di autenticazione per le entità servizio: autenticazione basata su password e autenticazione basata su certificato.There are two types of authentication available for service principals: Password-based authentication, and certificate-based authentication.

Autenticazione basata su passwordPassword-based authentication

Senza altri parametri di autenticazione, viene usata l'autenticazione basata su password e viene creata automaticamente una password casuale.Without any other authentication parameters, password-based authentication is used and a random password created for you. Se si intende implementare l'autenticazione basata su password, si consiglia questo metodo.If you want password-based authentication, this method is recommended.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

L'oggetto restituito contiene il membro Secret, ovvero un oggetto SecureString contenente la password generata.The returned object contains the Secret member, which is a SecureString containing the generated password. Assicurarsi di conservare questo valore in un posto sicuro per eseguire l'autenticazione con l'entità servizio.Make sure that you store this value somewhere secure to authenticate with the service principal. Il valore non verrà visualizzato nell'output della console.Its value won't be displayed in the console output. Se si perde la password, reimpostare le credenziali dell'entità servizio.If you lose the password, reset the service principal credentials.

Il codice seguente consentirà di esportare il segreto:The following code will allow you to export the secret:

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
$UnsecureSecret = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

Per le password definite dall'utente, l'argomento -PasswordCredential accetta oggetti Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential.For user-supplied passwords, the -PasswordCredential argument takes Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential objects. Questi oggetti devono avere valori validi di StartDate e EndDate e accettano Password in testo non crittografato.These objects must have a valid StartDate and EndDate, and take a plaintext Password. Quando si crea una password, assicurarsi di seguire le regole e limitazioni per le password di Azure Active Directory.When creating a password, make sure you follow the Azure Active Directory password rules and restrictions. Non usare password vulnerabili o già usate in precedenza.Don't use a weak password or reuse a password.

Import-Module Az.Resources # Imports the PSADPasswordCredential object
$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{ StartDate=Get-Date; EndDate=Get-Date -Year 2024; Password=<Choose a strong password>}
$sp = New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials

L'oggetto restituito da New-AzADServicePrincipal contiene i membri Id e DisplayName, che possono essere entrambi usati per l'accesso con l'entità servizio.The object returned from New-AzADServicePrincipal contains the Id and DisplayName members, either of which can be used for sign in with the service principal.

Importante

L'accesso con un'entità servizio richiede l'ID del tenant in cui è stata creata.Signing in with a service principal requires the tenant ID which the service principal was created under. Per ottenere il tenant attivo quando è stata creata l'entità servizio, eseguire il comando seguente immediatamente dopo averla creata:To get the active tenant when the service principal was created, run the following command immediately after service principal creation:

(Get-AzContext).Tenant.Id

Autenticazione basata su certificatiCertificate-based authentication

Le entità servizio che usano l'autenticazione basata su certificato vengono create con il parametro -CertValue.Service principals using certificate-based authentication are created with the -CertValue parameter. Questo parametro accetta una stringa ASCII con codifica Base64 del certificato pubblico,This parameter takes a base64-encoded ASCII string of the public certificate. rappresentato da un file PEM oppure da un file CRT o CER con codifica di testo.This is represented by a PEM file, or a text-encoded CRT or CER. Le codifiche binarie del certificato pubblico non sono supportate.Binary encodings of the public certificate aren't supported. Queste istruzioni presuppongono che sia già disponibile un certificato.These instructions assume that you already have a certificate available.

$cert = <public certificate as base64-encoded string>
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert

È anche possibile usare il parametro -KeyCredential, che accetta oggetti PSADKeyCredential.You can also use the -KeyCredential parameter, which takes PSADKeyCredential objects. Questi oggetti devono avere valori validi di StartDate e EndDate. Inoltre, il membro CertValue deve essere impostato su una stringa ASCII con codifica Base64 del certificato pubblico.These objects must have a valid StartDate, EndDate, and have the CertValue member set to a base64-encoded ASCII string of the public certificate.

$cert = <public certificate as base64-encoded string>
$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADKeyCredential -Property @{ StartDate=Get-Date; EndDate=Get-Date -Year 2024; KeyId=New-Guid; CertValue=$cert}
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -KeyCredential $credentials

L'oggetto restituito da New-AzADServicePrincipal contiene i membri Id e DisplayName, che possono essere entrambi usati per l'accesso con l'entità servizio.The object returned from New-AzADServicePrincipal contains the Id and DisplayName members, either of which can be used for sign in with the service principal. I client che accedono con l'entità servizio devono anche accedere alla chiave privata del certificato.Clients which sign in with the service principal also need access to the certificate's private key.

Importante

L'accesso con un'entità servizio richiede l'ID del tenant in cui è stata creata.Signing in with a service principal requires the tenant ID which the service principal was created under. Per ottenere il tenant attivo quando è stata creata l'entità servizio, eseguire il comando seguente immediatamente dopo averla creata:To get the active tenant when the service principal was created, run the following command immediately after service principal creation:

(Get-AzContext).Tenant.Id

Ottenere un'entità servizio esistenteGet an existing service principal

L'elenco delle entità servizio per il tenant attualmente attivo può essere recuperato con Get-AzADServicePrincipal.A list of service principals for the currently active tenant can be retrieved with Get-AzADServicePrincipal. Per impostazione predefinita, questo comando restituisce tutte le entità servizio di un tenant, quindi per le organizzazioni più grandi la restituzione di risultati può richiedere tempi lunghi.By default this command returns all service principals in a tenant, so for large organizations, it may take a long time to return results. In alternativa, è consigliabile usare gli argomenti di filtro facoltativi sul lato server:Instead, using one of the optional server-side filtering arguments is recommended:

  • -DisplayNameBeginsWith richiede entità di servizio che abbiano un prefisso corrispondente al valore specificato.-DisplayNameBeginsWith requests service principals that have a prefix that match the provided value. Il nome visualizzato di un'entità servizio è il valore impostato con -DisplayName durante la creazione.The display name of a service principal is the value set with -DisplayName during creation.
  • -DisplayName richiede una corrispondenza esatta del nome di un'entità servizio.-DisplayName requests an exact match of a service principal name.

Gestire i ruoli delle entità servizioManage service principal roles

Azure PowerShell include i cmdlet seguenti per gestire le assegnazioni dei ruoli:Azure PowerShell has the following cmdlets to manage role assignments:

Il ruolo predefinito per un'entità servizio è quello Collaboratore.The default role for a service principal is Contributor. Questo ruolo ha autorizzazioni complete per la lettura e la scrittura in un account di Azure.This role has full permissions to read and write to an Azure account. Il ruolo Lettore è più restrittivo e offre l'accesso in sola lettura.The Reader role is more restrictive, with read-only access. Per altre informazioni sul controllo degli accessi in base al ruolo e i ruoli, vedere Controllo degli accessi in base al ruolo: ruoli predefiniti.For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

Questo esempio aggiunge il ruolo Lettore e rimuove il ruolo Collaboratore:This example adds the Reader role and removes the Contributor one:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName "Reader"
Remove-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName "Contributor"

Importante

I cmdlet per l'assegnazione dei ruoli non accettano l'ID oggetto entità servizio.Role assignment cmdlets don't take the service principal object ID. Accettano l'ID applicazione associato, generato al momento della creazione.They take the associated application ID, which is generated at creation time. Per ottenere l'ID applicazione per un'entità servizio, usare Get-AzADServicePrincipal.To get the application ID for a service principal, use Get-AzADServicePrincipal.

Nota

Se l'account non ha le autorizzazioni per assegnare un ruolo, verrà visualizzato un messaggio di errore che segnala che l'account non è autorizzato a eseguire l'azione 'Microsoft.Authorization/roleAssignments/write'. Per gestire i ruoli, contattare l'amministratore di Azure Active Directory.If your account doesn't have permission to assign a role, you see an error message that your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write'." Contact your Azure Active Directory admin to manage roles.

L'aggiunta di un ruolo non limita le autorizzazioni assegnate in precedenza.Adding a role doesn't restrict previously assigned permissions. Quando si limitano le autorizzazioni di un'entità servizio, il ruolo Collaboratore deve essere rimosso.When restricting a service principal's permissions, the Contributor role should be removed.

È possibile verificare le modifiche visualizzando l'elenco dei ruoli assegnati:The changes can be verified by listing the assigned roles:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Accedere con un'entità servizioSign in using a service principal

Testare le credenziali e le autorizzazioni della nuova entità servizio eseguendo l'accesso.Test the new service principal's credentials and permissions by signing in. Per accedere con un'entità servizio, è necessario il valore di applicationId associato e il tenant in cui è stata creata.To sign in with a service principal, you need the applicationId value associated with it, and the tenant it was created under.

Per accedere con un'entità servizio usando una password:To sign in with a service principal using a password:

# Use the application ID as the username, and the secret as password
$credentials = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $credentials -Tenant <tenant ID> 

Per l'autenticazione basata su certificato, è necessario che Azure PowerShell sia in grado di recuperare informazioni da un archivio certificati locale in base a un'identificazione personale del certificato.Certificate-based authentication requires that Azure PowerShell can retrieve information from a local certificate store based on a certificate thumbprint.

Connect-AzAccount -ServicePrincipal -Tenant <tenant ID> -CertificateThumbprint <thumbprint>

Per le istruzioni su come importare un certificato in un archivio certificati accessibile a PowerShell, vedere Accedere con Azure PowerShellFor instructions on importing a certificate into a credential store accessible by PowerShell, see Sign in with Azure PowerShell

Reimpostare le credenzialiReset credentials

Se si dimenticano le credenziali per un'entità di servizio, usare New-AzADSpCredential per aggiungerne una nuova.If you forget the credentials for a service principal, use New-AzADSpCredential to add a new credential. Questo cmdlet accetta gli stessi argomenti e tipi di credenziali di New-AzADServicePrincipal.This cmdlet takes the same credential arguments and types as New-AzADServicePrincipal. Senza argomenti di credenziali, viene creato un nuovo oggetto PasswordCredential con una password casuale.Without any credential arguments, a new PasswordCredential with a random password is created.

Importante

Prima di assegnare nuove credenziali, è consigliabile rimuovere quelle esistenti per evitare che vengano usate per l'accesso.Before assigning any new credentials, you may want to remove existing credentials to prevent sign in with them. A questo scopo, usare il cmdlet Remove-AzADSpCredential:To do so, use the Remove-AzADSpCredential cmdlet:

Remove-AzADSpCredential -DisplayName ServicePrincipalName
$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName