Erstellen eines Azure-Dienstprinzipals mit der Azure-BefehlszeilenschnittstelleCreate an Azure service principal with the Azure CLI

Für automatisierte Tools, die Azure-Dienste verwenden, sollten stets eingeschränkte Berechtigungen festgelegt sein.Automated tools that use Azure services should always have restricted permissions. Azure bietet Dienstprinzipale, damit Anwendungen nicht als Benutzer mit uneingeschränkten Berechtigungen angemeldet werden müssen.Instead of having applications sign in as a fully privileged user, Azure offers service principals.

Ein Azure-Dienstprinzipal ist eine Identität, die zur Verwendung mit Anwendungen, gehosteten Diensten und automatisierten Tools für den Zugriff auf Azure-Ressourcen erstellt wird.An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Dieser Zugriff wird durch die dem Dienstprinzipal zugewiesenen Rollen eingeschränkt. Dadurch können Sie steuern, auf welcher Ebene auf welche Ressourcen zugegriffen werden kann.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. Aus Sicherheitsgründen wird stets empfohlen, Dienstprinzipale mit automatisierten Tools zu verwenden, statt ihnen die Anmeldung mit einer Benutzeridentität zu erlauben.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.

In diesem Artikel wird Schritt für Schritt erläutert, wie Sie mit der Azure CLI einen Dienstprinzipal erstellen, Informationen zu ihm abrufen und ihn zurücksetzen.This article shows you the steps for creating, getting information about, and resetting a service principal with the Azure CLI.

Erstellen eines DienstprinzipalsCreate a service principal

Erstellen Sie mit dem Befehl az ad sp create-for-rbac einen Dienstprinzipal.Create a service principal with the az ad sp create-for-rbac command. Beim Erstellen eines Dienstprinzipals wählen Sie den Typ der von ihm verwendeten Anmeldeauthentifizierung aus.When creating a service principal, you choose the type of sign-in authentication it uses.

Hinweis

Wenn Ihr Konto nicht über Berechtigungen zum Erstellen eines Dienstprinzipals verfügt, gibt az ad sp create-for-rbac eine Fehlermeldung mit dem Hinweis „Nicht genügend Berechtigungen zum Abschließen des Vorgangs“ zurück.If your account doesn't have permission to create a service principal, az ad sp create-for-rbac will return an error message containing "Insufficient privileges to complete the operation." Bitten Sie den Azure Active Directory-Administrator, einen Dienstprinzipal zu erstellen.Contact your Azure Active Directory admin to create a service principal.

Für Dienstprinzipale stehen zwei Authentifizierungstypen zur Verfügung: Kennwortbasierte Authentifizierung und zertifikatbasierte Authentifizierung.There are two types of authentication available for service principals: Password-based authentication, and certificate-based authentication.

Kennwortbasierte AuthentifizierungPassword-based authentication

Ohne jegliche Authentifizierungsparameter wird die kennwortbasierte Authentifizierung mit einem für Sie erstellten zufälligen Kennwort verwendet.Without any authentication parameters, password-based authentication is used with a random password created for you.

az ad sp create-for-rbac --name ServicePrincipalName

Wichtig

Ab Azure CLI 2.0.68 wird der Parameter --password zum Erstellen eines Dienstprinzipals mit einem benutzerdefinierten Kennwort nicht mehr unterstützt, um die versehentliche Verwendung von unsicheren Kennwörtern zu verhindern.As of Azure CLI 2.0.68, the --password parameter to create a service principal with a user-defined password is no longer supported to prevent the accidental use of weak passwords.

Die Ausgabe für einen Dienstprinzipal mit Kennwortauthentifizierung enthält den Schlüssel password.The output for a service principal with password authentication includes the password key. Kopieren Sie diesen Wert unbedingt, da er nicht abgerufen werden kann.Make sure you copy this value - it can't be retrieved. Wenn Sie das Kennwort vergessen haben, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.If you forget the password, reset the service principal credentials.

Die Schlüssel appId und tenant werden in der Ausgabe von az ad sp create-for-rbac angezeigt und bei der Dienstprinzipalauthentifizierung verwendet.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Notieren Sie die Werte. Sie können jedoch auch jederzeit mit az ad sp list abgerufen werden.Record their values, but they can be retrieved at any point with az ad sp list.

Zertifikatbasierte AuthentifizierungCertificate-based authentication

Verwenden Sie für die zertifikatbasierte Authentifizierung das Argument --cert.For certificate-based authentication, use the --cert argument. Bei Verwendung dieses Arguments muss bereits ein Zertifikat vorhanden sein.This argument requires that you hold an existing certificate. Vergewissern Sie sich, dass alle Tools, die diesen Dienstprinzipal verwenden, Zugriff auf den privaten Schlüssel des Zertifikats haben.Make sure any tool that uses this service principal has access to the certificate's private key. Zertifikate müssen in einem ASCII-Format vorliegen, etwa PEM, CER oder DER.Certificates should be in an ASCII format such as PEM, CER, or DER. Übergeben Sie das Zertifikat als Zeichenfolge, oder verwenden Sie das Format @path, um das Zertifikat aus einer Datei zu laden.Pass the certificate as a string, or use the @path format to load the certificate from a file.

Hinweis

Bei Verwendung einer PEM-Datei muss das Zertifikat (CERTIFICATE) an den privaten Schlüssel (PRIVATE KEY) in der Datei angefügt werden.When using a PEM file, the CERTIFICATE must be appended to the PRIVATE KEY within the file.

az ad sp create-for-rbac --name ServicePrincipalName --cert "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
az ad sp create-for-rbac --name ServicePrincipalName --cert @/path/to/cert.pem

Das Argument --keyvault kann hinzugefügt werden, um ein Zertifikat in Azure Key Vault zu verwenden.The --keyvault argument can be added to use a certificate in Azure Key Vault. In diesem Fall ist der Wert --cert der Name des Zertifikats.In this case, the --cert value is the name of the certificate.

az ad sp create-for-rbac --name ServicePrincipalName --cert CertName --keyvault VaultName

Verwenden Sie das Argument --create-cert, um ein selbstsigniertes Zertifikat für die Authentifizierung zu erstellen:To create a self-signed certificate for authentication, use the --create-cert argument:

az ad sp create-for-rbac --name ServicePrincipalName --create-cert

Konsolenausgabe:Console output:

Creating a role assignment under the scope of "/subscriptions/myId"
Please copy C:\myPath\myNewFile.pem to a safe place.
When you run 'az login', provide the file path in the --password argument
{
  "appId": "myAppId",
  "displayName": "myDisplayName",
  "fileWithCertAndPrivateKey": "C:\\myPath\\myNewFile.pem",
  "name": "http://myName",
  "password": null,
  "tenant": "myTenantId"
}

Inhalt der neuen PEM-Datei:Contents of the new PEM file:

-----BEGIN PRIVATE KEY-----
myPrivateKeyValue
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
myCertificateValue
-----END CERTIFICATE-----

Hinweis

Mit dem Befehl az ad sp create-for-rbac --create-cert werden der Dienstprinzipal und eine PEM-Datei erstellt.The az ad sp create-for-rbac --create-cert command creates the service principal and a PEM file. Die PEM-Datei enthält einen ordnungsgemäß formatierten privaten Schlüssel (PRIVATE KEY) und ein ordnungsgemäß formatiertes Zertifikat (CERTIFICATE).The PEM file contains a correctly formatted PRIVATE KEY and CERTIFICATE.

Das Argument --keyvault kann hinzugefügt werden, um das Zertifikat in Azure Key Vault zu speichern.The --keyvault argument can be added to store the certificate in Azure Key Vault. Bei Verwendung von --keyvault ist das Argument --certerforderlich.When using --keyvault, the --cert argument is required.

az ad sp create-for-rbac --name ServicePrincipalName --create-cert --cert CertName --keyvault VaultName

Die Ausgabe enthält den Schlüssel fileWithCertAndPrivateKey, es sei denn, Sie speichern das Zertifikat in Key Vault.Unless you store the certificate in Key Vault, the output includes the fileWithCertAndPrivateKey key. Am Wert dieses Schlüssels können Sie erkennen, wo das generierte Zertifikat gespeichert ist.This key's value tells you where the generated certificate is stored. Kopieren Sie das Zertifikat unbedingt an einen sicheren Speicherort. Andernfalls können Sie sich nicht mit diesem Dienstprinzipal anmelden.Make sure that you copy the certificate to a secure location, or you can't sign in with this service principal.

Rufen Sie für in Key Vault gespeicherte Zertifikate den privaten Schlüssel des Zertifikats mit az keyvault secret show ab.For certificates stored in Key Vault, retrieve the certificate's private key with az keyvault secret show. In Key Vault ist der Name des Zertifikatgeheimnisses mit dem Zertifikatnamen identisch.In Key Vault, the name of the certificate's secret is the same as the certificate name. Wenn Sie keinen Zugriff mehr auf den privaten Schlüssel des Zertifikats haben, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.If you lose access to a certificate's private key, reset the service principal credentials.

Die Schlüssel appId und tenant werden in der Ausgabe von az ad sp create-for-rbac angezeigt und bei der Dienstprinzipalauthentifizierung verwendet.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Notieren Sie die Werte. Sie können jedoch auch jederzeit mit az ad sp list abgerufen werden.Record their values, but they can be retrieved at any point with az ad sp list.

Abrufen eines vorhandenen DienstprinzipalsGet an existing service principal

Mit az ad sp list kann eine Liste der Dienstprinzipale in einem Mandanten abgerufen werden.A list of the service principals in a tenant can be retrieved with az ad sp list. Dieser Befehl gibt standardmäßig die ersten 100 Dienstprinzipale für Ihren Mandanten zurück.By default this command returns the first 100 service principals for your tenant. Verwenden Sie zum Abrufen aller Dienstprinzipale eines Mandanten das Argument --all.To get all of a tenant's service principals, use the --all argument. Da das Abrufen dieser Liste sehr lange dauern kann, wird empfohlen, die Liste mit einem der folgenden Argumente zu filtern:Getting this list can take a long time, so it's recommended that you filter the list with one of the following arguments:

  • --display-name fordert Dienstprinzipale mit einem Präfix an, das dem angegebenen Namen entspricht.--display-name requests service principals that have a prefix that match the provided name. Der Anzeigename eines Dienstprinzipals ist der Wert, der während der Erstellung mit dem Parameter --name festgelegt wird.The display name of a service principal is the value set with the --name parameter during creation. Haben Sie --name während der Erstellung des Dienstprinzipals nicht festgelegt, lautet das Namenspräfix azure-cli-.If you didn't set --name during service principal creation, the name prefix is azure-cli-.
  • --spn filtert nach genauen Übereinstimmungen des Dienstprinzipalnamens.--spn filters on exact service principal name matching. Der Dienstprinzipalname beginnt immer mit https://.The service principal name always starts with https://. Handelte es sich bei dem für --name verwendeten Wert nicht um einen URI, wird für diesen Wert https:// gefolgt vom Anzeigenamen verwendet.if the value you used for --name wasn't a URI, this value is https:// followed by the display name.
  • --show-mine fordert nur Dienstprinzipale an, die vom angemeldeten Benutzer erstellt wurden.--show-mine requests only service principals created by the signed-in user.
  • --filter akzeptiert einen OData-Filter und führt die serverseitige Filterung aus.--filter takes an OData filter, and performs server-side filtering. Diese Methode wird anstelle der clientseitigen Filterung mit dem Argument --query der CLI empfohlen.This method is recommended over filtering client-side with the CLI's --query argument. Weitere Informationen zu OData-Filtern finden Sie unter OData-Ausdruckssyntax für Filter und Sortierklauseln in Azure Search.To learn about OData filters, see OData expression syntax for filters.

Für Dienstprinzipalobjekte werden ausführliche Informationen zurückgegeben.The information returned for service principal objects is verbose. Verwenden Sie die Abfragezeichenfolge [].{id:appId, tenant:appOwnerTenantId}, um nur die für die Anmeldung erforderlichen Informationen abzurufen.To get only the information necessary for sign-in, use the query string [].{id:appId, tenant:appOwnerTenantId}. Die Anmeldeinformationen für alle Dienstprinzipale, die vom derzeit angemeldeten Benutzer erstellt wurden, rufen Sie beispielsweise wie folgt ab:For example, to get the sign-in information for all service principals created by the currently logged in user:

az ad sp list --show-mine --query "[].{id:appId, tenant:appOwnerTenantId}"

Wichtig

Mit az ad sp list und az ad sp show rufen Sie den Benutzer und den Mandanten ab, allerdings nicht die Authentifizierungsgeheimnisse oder die Authentifizierungsmethode.az ad sp list or az ad sp show get the user and tenant, but not any authentication secrets or the authentication method. Geheimnisse für Zertifikate in Key Vault können mit az keyvault secret show abgerufen werden. Andere Geheimnisse werden jedoch nicht standardmäßig gespeichert.Secrets for certificates in Key Vault can be retrieved with az keyvault secret show, but no other secrets are stored by default. Wenn Sie eine Authentifizierungsmethode oder ein Geheimnis vergessen haben, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.If you forget an authentication method or secret, reset the service principal credentials.

Verwalten von DienstprinzipalrollenManage service principal roles

Die Azure CLI enthält die folgenden Befehle zum Verwalten von Rollenzuweisungen:The Azure CLI has the following commands to manage role assignments:

Standardmäßig hat ein Dienstprinzipal die Rolle Mitwirkender.The default role for a service principal is Contributor. Diese Rolle besitzt uneingeschränkte Berechtigungen für Lese- und Schreibvorgänge in einem Azure-Konto.This role has full permissions to read and write to an Azure account. Die Rolle Leser ist stärker eingeschränkt und bietet schreibgeschützten Zugriff.The Reader role is more restrictive, with read-only access. Weitere Informationen zur rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) finden Sie unter Rollenbasierte Zugriffssteuerung: Integrierte Rollen.For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

Das folgende Beispiel fügt die Rolle Leser hinzu und entfernt die Rolle Mitwirkender:This example adds the Reader role and removes the Contributor one:

az role assignment create --assignee APP_ID --role Reader
az role assignment delete --assignee APP_ID --role Contributor

Hinweis

Wenn Ihr Konto nicht über Berechtigungen zum Zuweisen einer Rolle verfügt, wird eine Fehlermeldung mit dem Hinweis angezeigt, dass Ihr Konto keine Berechtigung zum Ausführen der Aktion „Microsoft.Authorization/roleAssignments/write“ hat. Bitten Sie den Azure Active Directory-Administrator um die Verwaltung von Rollen.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.

Durch das Hinzufügen einer Rolle werden zuvor zugewiesene Berechtigungen nicht eingeschränkt.Adding a role doesn't restrict previously assigned permissions. Beim Einschränken der Berechtigungen eines Dienstprinzipals sollte die Rolle Mitwirkender entfernt werden.When restricting a service principal's permissions, the Contributor role should be removed.

Die Änderungen können durch Auflisten der zugewiesenen Rollen überprüft werden:The changes can be verified by listing the assigned roles:

az role assignment list --assignee APP_ID

Anmelden mithilfe eines DienstprinzipalsSign in using a service principal

Testen Sie die Anmeldeinformationen und Berechtigungen des neuen Dienstprinzipals, indem Sie sich anmelden.Test the new service principal's credentials and permissions by signing in. Für die Anmeldung mit einem Dienstprinzipal benötigen Sie appId, tenant und Anmeldeinformationen.To sign in with a service principal, you need the appId, tenant, and credentials.

So melden Sie sich mit einem Dienstprinzipal und einem Kennwort an:To sign in with a service principal using a password:

az login --service-principal --username APP_ID --password PASSWORD --tenant TENANT_ID

Um sich mit einem Zertifikat anmelden zu können, muss es lokal als PEM- oder DER-Datei im ASCII-Format verfügbar sein.To sign in with a certificate, it must be available locally as a PEM or DER file, in ASCII format. Bei Verwendung einer PEM-Datei müssen der private Schlüssel (PRIVATE KEY) und das Zertifikat (CERTIFICATE) gemeinsam innerhalb der Datei angefügt werden.When using a PEM file, the PRIVATE KEY and CERTIFICATE must be appended together within the file.

az login --service-principal --username APP_ID --tenant TENANT_ID --password /path/to/cert

Weitere Informationen zum Anmelden mit einem Dienstprinzipal finden Sie unter Anmelden mit der Azure CLI.To learn more about signing in with a service principal, see Sign in with the Azure CLI.

Zurücksetzen von AnmeldeinformationReset credentials

Wenn Sie die Anmeldeinformationen für einen Dienstprinzipal vergessen haben, verwenden Sie az ad sp credential reset.If you forget the credentials for a service principal, use az ad sp credential reset. Der Befehl zum Zurücksetzen akzeptiert die gleichen Argumente wie az ad sp create-for-rbac.The reset command takes the same arguments as az ad sp create-for-rbac.

az ad sp credential reset --name APP_ID