Arbeiten mit Azure-Dienstprinzipalen über die Azure CLI

  • 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.

Was ist ein Azure-Dienstprinzipal?

Ein Azure-Dienstprinzipal ist eine Identität, die zur Verwendung mit Anwendungen, gehosteten Diensten und automatisierten Tools für den Zugriff auf Ressourcen erstellt wird. Die dem Dienstprinzipal zugewiesenen Rollen beschränken den Zugriff. Dadurch haben Sie die Kontrolle darüber, auf welche Ressourcen auf welcher Ebene 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 der Azure CLI einen Azure-Dienstprinzipal erstellen, Informationen zu ihm abrufen und ihn zurücksetzen.

1 Erstellen eines Dienstprinzipals

Erstellen Sie mit dem Befehl az ad sp create-for-rbac einen Azure-Dienstprinzipal.

Die Schlüssel appId und tenant werden in der Ausgabe von az ad sp create-for-rbac angezeigt und bei der Dienstprinzipalauthentifizierung verwendet. Notieren Sie die Werte. Sie können jedoch auch jederzeit mit az ad sp list abgerufen werden.

Beim Erstellen eines Dienstprinzipals wählen Sie den Typ der von ihm verwendeten Anmeldeauthentifizierung aus. Für Azure-Dienstprinzipale sind zwei Arten von Authentifizierung verfügbar: kennwortbasiert und zertifikatbasiert.

Warnung

Wenn Sie mithilfe des Befehls az ad sp create-for-rbac einen Azure-Dienstprinzipal erstellen, enthält die Ausgabe Anmeldeinformationen, die geschützt werden müssen. Schließen Sie diese Anmeldeinformationen nicht in Ihren Code ein, und checken Sie sie nicht in Ihre Quellcodeverwaltung ein. Verwenden Sie als Alternative ggf. verwaltete Identitäten (sofern verfügbar), um zu vermeiden, dass die Verwendung von Anmeldeinformationen erforderlich ist.

Um das Risiko eines kompromittierten Dienstprinzipals zu verringern, weisen Sie eine spezifischere Rolle zu, und schränken Sie die Bereiche auf eine Ressource oder Ressourcengruppe ein. Weitere Informationen finden Sie unter Schritte zum Hinzufügen einer Rollenzuweisung.

Kennwortbasierte Authentifizierung

Bei der kennwortbasierten Authentifizierung wird ein zufälliges Kennwort für Sie erstellt. Wenn Sie keinen Parameterwert vom Typ --name angeben, wird ein Name mit einem Zeitstempel für Sie erstellt. Sie müssen einen Wert für --scopes angeben, da dieser Wert keinen Standardwert hat. Wenn Sie möchten, können Sie die Rollenzuweisung später mit az role assignment create festlegen.

# Create a service principal without a role assignment
az ad sp create-for-rbac --scopes /subscriptions/mySubscriptionID

# Create a service principal for a resource group using a preferred name and role
az ad sp create-for-rbac --name myServicePrincipalName \
                         --role reader \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

Sie können für die Erstellung eines Dienstprinzipals auch Variablen verwenden.

let "randomIdentifier=$RANDOM*$RANDOM"  
servicePrincipalName="msdocs-sp-$randomIdentifier"
roleName="azureRoleName"
subscriptionID=$(az account show --query id -o tsv)
# Verify the ID of the active subscription
echo "Using subscription ID $subscriptionID"
resourceGroup="myResourceGroupName"

echo "Creating SP for RBAC with name $servicePrincipalName, with role $roleName and in scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup"
az ad sp create-for-rbac --name $servicePrincipalName --role $roleName --scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup

Die Ausgabe für einen Dienstprinzipal mit Kennwortauthentifizierung enthält den Schlüssel password. Denken Sie unbedingt daran, diesen Wert zu kopieren – er kann nicht abgerufen werden. Wenn Sie das Kennwort verlieren, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.

Zertifikatbasierte Authentifizierung

Verwenden Sie für die zertifikatbasierte Authentifizierung den Parameter --cert. Bei Verwendung dieses Parameters muss bereits ein Zertifikat vorhanden sein. Vergewissern Sie sich, dass alle Tools, die diesen Dienstprinzipal verwenden, Zugriff auf den privaten Schlüssel des Zertifikats haben. Zertifikate müssen in einem ASCII-Format vorliegen, etwa PEM, CER oder DER. Übergeben Sie das Zertifikat als Zeichenfolge, oder verwenden Sie das Format @path, um das Zertifikat aus einer Datei zu laden.

Hinweis

Bei Verwendung einer PEM-Datei muss das Zertifikat (CERTIFICATE) an den privaten Schlüssel (PRIVATE KEY) in der Datei angefügt werden.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert @/path/to/cert.pem

Der Parameter --keyvault kann hinzugefügt werden, um ein Zertifikat in Azure Key Vault zu verwenden. In diesem Fall ist der Wert --cert der Name des Zertifikats.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert certificateName \
                         --keyvault vaultName

Verwenden Sie den Parameter --create-cert, um ein selbstsigniertes Zertifikat für die Authentifizierung zu erstellen:

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --create-cert

Konsolenausgabe:

Creating a role assignment under the scopes 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 parameter
{
  "appId": "myAppId",
  "displayName": "myDisplayName",
  "fileWithCertAndPrivateKey": "C:\\myPath\\myNewFile.pem",
  "name": "http://myName",
  "password": null,
  "tenant": "myTenantId"
}

Inhalt der neuen PEM-Datei:

-----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. Die PEM-Datei enthält einen ordnungsgemäß formatierten privaten Schlüssel (PRIVATE KEY) und ein ordnungsgemäß formatiertes Zertifikat (CERTIFICATE).

Der Parameter --keyvault kann hinzugefügt werden, um das Zertifikat in Azure Key Vault zu speichern. Bei der Verwendung von --keyvault ist der Parameter --certerforderlich.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --create-cert \
                         --cert certificateName \
                         --keyvault vaultName

Die Ausgabe enthält den Schlüssel fileWithCertAndPrivateKey, es sei denn, Sie speichern das Zertifikat in Key Vault. Am Wert dieses Schlüssels können Sie erkennen, wo das generierte Zertifikat gespeichert ist. Kopieren Sie das Zertifikat unbedingt an einen sicheren Speicherort. Andernfalls können Sie sich nicht mit diesem Dienstprinzipal anmelden.

Wenn Sie keinen Zugriff mehr auf den privaten Schlüssel des Zertifikats haben, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.

Abrufen eines Zertifikats aus Key Vault

Rufen Sie für das in Key Vault gespeicherte Zertifikat das Zertifikat mit seinem privaten Schlüssel mit az keyvault secret show ab, und konvertieren Sie es in eine PEM-Datei. In Key Vault ist der Name des Zertifikatgeheimnisses mit dem Zertifikatnamen identisch.

az keyvault secret download --file /path/to/cert.pfx --vault-name VaultName --name CertName --encoding base64
openssl pkcs12 -in cert.pfx -passin pass: -out cert.pem -nodes

Konvertieren einer vorhandenen PKCS12-Datei

Wenn Sie bereits über eine PKCS#12-Datei verfügen, können Sie diese mithilfe von OpenSSL in das PEM-Format konvertieren. Wenn Sie über ein Kennwort verfügen, ändern Sie das passin-Argument.

openssl pkcs12 -in fileName.p12 -clcerts -nodes -out fileName.pem -passin pass:

2. Abrufen eines vorhandenen Dienstprinzipals

Mit az ad sp list kann eine Liste der Dienstprinzipale in einem Mandanten abgerufen werden. Dieser Befehl gibt standardmäßig die ersten 100 Dienstprinzipale für Ihren Mandanten zurück. Verwenden Sie zum Abrufen aller Dienstprinzipale eines Mandanten den Parameter --all. Da das Abrufen dieser Liste sehr lange dauern kann, wird empfohlen, die Liste mit einem der folgenden Parameter zu filtern:

  • --display-name fordert Dienstprinzipale mit einem Präfix an, das dem angegebenen Namen entspricht. Der Anzeigename eines Dienstprinzipals ist der Wert, der während der Erstellung mit dem Parameter --name festgelegt wird. Haben Sie --name während der Erstellung des Dienstprinzipals nicht festgelegt, lautet das Namenspräfix azure-cli-.
  • --spn filtert nach genauen Übereinstimmungen des Dienstprinzipalnamens. Der Dienstprinzipalname beginnt immer mit 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.
  • --show-mine fordert nur Dienstprinzipale an, die vom angemeldeten Benutzer erstellt wurden.
  • --filter akzeptiert einen OData-Filter und führt die serverseitige Filterung aus. Diese Methode wird anstelle der clientseitigen Filterung mit dem Parameter --query der CLI empfohlen. Weitere Informationen zu OData-Filtern finden Sie unter OData-Ausdruckssyntax für Filter und Sortierklauseln in Azure Search.

Für Dienstprinzipalobjekte werden ausführliche Informationen zurückgegeben. Verwenden Sie die Abfragezeichenfolge [].{id:appId, tenant:appOwnerTenantId}, um nur die für die Anmeldung erforderlichen Informationen abzurufen. Die Anmeldeinformationen für alle Dienstprinzipale, die vom derzeit angemeldeten Benutzer erstellt wurden, rufen Sie beispielsweise wie folgt ab:

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. Geheimnisse für Zertifikate in Key Vault können mit az keyvault secret show abgerufen werden. Andere Geheimnisse werden jedoch nicht standardmäßig gespeichert. Wenn Sie eine Authentifizierungsmethode oder ein Geheimnis vergessen haben, setzen Sie die Anmeldeinformationen des Dienstprinzipals zurück.

3. Verwalten von Dienstprinzipalrollen

Die Azure CLI enthält die folgenden Befehle zum Verwalten von Rollenzuweisungen:

Die Rolle Mitwirkender verfügt über uneingeschränkte Berechtigungen für Lese- und Schreibvorgänge in einem Azure-Konto. Die Rolle Leser ist stärker eingeschränkt und bietet schreibgeschützten Zugriff. 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:

az role assignment create --assignee appID \
                          --role Reader \
                          --scope /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

az role assignment delete --assignee appID \
                          --role Contributor \
                          --scope /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

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, falls sie zuvor zugewiesen wurde.

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

az role assignment list --assignee appID

4. Anmelden mithilfe eines Dienstprinzipals

Testen Sie die Anmeldeinformationen und Berechtigungen des neuen Dienstprinzipals, indem Sie sich anmelden. Für die Anmeldung mit einem Dienstprinzipal benötigen Sie appId, tenant und Anmeldeinformationen.

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

az login --service-principal --username appID --password PASSWORD --tenant tenantID

Um sich mit einem Zertifikat anmelden zu können, muss es lokal als PEM- oder DER-Datei im ASCII-Format verfügbar sein. Bei Verwendung einer PEM-Datei müssen der private Schlüssel (PRIVATE KEY) und das Zertifikat (CERTIFICATE) gemeinsam innerhalb der Datei angefügt werden.

az login --service-principal --username appID --tenant tenantID --password /path/to/cert

Weitere Informationen zum Anmelden mit einem Dienstprinzipal finden Sie unter Anmelden mit der Azure CLI.

5. Erstellen einer Ressource mithilfe des Dienstprinzipals

Der folgende Abschnitt enthält ein Beispiel für die Erstellung einer Ressource für Azure Storage mit einem Dienstprinzipal. Dazu werden die folgenden Befehle verwendet:

Für die Anmeldung mit einem Dienstprinzipal benötigen Sie die Werte für appID, tenantID und password, die beim Erstellen des Dienstprinzipals als Antwort zurückgegeben wurden.

  1. Melden Sie sich als Dienstprinzipal an:

    az login --service-principal --username appID --password PASSWORD --tenant tenantID

  2. Erstellen Sie eine Ressourcengruppe für alle Ressourcen, die für den gleichen Schnellstart, das gleiche Tutorial oder das gleiche Entwicklungsprojekt verwendet werden.

    az group create --location westus --name myResourceGroupName

  3. Erstellen Sie ein Speicherkonto.

    Für Azure Storage sind folgende Werte für den Parameter <KIND> zulässig:

    • BlobStorage
    • BlockBlobStorage
    • FileStorage
    • Storage
    • StorageV2
    az storage account create --name myStorageAccountName --resource-group myResourceGroupName --kind <KIND> --sku F0 --location westus --yes

  4. Rufen Sie Ressourcenschlüssel ab, die Sie in Ihrem Code für die Authentifizierung beim Azure-Speicherkonto verwenden:

    az storage account keys list --name myStorageAccountName --resource-group myResourceGroupName

6. Zurücksetzen von Anmeldeinformationen

Wenn Sie die Anmeldeinformationen für einen Dienstprinzipal verloren haben, verwenden Sie az ad sp credential reset. Der Befehl zum Zurücksetzen akzeptiert die gleichen Parameter wie az ad sp create-for-rbac.

az ad sp credential reset --name myServicePrincipal_appID_or_name

7. Problembehandlung

Keine ausreichenden Berechtigungen

Wenn Ihr Konto nicht über die Berechtigung 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. Wenden Sie sich an Ihre*n Azure Active Directory-Administrator*in, um einen Dienstprinzipal zu erstellen.

Ungültiger Mandant

Wenn Sie eine ungültige Abonnement-ID angegeben haben, wird die Fehlermeldung „Die Anforderung umfasste weder ein Abonnement noch einen gültigen Ressourcenanbieter auf Mandantenebene.“ angezeigt. Verwenden Sie bei Verwendung von Variablen den Bash-Befehl echo, um den Wert anzuzeigen, der an den Verweisbefehl übergeben wird. Verwenden Sie az account set, um Ihr Abonnement zu ändern, oder informieren Sie sich über das Verwalten von Azure-Abonnements mit der Azure CLI.

Ressourcengruppe nicht gefunden

Wenn Sie einen ungültigen Ressourcengruppennamen angegeben haben, wird die Fehlermeldung „Ressourcengruppe "Name" konnte nicht gefunden werden.“ angezeigt. Verwenden Sie bei Verwendung von Variablen den Bash-Befehl echo, um den Wert anzuzeigen, der an die Abonnement- und die Verweisbefehle übergeben wird. Verwenden Sie az group list, um die Ressourcengruppen für das aktuelle Abonnement anzuzeigen, oder informieren Sie sich über das Verwalten von Azure-Ressourcengruppen mit der Azure CLI.

Autorisierung zum Ausführen von Aktionen

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.

Weitere Informationen