Freigeben über

Erstellen eines Azure-Dienstprinzipals mit Azure PowerShell

  • Artikel

Für automatisierte Tools, die Azure-Dienste verwenden, sollten stets eingeschränkte Berechtigungen festgelegt sein. Azure bietet Dienstprinzipale, damit Anwendungen nicht als Benutzer mit uneingeschränkten Berechtigungen angemeldet werden müssen.

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. 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. Aus Sicherheitsgründen wird stets empfohlen, Dienstprinzipale mit automatisierten Tools zu verwenden, statt ihnen die Anmeldung mit einer Benutzeridentität zu erlauben.

In diesem Artikel wird Schritt für Schritt erläutert, wie Sie mit Azure PowerShell einen Dienstprinzipal erstellen, Informationen zu ihm abrufen und ihn zurücksetzen.

Achtung

Wenn Sie mithilfe des Befehls New-AzADServicePrincipal einen Dienstprinzipal erstellen, enthält die Ausgabe Anmeldeinformationen, die geschützt werden müssen. Verwenden Sie als Alternative ggf. verwaltete Identitäten, um zu vermeiden, dass die Verwendung von Anmeldeinformationen erforderlich ist.

Voraussetzungen

Erstellen eines Dienstprinzipals

Erstellen Sie mit dem Cmdlet New-AzADServicePrincipal einen Dienstprinzipal. Beim Erstellen eines Dienstprinzipals wählen Sie den Typ der von ihm verwendeten Anmeldeauthentifizierung aus.

Wichtig

Ab Version 7.x des Az-Moduls von PowerShell weist New-AzADServicePrincipal dem Dienstprinzipal nicht mehr standardmäßig die Rolle Mitwirkender zu. Informationen zum Zuweisen einer bestimmten Rolle zu einem Dienstprinzipal finden Sie unter Schritte zum Zuweisen einer Azure-Rolle.

Hinweis

Wenn Ihr Konto nicht über die Berechtigung zum Erstellen eines Dienstprinzipals verfügt, gibt New-AzADServicePrincipal eine Fehlermeldung mit dem Hinweis „Nicht genügend Berechtigungen zum Abschließen des Vorgangs“ zurück. Wenden Sie sich an Ihre*n Microsoft Entra-Administrator*in, um einen Dienstprinzipal zu erstellen.

In einem Microsoft Entra-ID-Verzeichnis, in dem die Benutzereinstellung Benutzer können Anwendungen registriere auf Nein festgelegt wurde, müssen Sie Mitglied einer der folgenden integrierten Microsoft Entra-ID-Rollen sein (die folgende Aktion haben: microsoft.directory/applications/createAsOwner oder microsoft.directory/applications/create):

Weitere Informationen zu Benutzereinstellungen in Microsoft Entra ID finden Sie unter Einschränken, welche Benutzer Anwendungen erstellen können.

Für Dienstprinzipale stehen zwei Authentifizierungstypen zur Verfügung: Kennwortbasierte Authentifizierung und zertifikatbasierte Authentifizierung.

Kennwortbasierte Authentifizierung

Wichtig

Die Standardrolle für einen Dienstprinzipal mit kennwortbasierter Authentifizierung ist Mitwirkender. Diese Rolle besitzt uneingeschränkte Berechtigungen für Lese- und Schreibvorgänge in einem Azure-Konto. Informationen zum Verwalten von Rollenzuweisungen finden Sie unter Verwalten von Dienstprinzipalrollen.

Ohne weitere Authentifizierungsparameter wird die kennwortbasierte Authentifizierung mit einem für Sie erstellten zufälligen Kennwort verwendet. Diese Methode wird empfohlen, wenn Sie die kennwortbasierte Authentifizierung verwenden möchten.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

Das zurückgegebene Objekt enthält die Eigenschaft PasswordCredentials.SecretText, die das generierte Kennwort enthält. Achten Sie darauf, diesen Wert für die Authentifizierung beim Dienstprinzipal an einem sicheren Ort zu speichern. Der Wert wird nicht in der Konsolenausgabe angezeigt. Wenn Sie das Kennwort verlieren, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.

Mit dem folgenden Code können Sie das Geheimnis exportieren:

$sp.PasswordCredentials.SecretText

Das von New-AzADServicePrincipal zurückgegebene Objekt enthält die Member Id und DisplayName, die jeweils für die Anmeldung beim Dienstprinzipal verwendet werden können.

Wichtig

Das Anmelden bei einem Dienstprinzipal erfordert die ID des Mandanten, unter dem der Dienstprinzipal erstellt wurde. Führen Sie den folgenden Befehl unmittelbar nach der Erstellung des Dienstprinzipals aus, um den aktiven Mandanten abzurufen:

(Get-AzContext).Tenant.Id

Zertifikatbasierte Authentifizierung

Wichtig

Beim Erstellen eines Dienstprinzipals mit zertifikatbasierter Authentifizierung wird keine Standardrolle zugewiesen. Informationen zum Verwalten von Rollenzuweisungen finden Sie unter Verwalten von Dienstprinzipalrollen.

Dienstprinzipale mit zertifikatbasierter Authentifizierung werden mit dem Parameter CertValue erstellt. Dieser Parameter nimmt eine Base64-codierte ASCII-Zeichenfolge des öffentlichen Zertifikats entgegen. Diese wird durch eine PEM-Datei oder eine textcodierte CRT- oder CER-Datei dargestellt. Binäre Codierungen des öffentlichen Zertifikats werden nicht unterstützt. Für diese Anweisungen wird davon ausgegangen, dass bereits ein Zertifikat verfügbar ist.

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

Das von New-AzADServicePrincipal zurückgegebene Objekt enthält die Eigenschaften Id und DisplayName, die jeweils für die Anmeldung beim Dienstprinzipal verwendet werden können. Clients benötigen für die Anmeldung beim Dienstprinzipal außerdem Zugriff auf den privaten Schlüssel des Zertifikats.

Wichtig

Das Anmelden bei einem Dienstprinzipal erfordert die ID des Mandanten, unter dem der Dienstprinzipal erstellt wurde. Führen Sie den folgenden Befehl unmittelbar nach der Erstellung des Dienstprinzipals aus, um den aktiven Mandanten abzurufen:

(Get-AzContext).Tenant.Id

Abrufen eines vorhandenen Dienstprinzipals

Eine Liste der Dienstprinzipale für den aktiven Mandanten kann mit Get-AzADServicePrincipal abgerufen werden. Dieser Befehl gibt standardmäßig alle Dienstprinzipale in einem Mandanten zurück. Für große Organisationen kann es lange dauern, bis Ergebnisse zurückgegeben werden. Stattdessen wird die Verwendung eines der optionalen serverseitigen Filterungsargumente empfohlen:

  • DisplayNameBeginsWith fordert Dienstprinzipale mit einem Präfix an, das dem angegebenen Wert entspricht. Der Anzeigename eines Dienstprinzipals ist der Wert, der während der Erstellung mit DisplayName festgelegt wird.
  • DisplayName fordert die genaue Übereinstimmung eines Dienstprinzipalnamens an.

Verwalten von Dienstprinzipalrollen

Für die Verwaltung von Rollenzuweisungen stehen in Azure PowerShell folgende Cmdlets zur Verfügung:

Weitere Informationen zur rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) finden Sie unter Rollenbasierte Zugriffssteuerung: Integrierte Rollen.

Das folgende Beispiel fügt die Rolle Leser hinzu und entfernt die Rolle Mitwirkender:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName 'Reader'
Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName 'Contributor'

Wichtig

Cmdlets für die Rollenzuweisung akzeptieren die Objekt-ID des Dienstprinzipals nicht. Sie nehmen die zugeordnete Anwendungs-ID an, die zum Zeitpunkt der Erstellung generiert wird. Verwenden Sie Get-AzADServicePrincipal zum Abrufen der Anwendungs-ID für einen Dienstprinzipal.

Hinweis

Wenn Ihr Konto nicht über die Berechtigung zum Zuweisen einer Rolle verfügt, wird eine Fehlermeldung mit dem Hinweis angezeigt, dass Ihr Konto nicht über die Berechtigung zum Ausführen der Aktion „Microsoft.Authorization/roleAssignments/write“ verfügt. Wenden Sie sich an Ihre*n Microsoft Entra-Administrator*in, um Rollen zu verwalten.

Durch das Hinzufügen einer Rolle werden zuvor zugewiesene Berechtigungen nicht eingeschränkt. Beim Einschränken der Berechtigungen eines Dienstprinzipals sollte die Rolle Mitwirkender entfernt werden.

Die Änderungen können durch Auflisten der zugewiesenen Rollen überprüft werden:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Anmelden mithilfe eines Dienstprinzipals

Testen Sie die Anmeldeinformationen und Berechtigungen des neuen Dienstprinzipals, indem Sie sich anmelden. Für die Anmeldung bei einem Dienstprinzipal benötigen Sie den zugeordneten applicationId-Wert und den Mandanten, unter dem er erstellt wurde.

So melden Sie sich mit einem Dienstprinzipal und einem Kennwort an:

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

Zertifikatbasierte Authentifizierung erfordert, dass Azure PowerShell Informationen von einem lokalen Zertifikatsspeicher basierend auf einem Fingerabdruck des Zertifikats abrufen kann.

Connect-AzAccount -ServicePrincipal -Tenant <TenantId> -CertificateThumbprint <Thumbprint> -ApplicationId <ApplicationId>

Anweisungen zum Importieren eines Zertifikats in einen für PowerShell zugänglichen Anmeldeinformationsspeicher finden Sie unter Zertifikatbasierte Authentifizierung.

Zurücksetzen von Anmeldeinformation

Wenn Sie die Anmeldeinformationen für einen Dienstprinzipal vergessen, verwenden Sie New-AzADSpCredential, um neue Anmeldeinformationen mit einem zufälligen Kennwort hinzuzufügen. Dieses Cmdlet unterstützt beim Zurücksetzen des Kennworts keine benutzerdefinierten Anmeldeinformationen.

Wichtig

Vor dem Zuweisen von neuen Anmeldeinformationen empfiehlt es sich, vorhandene Anmeldeinformationen zu entfernen, um eine versehentliche Anmeldung damit zu verhindern. Verwenden Sie dazu das Cmdlet Remove-AzADSpCredential:

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Problembehandlung

Bei Anzeige der Fehlermeldung „New-AzADServicePrincipal: Another object with the same value for property identifierUris already exists.“ stellen Sie sicher, dass noch kein Dienstprinzipal mit dem gleichen Namen vorhanden ist.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Wenn der vorhandene Dienstprinzipal nicht mehr benötigt wird, können Sie ihn mit dem folgenden Beispiel entfernen.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Dieser Fehler kann auch auftreten, wenn Sie zuvor einen Dienstprinzipal für eine Azure Active Directory-Anwendung erstellt haben. Wenn Sie den Dienstprinzipal entfernen, ist die Anwendung weiterhin verfügbar. Diese Anwendung verhindert, dass Sie einen anderen Dienstprinzipal mit demselben Namen erstellen.

Verwenden Sie das folgende Beispiel, um zu überprüfen, ob bereits eine Microsoft Entra-Anwendung mit demselben Namen vorhanden ist:

Get-AzADApplication -DisplayName ServicePrincipalName

Wenn eine Anwendung mit demselben Namen vorhanden ist und nicht mehr benötigt wird, kann Sie mithilfe des folgenden Beispiels entfernt werden.

Remove-AzADApplication -DisplayName ServicePrincipalName

Wählen Sie andernfalls einen alternativen Namen für den neuen Dienstprinzipal aus, den Sie erstellen möchten.