Aufrufen einer API in einer .NET-Daemonbeispielanwendung

In diesem Leitfaden wird anhand einer .NET-Daemonbeispielanwendung veranschaulicht, wie eine Daemonanwendung ein Token zum Aufrufen einer geschützten Web-API abruft. Microsoft Entra schützt die Web-API.

Eine Daemonanwendung ruft ein Token im eigenen Namen auf (nicht im Namen eines Benutzers). Eine Interaktion von Benutzern mit einer Daemonanwendung ist nicht möglich, da die Daemonanwendung eine eigene Identität benötigt. Diese Art von Anwendung fordert auf der Grundlage ihrer Anwendungsidentität ein Zugriffstoken an und gibt dabei gegenüber Microsoft Entra External ID ihre Anwendungs-ID, ihre Anmeldeinformationen (Kennwort oder Zertifikat) sowie ihren Anwendungs-ID-URI an.

Voraussetzungen

• Visual Studio Code oder ein anderer Code-Editor
• .NET 7.0 oder höher.

• Ein externer Mandant. Um einen zu erstellen, können Sie eine der folgenden Methoden verwenden:
  • (Empfohlen) Verwenden Sie die Externe ID-Erweiterung von Microsoft Entra, um einen externen Mandanten direkt in Visual Studio Code einzurichten.
  • Erstellen Sie einen neuen externen Mandanten im Microsoft Entra Admin Center.

Registrieren einer Daemonanwendung und einer Web-API

In diesem Schritt erstellen Sie die Registrierungen der Daemon- und Web-API-Anwendung und geben die Bereiche Ihrer Web-API an.

Registrieren einer Web-API-Anwendung

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler an.

2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Einstellungen-Symbol im oberen Menü, um über das Menü Verzeichnisse + Abonnements zu Ihrem externen Mandanten zu wechseln.

3. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

4. Wählen Sie + Neue Registrierung aus.

5. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen Ihrer Anwendung ein:

   1. Geben Sie im Abschnitt „Name“ einen aussagekräftigen Anwendungsnamen ein, der den Benutzerinnen bzw. Benutzern der Anwendung angezeigt werden soll (beispielsweise ciam-client-app).

   2. Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

6. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

7. Der Bereich Übersicht der Anwendung wird angezeigt, wenn die Registrierung abgeschlossen ist. Notieren Sie sich die Verzeichnis-ID (Mandant) und die Anwendungs-ID (Client), die im Quellcode Ihrer Anwendung verwendet werden sollen.

Konfigurieren von Anwendungsrollen

Eine API muss mindestens eine Anwendungsrolle für Anwendungen veröffentlichen, die auch als Anwendungsberechtigung bezeichnet wird, damit die Clientanwendungen selbst ein Zugriffstoken erhalten können. Anwendungsberechtigungen sind der Typ von Berechtigungen, die APIs veröffentlichen sollten, wenn sie Clientanwendungen eine erfolgreiche Authentifizierung als sie selbst ermöglichen wollen und keine Benutzerinnen bzw. Benutzer anmelden müssen. Befolgen Sie die folgenden Schritte, um eine Anwendungsberechtigung zu veröffentlichen:

1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-ToDoList-api) aus, um ihre Seite Übersicht zu öffnen.

2. Wählen Sie unter Verwalten die Option Anwendungsrollen aus.

3. Wählen Sie App-Rolle erstellen aus, und geben Sie die folgenden Werte ein. Wählen Sie dann Anwenden aus, um Ihre Änderungen zu speichern:

   Eigenschaft	Wert
   `Display name`	ToDoList.Read.All
   Zulässige Mitgliedstypen	Anwendungen
   Wert	ToDoList.Read.All
   BESCHREIBUNG	Geben Sie der App Lesezugriff auf die ToDo-Liste aller Benutzer*innen mithilfe von „ToDoListApi“.

4. Wählen Sie erneut App-Rolle erstellen aus, und geben Sie die folgenden Werte für die zweite App-Rolle ein. Wählen Sie dann Anwenden aus, um Ihre Änderungen zu speichern:

   Eigenschaft	Wert
   `Display name`	ToDoList.ReadWrite.All
   Zulässige Mitgliedstypen	Anwendungen
   Wert	ToDoList.ReadWrite.All
   BESCHREIBUNG	Geben Sie der App Lese- und Schreibzugriff auf die ToDo-Liste eines jeden Benutzers mit Hilfe der „ToDoListApi“.

Konfigurieren optionaler Ansprüche

Fügen Sie den optionalen Anspruch idtyp ein, damit die Web-API besser ermitteln kann, ob ein Token ein App-Token oder ein App- und Benutzertoken ist. Für den gleichen Zweck kann zwar auch eine Kombination aus Ansprüchen vom Typ scp und roles verwendet werden, die Verwendung des Anspruchs idtyp ist jedoch die einfachste Möglichkeit, um App-Token von App- und Benutzertoken zu unterscheiden. Der Wert dieses Anspruchs ist beispielsweise app, wenn das Token ein reines App-Token ist.

Registrieren der Daemonanwendung

Damit Ihre Anwendung Benutzer mit Microsoft Entra anmelden kann, muss Microsoft Entra External ID auf die von Ihnen erstellte Anwendung aufmerksam gemacht werden. Durch die App-Registrierung wird eine Vertrauensstellung zwischen der Anwendung und Microsoft Entra eingerichtet. Wenn Sie eine Anwendung registrieren, generiert External ID einen eindeutigen Bezeichner, die Anwendungs-ID (Client). Dieser Wert wird zum Identifizieren Ihrer Anwendung beim Erstellen von Authentifizierungsanforderungen verwendet.

Die folgenden Schritte veranschaulichen, wie Sie Ihre Anwendung im Microsoft Entra Admin Center registrieren:

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler an.

2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Einstellungen-Symbol im oberen Menü, um über das Menü Verzeichnisse + Abonnements zu Ihrem externen Mandanten zu wechseln.

3. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

4. Wählen Sie + Neue Registrierung aus.

5. Auf der Seite Anwendung registrieren die angezeigt wird.

   1. Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der Anwendung angezeigt wird (z. B. ciam-client-app).
   2. Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

6. Wählen Sie Registrieren.

7. Der Bereich Übersicht der Anwendung wird bei erfolgreicher Registrierung angezeigt. Notieren Sie sich die Anwendungs-ID (Client), die im Quellcode Ihrer Anwendung verwendet werden sollen.

Erstellen eines Clientgeheimnisses

Erstellen Sie einen geheimen Clientschlüssel für die registrierte Anwendung. Die Anwendung verwendet den geheimen Clientschlüssel beim Anfordern von Token als Identitätsnachweis.

1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-client-app) aus, um ihre Seite Übersicht zu öffnen.
2. Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.
3. Wählen Sie Neuer geheimer Clientschlüssel.
4. Geben Sie im Feld Beschreibung eine Beschreibung für das Clientgeheimnis ein (z. B. Ciam-App-Clientgeheimnis).
5. Wählen Sie unter Gültig bis einen Gültigkeitszeitraum für den geheimen Schlüssel (gemäß den jeweiligen Sicherheitsregeln Ihrer Organisation) und dann Hinzufügen aus.
6. Notieren Sie den Wert des Geheimnisses. Dieser Wert wird in einem späteren Schritt für die Konfiguration verwendet. Der Wert des Geheimnisses wird nicht noch mal angezeigt und kann nicht anderweitig abgerufen werden, nachdem Sie die Seite Zertifikate & Geheimnisse verlassen haben. Notieren Sie sich diesen daher unbedingt.

Erteilen von API-Berechtigungen für die Daemonanwendung

1. Wählen Sie auf der Seite Anwendungsregistrierungen die von Ihnen erstellte Anwendung (z. B. ciam-client-app) aus.

2. Wählen Sie unter Verwalten die Option API-Berechtigungen.

3. Wählen Sie unter Konfigurierte Berechtigungen die Option Berechtigung hinzufügen aus.

4. Wählen Sie die Registerkarte Von meiner Organisation verwendete APIs aus.

5. Wählen Sie in der Liste der APIs die API aus, z. B. ciam-ToDoList-api.

6. Wählen Sie die Option Anwendungsberechtigungen aus. Wir wählen diese Option aus, weil sich die App nicht im Namen eines Benutzers oder einer Benutzerin, sondern selbst anmeldet.

7. Wählen Sie in der Berechtigungsliste TodoList.Read.All, ToDoList.ReadWrite.All aus (verwenden Sie bei Bedarf das Suchfeld).

8. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.

9. An diesem Punkt haben Sie die Berechtigungen ordnungsgemäß zugewiesen. Da die Daemon-App jedoch keine Interaktion mit Benutzerinnen oder Benutzern zulässt, können die Benutzerinnen und Benutzer selbst diesen Berechtigungen nicht zustimmen. Um dieses Problem zu beheben, müssen Sie als Administrator im Namen aller Benutzer im Mandanten diesen Berechtigungen zustimmen:

   1. Wählen Sie Administratorzustimmung für <Name Ihres Mandanten> erteilen und dann Ja aus.
   2. Wählen Sie Aktualisieren aus, und vergewissern Sie sich, dass für beide Berechtigungen unter Status der Status Erteilt für <Name Ihres Mandanten> angezeigt wird.

Klonen oder Herunterladen einer Daemon-Beispielanwendung und Web-API

Um die Beispielanwendung zu erhalten, können Sie sie entweder von GitHub klonen oder als ZIP-Datei herunterladen.

• Öffnen Sie zum Klonen des Beispiels eine Eingabeaufforderung, navigieren Sie zu der Stelle, an der Sie das Projekt erstellen möchten, und geben Sie den folgenden Befehl ein:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
  

• ZIP-Datei herunterladen. Extrahieren Sie sie an einem Dateipfad, dessen Name weniger als 260 Zeichen umfasst.

Konfigurieren der Daemonbeispielanwendung und -API

So verwenden Sie Ihre App-Registrierung im Beispiel für die Clientwebanwendung

1. Öffnen Sie im Code-Editor die Datei ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json.

2. Suchen Sie den folgenden Platzhalter:

   • Enter_the_Application_Id_Here, und ersetzen Sie sie durch die Anwendungs-ID (Client-ID) der zuvor von Ihnen registrierten Daemonanwendung.
   • Enter_the_Tenant_Subdomain_Here, und ersetzen Sie ihn durch die Unterdomäne des Verzeichnisses (des Mandanten). Wenn Ihre primäre Mandantendomäne beispielsweise contoso.onmicrosoft.com lautet, verwenden Sie contoso. Wenn Sie ihren Mandantennamen nicht kennen, können Sie Ihre Mandantendetails auslesen.
   • Enter_the_Client_Secret_Here, und ersetzen Sie ihn durch den Wert des Daemonanwendungsgeheimnisses, das Sie zuvor kopiert haben.
   • Enter_the_Web_Api_Application_Id_Here, und ersetzen Sie ihn durch die Anwendungs-ID (Client-ID) der zuvor von Ihnen kopierten Web-API.

So verwenden Sie Ihre App-Registrierung im Web-API-Beispiel:

1. Öffnen Sie im Code-Editor die Datei ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI/appsettings.json.

2. Suchen Sie den folgenden Platzhalter:

   • Enter_the_Application_Id_Here, und ersetzen Sie ihn durch die Anwendungs-ID (Client-ID) der von Ihnen kopierten Web-API.
   • Enter_the_Tenant_Id_Here, und ersetzen Sie ihn durch die Verzeichnis-ID (Mandanten-ID), die Sie zuvor kopiert haben.
   • Enter_the_Tenant_Subdomain_Here, und ersetzen Sie ihn durch die Unterdomäne des Verzeichnisses (des Mandanten). Wenn Ihre primäre Mandantendomäne beispielsweise contoso.onmicrosoft.com lautet, verwenden Sie contoso. Wenn Sie ihren Mandantennamen nicht kennen, können Sie Ihre Mandantendetails auslesen.

Ausführen und Testen der Daemonbeispielanwendung und -API

1. Öffnen Sie ein Konsolenfenster, und führen Sie dann mit den folgenden Befehlen die Web-API aus:

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListAPI
   dotnet run
   

2. Führen Sie den Daemonclient mit den folgenden Befehlen aus:

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
   dotnet run
   

Wenn Ihre Daemonanwendung und Ihre Web-API erfolgreich ausgeführt werden, sollte in Ihrem Konsolenfenster etwas Ähnliches wie das folgende JSON-Array angezeigt werden:

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Funktionsweise

Die Daemonanwendung verwendet die OAuth 2.0-Zuweisung für Clientanmeldeinformationen, um ein Zugriffstoken für sich selbst und nicht für den Benutzer bzw. die Benutzerin abzurufen. Das Zugriffstoken, das die App anfordert, enthält die Berechtigungen, die als Rollen dargestellt werden. Der Flow für Clientanmeldeinformationen verwendet diese Gruppe von Berechtigungen anstelle von Benutzerbereichen für Anwendungstoken. Sie haben diese Anwendungsberechtigungen zuvor in der Web-API verfügbar gemacht und sie dann der Daemon-App erteilt. Die Daemon-App in diesem Artikel verwendet die Microsoft-Authentifizierungsbibliothek für .NET, um den Prozess zum Abrufen eines Tokens zu vereinfachen.

Auf der API-Seite muss die Web-API überprüfen, ob das Zugriffstoken über die erforderlichen Berechtigungen (Anwendungsberechtigungen) verfügt. Die Web-API lehnt Zugriffstoken ab, die nicht über die erforderlichen Berechtigungen verfügen.

Zugehöriger Inhalt

• Verwenden Sie unsere mehrteilige Tutorialreihe, um diese .NET-Daemon-App von Grund auf neu zu erstellen.
• Aktivieren der Kennwortzurücksetzung.
• Anpassen des Standardbrandings
• Konfigurieren der Anmeldung mit Google.