Schnellstart: Abrufen eines Tokens und Aufrufen der Microsoft Graph-API aus einer Node.js-Konsolen-App

  • Artikel

Das Codebeispiel, das in dieser Schnellstartanleitung heruntergeladen und ausgeführt wird, zeigt, wie eine Node.js-Konsolenanwendung unter Verwendung der App-Identität ein Zugriffstoken abrufen kann, um die Microsoft Graph-API aufzurufen und eine Liste mit Benutzern im Verzeichnis anzuzeigen. Das Codebeispiel veranschaulicht, wie ein unbeaufsichtigter Auftrag oder Windows-Dienst mit einer Anwendungsidentität anstelle der Identität eines Benutzers ausgeführt werden kann.

In dieser Schnellstartanleitung wird die Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) für Node.js (MSAL Node) mit der Gewährung von Clientanmeldeinformationen verwendet.

Voraussetzungen

Registrieren und Herunterladen der Beispielanwendung

Führen Sie die folgenden Schritte aus:

Schritt 1: Registrieren der Anwendung

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

Führen Sie die folgenden Schritte aus, um Ihre Anwendung zu registrieren und Ihrer Projektmappe manuell die Registrierungsinformationen Ihrer App hinzuzufügen:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.
  2. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.
  3. Wählen Sie Neue Registrierung aus.
  4. Geben Sie unter Name einen Namen für Ihre Anwendung ein (beispielsweise msal-node-cli). Benutzern Ihrer App wird wahrscheinlich dieser Namen angezeigt. Sie können ihn später ändern.
  5. Wählen Sie Registrieren aus.
  6. Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.
  7. Wählen Sie unter Geheimer Clientschlüssel die Option Neuer geheimer Clientschlüssel aus, geben Sie einen Namen ein, und wählen Sie dann Hinzufügen aus. Notieren Sie den Wert für den geheimen Schlüssel an einem sicheren Ort, damit Sie ihn in einem späteren Schritt verwenden können.
  8. Wählen Sie unter Verwalten die Optionen API-Berechtigungen>Berechtigung hinzufügen aus. Wählen Sie Microsoft Graph.
  9. Wählen Sie Anwendungsberechtigungen.
  10. Wählen Sie unter dem Knoten Benutzer die Option User.Read.All und dann Berechtigungen hinzufügen aus.

Schritt 2: Herunterladen des Node.js-Beispielprojekts

Laden Sie das Codebeispiel herunter.

Schritt 3: Konfigurieren des Node.js-Beispielprojekts

  1. Extrahieren Sie die ZIP-Datei in einem lokalen Ordner in der Nähe des Datenträger-Stammverzeichnisses (beispielsweise unter C:\Azure-Samples).

  2. Bearbeiten Sie .env, und ersetzen Sie die Felder TENANT_ID, CLIENT_ID und CLIENT_SECRET durch den folgenden Ausschnitt:

    "TENANT_ID": "Enter_the_Tenant_Id_Here",
"CLIENT_ID": "Enter_the_Application_Id_Here",
"CLIENT_SECRET": "Enter_the_Client_Secret_Here"

    Hierbei gilt:

    • Enter_the_Application_Id_Here: Hierbei handelt es sich um die Anwendungs-ID (Client) der zuvor von Ihnen registrierten Anwendung. Diese ID befindet sich im Bereich Übersicht der App-Registrierung.
    • Enter_the_Tenant_Id_Here: Ersetzen Sie diesen Wert durch die Mandanten-ID oder den Mandantennamen (z. B. „contoso.microsoft.com“). Diese Werte befinden sich im Bereich Übersicht der App-Registrierung.
    • Enter_the_Client_Secret_Here: Ersetzen Sie diesen Wert durch den zuvor erstellten geheimen Clientschlüssel. Um einen neuen Schlüssel zu generieren, verwenden Sie Zertifikate und Geheimnisse in den App-Registrierungseinstellungen.

    Die Verwendung eines nicht verschlüsselten Schlüssels im Quellcode stellt ein erhöhtes Sicherheitsrisiko für Ihre Anwendung dar. Aus Gründen der Einfachheit wird im Beispiel in diesem Schnellstart allerdings ein nicht verschlüsselter geheimer Clientschlüssel verwendet. Es wird empfohlen, in vertraulichen Clientanwendungen Zertifikatanmeldeinformationen anstelle von geheimen Clientschlüsseln zu verwenden. Das gilt insbesondere bei Apps, die Sie in der Produktion bereitstellen möchten.

  3. Bearbeiten Sie .env, und ersetzen Sie die Microsoft Entra ID- und Microsoft Graph-Endpunkte durch die folgenden Werte:

    • Ersetzen Sie Enter_the_Cloud_Instance_Id_Here für den Microsoft Entra-Endpunkt durch https://login.microsoftonline.com.
    • Ersetzen Sie Enter_the_Graph_Endpoint_Here für den Microsoft Graph-Endpunkt durch https://graph.microsoft.com/.

Wenn Sie zu diesem Zeitpunkt versuchen, die Anwendung auszuführen, wird der Fehler HTTP 403 – Verboten angezeigt: Insufficient privileges to complete the operation. Dieser Fehler tritt auf, da für eine nur für die App geltende Berechtigung eine Administratoreinwilligung erforderlich ist. Ein*e Anwendungsadministrator*in oder globale*r Administrator*in muss also die Einwilligung für Ihre Anwendung erteilen. Wählen Sie je nach Ihrer Rolle eine der unten angegebenen Optionen aus:

Administrators

Gehen Sie wie folgt vor, wenn Sie die Rolle Anwendungsadministrator oder Globaler Administrator innehaben: Navigieren Sie im Azure-Portal in der Anwendungsregistrierung zur Seite API-Berechtigungen, und wählen Sie Administratoreinwilligung für „{Mandantenname}“ erteilen aus. Hierbei steht „{Mandantenname}“ für den Namen Ihres Verzeichnisses.

Standardbenutzer*innen

Wenn Sie ein Standardbenutzer Ihres Mandanten sind, müssen Sie einen globalen Administrator bitten, die Administratoreinwilligung für Ihre Anwendung zu erteilen. Übermitteln Sie hierzu die folgende URL an Ihren Administrator:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

Hierbei gilt:

  • Enter_the_Tenant_Id_Here: Ersetzen Sie diesen Wert durch die Mandanten-ID oder den Mandantennamen (z.B. „contoso.microsoft.com“).
  • Enter_the_Application_Id_Here ist die Anwendungs-ID (Client) für die von Ihnen registrierte Anwendung.

Schritt 5: Ausführen der Anwendung

Navigieren Sie über eine Eingabeaufforderung oder Konsole zum Stammordner des Beispiels (in dem sich package.json befindet). Sie müssen die für Ihre Beispiel-App benötigten Abhängigkeiten installieren, bevor Sie die App zum ersten Mal ausführen:

npm install

Führen Sie dann die Anwendung über die Eingabeaufforderung oder über die Konsole aus:

node . --op getUsers

Die Konsolenausgabe sollte ein JSON-Fragment enthalten, das eine Liste der Benutzer in Ihrem Microsoft Entra-Verzeichnis darstellt.

Informationen zum Code

Im Anschluss werden einige wichtige Aspekte der Beispielanwendung erläutert.

MSAL Node

MSAL Node ist die Bibliothek zum Anmelden von Benutzern und Anfordern von Token, die für den Zugriff auf eine durch Microsoft Identity Platform geschützte API verwendet wird. In dieser Schnellstartanleitung werden Token nicht auf der Grundlage von delegierten Berechtigungen, sondern wie beschrieben auf der Grundlage von Anwendungsberechtigungen (unter Verwendung der anwendungseigenen Identität) angefordert. Der hier verwendete Authentifizierungsablauf wird als OAuth 2.0-Clientanmeldeinformationsflow bezeichnet. Weitere Informationen zur Verwendung von MSAL Node mit Daemon-Apps finden Sie unter Szenario: Daemon-App zum Aufrufen von Web-APIs.

MSAL Node kann mithilfe des folgenden npm-Befehls installiert werden:

npm install @azure/msal-node --save

MSAL-Initialisierung

Sie können den Verweis auf MSAL hinzufügen, indem Sie den folgenden Code hinzufügen:

const msal = require('@azure/msal-node');

Initialisieren Sie MSAL anschließend mit dem folgenden Code:

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
        clientSecret: "Enter_the_Client_Secret_Here",
   }
};
const cca = new msal.ConfidentialClientApplication(msalConfig);
Hierbei gilt: BESCHREIBUNG
clientId Die Anwendungs-ID (Client) für die im Azure-Portal registrierte Anwendung. Dieser Wert befindet sich im Azure-Portal auf der Seite Übersicht der App.
authority Der STS-Endpunkt für den zu authentifizierenden Benutzer. Normalerweise https://login.microsoftonline.com/{tenant} für die öffentliche Cloud, wobei „{tenant}“ der Name Ihres Mandanten bzw. Ihre Mandanten-ID ist.
clientSecret Der geheime Clientschlüssel, der für die Anwendung im Azure-Portal erstellt wird.

Weitere Informationen finden Sie in der Referenzdokumentation für ConfidentialClientApplication.

Anfordern von Token

Verwenden Sie die acquireTokenByClientCredential-Methode, um ein Token mit der Identität einer App anzufordern:

const tokenRequest = {
    scopes: [ 'https://graph.microsoft.com/.default' ],
};

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);
Hierbei gilt: BESCHREIBUNG
tokenRequest Enthält die angeforderten Bereiche. Für vertrauliche Clients sollte ein Format wie {Application ID URI}/.default verwendet werden. Hiermit wird angegeben, dass die angeforderten Bereiche diejenigen sind, die im App-Objekt, das im Azure-Portal festgelegt ist, statisch definiert sind (für Microsoft Graph wird für {Application ID URI} auf https://graph.microsoft.com verwiesen). Für benutzerdefinierte Web-APIs wird {Application ID URI} in der Anwendungsregistrierung im Azure-Portal unter dem Abschnitt Eine API verfügbar machen definiert.
tokenResponse Die Antwort enthält ein Zugriffstoken für die angeforderten Bereiche.

Hilfe und Support

Wenn Sie Hilfe benötigen, ein Problem melden möchten oder sich über Ihre Supportoptionen informieren möchten, finden Sie weitere Informationen unter Hilfe und Support für Entwickler.

Nächste Schritte

Weitere Informationen zur Entwicklung von Daemon-/Konsolen-Apps mit MSAL Node finden Sie im folgenden Tutorial:

Daemon-App zum Aufrufen von Web-APIs