Create an Azure service principal with Azure PowerShell
Статия
Automated tools that use Azure services should always have restricted permissions. Instead of having
applications sign in as a fully privileged user, Azure offers service principals.
An Azure service principal is an identity created for use with applications, hosted services, and
automated tools to access Azure resources. 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. 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.
This article shows you the steps for creating, getting information about, and resetting a service
principal with Azure PowerShell.
Внимание
When you create a service principal using the
New-AzADServicePrincipal command, the
output includes credentials that you must protect. As an alternative, consider using
managed identities to avoid
the need to use credentials.
Create a service principal with the
New-AzADServicePrincipal cmdlet. When
creating a service principal, you choose the type of sign-in authentication it uses.
If your account doesn't have permission to create a service principal, New-AzADServicePrincipal
returns an error message containing "Insufficient privileges to complete the operation". Contact
your Microsoft Entra admin to create a service principal.
In a Microsoft Entra ID directory where user setting Users can register applications has been
set to No, you must be a member of one of the following Microsoft Entra ID built-in roles
(which have the action: microsoft.directory/applications/createAsOwner or microsoft.directory/applications/create):
There are two types of authentication available for service principals: Password-based
authentication, and certificate-based authentication.
Password-based authentication
Важно
The default role for a password-based authentication service principal is Contributor. This
role has full permissions to read and write to an Azure account. For information on managing role
assignments, see
Manage service principal roles.
Without any other authentication parameters, password-based authentication is used and a random
password created for you. If you want password-based authentication, this method is recommended.
The returned object contains the PasswordCredentials.SecretText property containing the generated
password. Make sure that you store this value somewhere secure to authenticate with the service
principal. Its value won't be displayed in the console output. If you lose the password,
reset the service principal credentials.
The following code allows you to export the secret:
Azure PowerShell
$sp.PasswordCredentials.SecretText
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.
Важно
Signing in with a service principal requires the tenant ID which the service principal was created
under. To get the active tenant when the service principal was created, run the following command
immediately after service principal creation:
Azure PowerShell
(Get-AzContext).Tenant.Id
Certificate-based authentication
Важно
There is no default role assigned when creating a certificate-based authentication service
principal. For information on managing role assignments, see
Manage service principal roles.
Service principals using certificate-based authentication are created with the CertValue
parameter. This parameter takes a base64-encoded ASCII string of the public certificate. This is
represented by a PEM file, or a text-encoded CRT or CER. Binary encodings of the public certificate
aren't supported. These instructions assume that you already have a certificate available.
The object returned from New-AzADServicePrincipal contains the Id and DisplayName properties,
either of which can be used for sign in with the service principal. Clients which sign in with the
service principal also need access to the certificate's private key.
Важно
Signing in with a service principal requires the tenant ID which the service principal was created
under. To get the active tenant when the service principal was created, run the following command
immediately after service principal creation:
Azure PowerShell
(Get-AzContext).Tenant.Id
Get an existing service principal
A list of service principals for the active tenant can be retrieved with
Get-AzADServicePrincipal. By default
this command returns all service principals in a tenant. For large organizations, it may take
a long time to return results. Instead, using one of the optional server-side filtering arguments is
recommended:
DisplayNameBeginsWith requests service principals that have a prefix that match the provided
value. The display name of a service principal is the value set with DisplayName during
creation.
DisplayName requests an exact match of a service principal name.
Manage service principal roles
Azure PowerShell has the following cmdlets to manage role assignments:
For more information on Role-Based Access Control (RBAC) and roles, see
RBAC: Built-in roles.
The following example adds the Reader role and removes the Contributor role:
Azure PowerShell
New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName'Reader'Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName'Contributor'
Важно
Role assignment cmdlets don't take the service principal object ID. They take the associated
application ID, which is generated at creation time. To get the application ID for a service
principal, use Get-AzADServicePrincipal.
Бележка
If your account doesn't have permission to assign a role, you see an error message that your
account "doesn't have authorization to perform action
'Microsoft.Authorization/roleAssignments/write'". Contact your Microsoft Entra admin to
manage roles.
Adding a role doesn't restrict previously assigned permissions. When restricting a service
principal's permissions, the Contributor role should be removed.
The changes can be verified by listing the assigned roles:
Test the new service principal's credentials and permissions by signing in. To sign in with a
service principal, you need the applicationId value associated with it, and the tenant it's
created under.
To sign in with a service principal using a password:
Azure PowerShell
# Use the application ID as the username, and the secret as password$credentials = Get-CredentialConnect-AzAccount -ServicePrincipal -Credential$credentials -Tenant <tenant ID>
Certificate-based authentication requires that Azure PowerShell can retrieve information from a
local certificate store based on a certificate thumbprint.
For instructions on importing a certificate into a credential store accessible by PowerShell, see
Certificate-based authentication
Reset credentials
If you forget the credentials for a service principal, use
New-AzADSpCredential to add a new credential
with a random password. This cmdlet doesn't support user-defined credentials when resetting the
password.
Важно
Before assigning any new credentials, you may want to remove existing credentials to prevent sign
in with them. To do so, use the
Remove-AzADSpCredential cmdlet:
If you receive the error: "New-AzADServicePrincipal: Another object with the same value for
property identifierUris already exists.", verify that a service principal with the same name
doesn't already exist.
This error can also occur when you've previously created a service principal for an Azure Active
Directory application. If you remove the service principal, the application is still available. This
application prevents you from creating another service principal with the same name.
You can use the following example to verify that a Microsoft Entra application with the same
name doesn't exist:
Otherwise, choose an alternate name for the new service principal that you're attempting to create.
Работете съвместно с нас в GitHub
Източникът за това съдържание може да бъде намерен в GitHub, където можете също да създавате и преглеждате проблеми и да изтегляте искания. За повече информация вижте нашето ръководство за сътрудник.
Обратна връзка за Azure PowerShell
Azure PowerShell е проект с отворен код. Изберете връзка, за да предоставите обратна връзка: