Authentifizieren bei Azure-Ressourcen von lokal gehosteten .NET-Apps

Apps, die außerhalb von Azure (z. B. lokal oder in einem Rechenzentrum eines Drittanbieters) gehostet werden, sollten einen Anwendungsdienstprinzipal verwenden, um sich beim Zugriff auf Azure-Ressourcen bei Azure zu authentifizieren. Anwendungsdienstprinzipalobjekte werden mithilfe des App-Registrierungsprozesses in Azure erstellt. Wenn ein Anwendungsdienstprinzipal erstellt wird, werden eine Client-ID und ein geheimer Clientschlüssel für Ihre App generiert. Die Client-ID, der geheime Clientschlüssel und Ihre Mandanten-ID werden dann in Umgebungsvariablen gespeichert, sodass sie von der Azure Identity-Bibliothek verwendet werden können, um Ihre App zur Laufzeit bei Azure zu authentifizieren.

Für jede Umgebung, in der die App gehostet wird, sollte eine andere App-Registrierung erstellt werden. Dadurch können umgebungsspezifische Ressourcenberechtigungen für jeden Dienstprinzipal konfiguriert und sichergestellt werden, dass eine in einer Umgebung bereitgestellte App nicht mit Azure-Ressourcen kommuniziert, die Teil einer anderen Umgebung sind.

1 - Registrieren der Anwendung in Azure AD

Eine App kann entweder mit dem Azure-Portal oder der Azure CLI bei Azure registriert werden.

Azure portal

Melden Sie sich beim Azure-Portal an, und führen Sie die folgenden Schritte aus.

Anweisungen	Screenshot
Im Azure-Portal: Geben Sie auf der Suchleiste oben im Azure-Portal App Registrierungen ein. Wählen Sie im Menü, das unter der Suchleiste angezeigt wird, unter der Rubrik Dienste die Option App Registrierungen aus.
Wählen Sie auf der Seite „App-Registrierungen“ die Option + Neue Registrierung aus.
Füllen Sie auf der Seite Registrieren einer Anwendung das Formular wie folgt aus: Name → Geben Sie einen Namen für die App-Registrierung in Azure ein. Es wird empfohlen, dass dieser Name den App-Namen und die Umgebung (Test, Produktion) enthält, für die die App-Registrierung vorgesehen ist. Unterstützte Kontotypen → Nur Konten in diesem Organisationsverzeichnis. Wählen Sie Registrieren aus, um Ihre App zu registrieren und den Anwendungsdienstprinzipal zu erstellen.
Auf der App-Registrierungsseite für Ihre App: Anwendungs-ID (Client) → Dies ist die App-ID, die die App während der lokalen Entwicklung für den Zugriff auf Azure verwendet. Kopieren Sie diesen Wert an einen temporären Speicherort in einem Text-Editor, da Sie ihn in einem zukünftigen Schritt benötigen. Verzeichnis-ID (Mandanten-ID) → Dieser Wert wird auch von Ihrer App benötigt, wenn sie sich bei Azure authentifiziert. Kopieren Sie diesen Wert an einen temporären Speicherort in einem Text-Editor, da Sie ihn in einem zukünftigen Schritt benötigen. Clientanmeldeinformationen → Sie müssen die Clientanmeldeinformationen für die App festlegen, bevor Ihre App sich bei Azure authentifizieren und Azure-Dienste verwenden kann. Wählen Sie Zertifikat oder Geheimnis hinzufügen aus, um Anmeldeinformationen für Ihre App hinzuzufügen.
Wählen Sie auf der Seite Zertifikate und Geheimnisse die Option + Neuer geheimer Clientschlüssel aus.
Das Dialogfeld Geheimer Clientschlüssel hinzufügen wird auf der rechten Seite der Seite angezeigt. In diesem Dialog: Beschreibung → Geben Sie den Wert Current ein. Läuft aus→ Wählen Sie einen Wert von 24 Monaten aus. Wählen Sie Hinzufügen aus, um das Geheimnis hinzuzufügen. WICHTIG: Legen Sie eine Erinnerung in Ihrem Kalender vor dem Ablaufdatum des Geheimnisses fest. Auf diese Weise können Sie vor Ablauf dieses Geheimnisses ein neues Geheimnis hinzufügen und Ihre Apps aktualisieren und eine Dienstunterbrechung in Ihrer App vermeiden.
Auf der Seite Zertifikate und geheime Schlüssel wird Ihnen der Wert des geheimen Clientschlüssels angezeigt. Kopieren Sie diesen Wert an einen temporären Speicherort in einem Text-Editor, da Sie ihn in einem zukünftigen Schritt benötigen. WICHTIG: Dieser Wert wird nur dieses eine Mal angezeigt. Sobald Sie diese Seite verlassen oder aktualisieren, können Sie diesen Wert nicht mehr anzeigen. Sie können einen zusätzlichen geheimen Clientschlüssel hinzufügen, ohne diesen geheimen Clientschlüssel für ungültig zu erklären. Dieser Wert wird jedoch nicht mehr angezeigt.

Azure-Befehlszeilenschnittstelle

az ad sp create-for-rbac --name <app-name>

Der Befehl gibt eine Ausgabe ähnlich der folgenden zurück: Notieren Sie sich diese Werte, oder lassen Sie dieses Fenster geöffnet, da Sie diese Werte im nächsten Schritt benötigen und den Wert des Kennworts (geheimer Clientschlüssel) nicht mehr anzeigen können.

{
  "appId": "00000000-1111-2222-3333-444444444444",
  "displayName": "msdocs-dotnet-sdk-auth-prod",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "00000000-0000-0000-0000-000000000000"
}

2: Zuweisen von Rollen zum Anwendungsdienstprinzipal

Als Nächstes müssen Sie bestimmen, welche Rollen (Berechtigungen) Ihre App für welche Ressourcen benötigt, und diese Rollen Ihrer App zuweisen. Rollen können in einem Ressourcen-, Ressourcengruppen- oder Abonnementbereich eine Rolle zugewiesen werden. In diesem Beispiel wird gezeigt, wie Sie Rollen für den Dienstprinzipal im Bereich der Ressourcengruppe zuweisen, da die meisten Apps alle ihre Azure-Ressourcen in einer einzigen Ressourcengruppe zusammenfassen.

Azure portal

Anweisungen	Screenshot
Suchen Sie die Ressourcengruppe für Ihre App, indem Sie über das Suchfeld oben im Azure-Portal nach dem Namen der Ressourcengruppe suchen. Navigieren Sie zu Ihrer Ressourcengruppe, indem Sie den Namen der Ressourcengruppe unter der Überschrift Ressourcengruppen im Dialogfeld auswählen.
Wählen Sie auf der Seite für die Ressourcengruppe im linken Menü Die Option Zugriffssteuerung (IAM) aus.
Klicken Sie auf der Seite Zugriffssteuerungseinstellungen: Klicken Sie auf die Registerkarte Rollenzuweisungen. Wählen Sie im oberen Menü + Hinzufügen und aus dem dann angezeigten Dropdownmenü die Option Rollenzuweisung hinzufügen aus.
Auf der Seite Rollenzuweisung hinzufügen werden alle Rollen aufgelistet, die der Ressourcengruppe zugewiesen werden können. Verwenden Sie das Suchfeld, um die Liste auf eine besser verwaltbare Größe zu filtern. In diesem Beispiel wird gezeigt, wie Sie nach Storage-Blobrollen filtern. Wählen Sie die Rolle aus, die Sie zuweisen möchten. Klicken Sie auf Weiter, um zum nächsten Bildschirm zu wechseln.
Auf der nächsten Seite Rollenzuweisung hinzufügen können Sie angeben, welchem Benutzer die Rolle zugewiesen werden soll. Wählen Sie unter Zugriff zuweisendie Option Benutzer, Gruppe oder Dienstprinzipal aus. Wählen Sie unter Mitglieder die Option + Mitglieder auswählen aus. Auf der rechten Seite des Azure-Portal wird ein Dialogfeld geöffnet.
Im Dialogfeld Mitglieder auswählen : Das Textfeld Auswählen kann verwendet werden, um die Liste der Benutzer und Gruppen in Ihrem Abonnement zu filtern. Geben Sie bei Bedarf die ersten Zeichen des Dienstprinzipals ein, den Sie für die App erstellt haben, um die Liste zu filtern. Wählen Sie den Dienstprinzipal aus, der Ihrer Anwendung zugeordnet ist. Wählen Sie unten im Dialogfeld Auswählen aus, um den Vorgang fortzusetzen.
Der Hauptdienst wird nun auf dem Bildschirm Rollenzuweisung hinzufügen als ausgewählt angezeigt. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Azure-Befehlszeilenschnittstelle

Einem Anwendungsdienstprinzipal wird mithilfe des Befehls az role assignment create eine Rolle in Azure zugewiesen:

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

Verwenden Sie den Befehl az role definition list, um die Rollennamen abzurufen, denen ein Dienstprinzipal zugewiesen werden kann.

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

Wenn Sie beispielsweise dem Dienstprinzipal mit der App-ID (appId) 00000000-0000-0000-0000-000000000000 Lese-, Schreib- und Löschzugriff auf Azure Storage-Blobcontainer und -Daten für alle Speicherkonten in der Ressourcengruppe msdocs-dotnet-sdk-auth-example ermöglichen möchten, weisen Sie den Anwendungsdienstprinzipal der Rolle Mitwirkender an Storage-Blobdaten zu. Verwenden Sie dazu den folgenden Befehl:

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-sdk-auth-example"

Informationen zum Zuweisen von Berechtigungen auf Ressourcen- oder Abonnementebene mithilfe der Azure CLI finden Sie unter Zuweisen von Azure-Rollen mithilfe der Azure CLI.

3. Konfigurieren von Umgebungsvariablen für die Anwendung

Das DefaultAzureCredential-Objekt sucht zur Laufzeit in einer Reihe von Umgebungsvariablen nach den Zugangsdaten für den Dienst. Es gibt mehrere Möglichkeiten, Umgebungsvariablen zu konfigurieren, wenn Sie mit .NET arbeiten, abhängig von Ihren Tools und Ihrer Umgebung.

Unabhängig davon, für welchen Ansatz Sie sich entscheiden, konfigurieren Sie die folgenden Umgebungsvariablen, wenn Sie mit einem Dienstprinzipal arbeiten:

• AZURE_CLIENT_ID → Der App-ID-Wert.
• AZURE_TENANT_ID → Der Wert der Mandanten-ID.
• AZURE_CLIENT_SECRET → Das für die App generierte Kennwort/Anmeldeinformationen.

IIS

Wenn Ihre App in IIS gehostet wird, wird empfohlen, Umgebungsvariablen pro App-Pool festzulegen, um Einstellungen zwischen Apps zu isolieren.

appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='ASPNETCORE_ENVIRONMENT',value='Production']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_ID',value='00000000-0000-0000-0000-000000000000']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_TENANT_ID',value='11111111-1111-1111-1111-111111111111']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_SECRET',value='=abcdefghijklmnopqrstuvwxyz']" /commit:apphost

Sie können diese Einstellungen auch direkt mithilfe des applicationPools-Elements in der applicationHost.config-Datei konfigurieren:

<applicationPools>
   <add name="CorePool" managedRuntimeVersion="v4.0" managedPipelineMode="Classic">
      <environmentVariables>
         <add name="ASPNETCORE_ENVIRONMENT" value="Development" />
         <add name="AZURE_CLIENT_ID" value="00000000-0000-0000-0000-000000000000" />
         <add name="AZURE_TENANT_ID" value="11111111-1111-1111-1111-111111111111" />
         <add name="AZURE_CLIENT_SECRET" value="=abcdefghijklmnopqrstuvwxyz" />
      </environmentVariables>
   </add>
</applicationPools>

Windows

Sie können Umgebungsvariablen für Windows über die Befehlszeile festlegen. Wenn Sie diesen Ansatz verwenden, sind die Werte jedoch für alle Apps zugänglich, die unter diesem Betriebssystem ausgeführt werden. Dies kann Konflikte verursachen, wenn Sie nicht vorsichtig sind. Umgebungsvariablen können auf Benutzer- oder Systemebene festgelegt werden:

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

Sie können auch PowerShell verwenden, um Umgebungsvariablen auf Benutzer- oder Computerebene festzulegen:

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

4. Implementieren von DefaultAzureCredential in Ihrer Anwendung

DefaultAzureCredential ist eine dogmatische, sortierte Sequenz von Mechanismen für die Authentifizierung bei Microsoft Entra. Jeder Authentifizierungsmechanismus ist eine von der TokenCredential-Klasse abgeleitete Klasse, die als Anmeldeinformationen bezeichnet wird. Zur Laufzeit versucht DefaultAzureCredential, sich mit den ersten Anmeldeinformationen zu authentifizieren. Wenn diese Anmeldeinformationen kein Zugriffstoken abrufen, werden die nächsten Anmeldeinformationen in der Sequenz ausprobiert usw., bis erfolgreich ein Zugriffstoken abgerufen wurde. Auf diese Weise kann Ihre App unterschiedliche Anmeldeinformationen in verschiedenen Umgebungen verwenden, ohne umgebungsspezifischen Code zu schreiben.

Die Reihenfolge und die Speicherorte, in denen nach Anmeldeinformationen gesucht wird, DefaultAzureCredential finden Sie unter DefaultAzureCredential.

Fügen Sie zur Verwendung von DefaultAzureCredential das Paket Azure.Identity und optional das Paket Microsoft.Extensions.Azure zu Ihrer Anwendung hinzu:

Befehlszeile

Navigieren Sie in einem Terminal Ihrer Wahl zum Anwendungsprojektverzeichnis, und führen Sie die folgenden Befehle aus:

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

NuGet-Paket-Manager

Klicken Sie in Visual Studio im Fenster Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt, und wählen Sie NuGet-Pakete verwalten aus. Suchen Sie nach Azure.Identity, und installieren Sie das entsprechende Paket. Wiederholen Sie diesen Vorgang für das Paket Microsoft.Extensions.Azure.

Auf Azure-Dienste wird mithilfe spezieller Clientklassen aus den verschiedenen Azure SDK-Clientbibliotheken zugegriffen. Diese Klassen und Ihre eigenen benutzerdefinierten Dienste sollten registriert werden, damit über die Abhängigkeitsinjektion in der gesamten App darauf zugegriffen werden kann. Führen Sie in Program.cs die folgenden Schritte aus, um eine Clientklasse und DefaultAzureCredential zu registrieren:

1. Schließen Sie die Namespaces Azure.Identity und Microsoft.Extensions.Azure über using-Direktiven ein.
2. Registrieren Sie den Azure-Dienstclient mithilfe der entsprechenden Erweiterungsmethode mit dem Präfix Add.
3. Übergeben Sie eine Instanz von DefaultAzureCredential an die UseCredential-Methode.

Zum Beispiel:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Eine Alternative zu UseCredential besteht darin, DefaultAzureCredential direkt zu instanziieren:

using Azure.Identity;

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new DefaultAzureCredential()));

Wenn der vorherige Code auf Ihrer lokalen Entwicklungsarbeitsstation ausgeführt wird, sucht er in den Umgebungsvariablen nach einem Anwendungsdienstprinzipal oder in lokal installierten Entwicklertools (etwa Visual Studio) nach einem Satz von Entwickleranmeldeinformationen. Beide Ansätze können verwendet werden, um die App während der lokalen Entwicklung bei Azure-Ressourcen zu authentifizieren.

Bei der Bereitstellung in Azure kann dieser Code Ihre App auch bei anderen Azure-Ressourcen authentifizieren. DefaultAzureCredential kann Umgebungseinstellungen und Konfigurationen für verwaltete Identitäten abrufen, um sich automatisch bei anderen Diensten zu authentifizieren.