Aufrufen einer API in einer Node.js-Daemon-Beispielanwendung

  • Artikel

In diesem Leitfaden wird anhand einer Node.js-Daemon-Beispielanwendung veranschaulicht, wie eine Daemon-App ein Token zum Aufrufen einer 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.

Eine Daemon-App verwendet die Standardzuweisung für Clientanmeldeinformationen von OAuth 2.0. Zum Vereinfachen des Vorgangs des Tokenabrufs nutzt das in diesem Artikel verwendete Beispiel die Microsoft Authentication Library for Node (MSAL Node).

Voraussetzungen

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 App-Rollen

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

Von der Microsoft-Identität zurückgegebene Token werden kleiner gehalten, um eine optimale Leistung von Clients zu gewährleisten, die sie anfordern. Daher sind einige Ansprüche nicht mehr standardmäßig im Token vorhanden und müssen für einzelne Anwendungen speziell angefordert werden. Fügen Sie für diese App 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.

Führen Sie die folgenden Schritte aus, um den optionalen Anspruch idtyp zu konfigurieren:

  1. Wählen Sie auf der Seite App-Registrierungen den zu konfigurierenden optionalen Anspruch aus, z. B. ciam-client-app, um die entsprechende Seite Übersicht zu öffnen.

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

  3. Wählen Sie Optionalen Anspruch hinzufügen aus.

  4. Wählen Sie unter Tokentyp die Option Zugriff aus.

  5. Wählen Sie den optionalen Anspruch idtyp aus.

  6. Klicken Sie auf Hinzufügen, um die Änderungen zu speichern.

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, da sich die Anwendung als sie selbst anmeldet, nicht als Benutzer.

  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-javascript-tutorial.git

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

Installieren von Projektabhängigkeiten

  1. Öffnen Sie ein Konsolenfenster, und wechseln Sie in das Verzeichnis, das die Node.js-Beispiel-App enthält:

    cd 2-Authorization\3-call-api-node-daemon\App

  2. Führen Sie die folgenden Befehle aus, um App-Abhängigkeiten zu installieren:

    npm install && npm update

Konfigurieren der Daemon-Beispielanwendung und -API

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

  1. Öffnen Sie die App\authConfig.js-Datei in Ihrem Code-Editor.

  2. Suchen Sie den folgenden Platzhalter:

    • Enter_the_Application_Id_Here, und ersetzen Sie ihn 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 App-Geheimnisses, 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 registrierten Anwendung.

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

  1. Öffnen Sie die API\ToDoListAPI\appsettings.json-Datei in Ihrem Code-Editor.

  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 Daemon-Beispiel-App 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-api-node-daemon\API\ToDoListAPI
dotnet run

  2. Führen Sie den Web-App-Client mit den folgenden Befehlen aus:

    2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

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

    {
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Funktionsweise

Die Node.js-App verwendet die OAuth 2.0-Zuweisung für Clientanmeldeinformationen, um ein Zugriffstoken für sich selbst und nicht für den Benutzer 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.

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

Zugriff auf Daten

Ein Web-API-Endpunkt sollte bereit sein, Aufrufe von Benutzern und Anwendungen zu akzeptieren. Daher sollte er eine Möglichkeit haben, auf jede Anforderung entsprechend zu reagieren. Beispielsweise empfängt ein Aufruf eines Benutzers über delegierte Berechtigungen/Bereiche die Aufgabenliste des Benutzers. Andererseits kann ein Aufruf einer Anwendung über Anwendungsberechtigungen/-rollen die gesamte Aufgabenliste empfangen. In diesem Artikel führen wir jedoch nur einen Anwendungsaufruf aus, sodass wir keine delegierten Berechtigungen/Bereiche konfigurieren mussten.

Zugehöriger Inhalt