Schnellstart: Abrufen eines Tokens und Aufrufen der Microsoft Graph-API aus einer Node.js-Konsolen-App
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
- Node.js
- Visual Studio Code oder ein anderer Code-Editor
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:
- Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.
- Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.
- Wählen Sie Neue Registrierung aus.
- 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. - Wählen Sie Registrieren aus.
- Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.
- 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.
- Wählen Sie unter Verwalten die Optionen API-Berechtigungen>Berechtigung hinzufügen aus. Wählen Sie Microsoft Graph.
- Wählen Sie Anwendungsberechtigungen.
- 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
Extrahieren Sie die ZIP-Datei in einem lokalen Ordner in der Nähe des Datenträger-Stammverzeichnisses (beispielsweise unter C:\Azure-Samples).
Bearbeiten Sie .env, und ersetzen Sie die Felder
TENANT_ID,CLIENT_IDundCLIENT_SECRETdurch 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.
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_Herefür den Microsoft Entra-Endpunkt durchhttps://login.microsoftonline.com. - Ersetzen Sie
Enter_the_Graph_Endpoint_Herefür den Microsoft Graph-Endpunkt durchhttps://graph.microsoft.com/.
- Ersetzen Sie
Schritt 4: Administratorzustimmung
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. Jemand, der mindestens die Rolle Anwendungsadmin hat, muss also die Einwilligung für Ihre Anwendung erteilen. Wählen Sie je nach Ihrer Rolle eine der unten angegebenen Optionen aus:
Administratoren
Gehen Sie wie folgt vor, wenn Sie mindestens die Rolle Anwendungsadmin 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 Standardbenutzer:in Ihres Mandanten sind, müssen Sie eine Person mit der Rolle „Cloudanwendungsadministrator“ 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_Hereist 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: