Erstellen von JavaScript-Apps mit Microsoft Graph und nur app-Authentifizierung
In diesem Tutorial erfahren Sie, wie Sie eine JavaScript-Konsolen-App erstellen, die die Microsoft Graph-API verwendet, um mithilfe der reinen App-Authentifizierung auf Daten zuzugreifen. Die reine App-Authentifizierung ist eine gute Wahl für Hintergrunddienste oder Anwendungen, die auf Daten für alle Benutzer in einer Organisation zugreifen müssen.
Hinweis
Informationen zur Verwendung von Microsoft Graph zum Zugreifen auf Daten im Namen eines Benutzers finden Sie in diesem Tutorial zur (delegierten) Benutzerauthentifizierung.
In diesem Lernprogramm wird Folgendes vermittelt:
Tipp
Alternativ zur Durchführung dieses Tutorials können Sie das GitHub-Repository herunterladen oder klonen und den Anweisungen in der INFODATEI folgen, um eine Anwendung zu registrieren und das Projekt zu konfigurieren.
Voraussetzungen
Bevor Sie mit diesem Tutorial beginnen, sollte Node.js auf Ihrem Entwicklungscomputer installiert sein.
Sie sollten auch über ein Microsoft-Geschäfts-, Schul- oder Unikonto mit der Rolle "Globaler Administrator" verfügen. Wenn Sie nicht über einen Microsoft 365-Mandanten verfügen, können Sie sich über das Microsoft 365-Entwicklerprogramm für einen mandantenfähigen Mandanten qualifizieren. Weitere Informationen finden Sie in den häufig gestellten Fragen. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.
Hinweis
Dieses Tutorial wurde mit Node.js Version 16.14.2 geschrieben. Die Schritte in diesem Leitfaden funktionieren möglicherweise mit anderen Versionen, die jedoch nicht getestet wurden.
Registrieren der App im Portal
In dieser Übung registrieren Sie eine neue Anwendung in Azure Active Directory, um die reine App-Authentifizierung zu aktivieren. Sie können eine Anwendung über das Microsoft Entra Admin Center oder mithilfe des Microsoft Graph PowerShell SDK registrieren.
Registrieren der Anwendung für die reine App-Authentifizierung
In diesem Abschnitt registrieren Sie eine Anwendung, die die reine App-Authentifizierung mit Clientanmeldeinformationen unterstützt.
Öffnen Sie einen Browser, navigieren Sie zum Microsoft Entra Admin Center , und melden Sie sich mit einem globalen Administratorkonto an.
Wählen Sie im linken Navigationsbereich Microsoft Entra ID aus, erweitern Sie Identität, erweitern Sie Anwendungen, und wählen Sie dann App-Registrierungen aus.
Wählen Sie Neue Registrierung aus. Geben Sie einen Namen für Ihre Anwendung ein,
Graph App-Only Auth Tutorial
z. B. .Legen Sie Unterstützte Kontotypen auf Nur Konten in diesem Organisationsverzeichnis fest.
Lassen Sie URI umleiten leer.
Wählen Sie Registrieren aus. Kopieren Sie auf der Seite Übersicht der Anwendung den Wert der Anwendungs-ID (Client) und der Verzeichnis-ID (Mandanten-ID), und speichern Sie sie. Diese Werte benötigen Sie im nächsten Schritt.
Wählen Sie API-Berechtigungen unter Verwalten aus.
Entfernen Sie die Standardberechtigung User.Read unter Konfigurierte Berechtigungen , indem Sie die Auslassungspunkte (...) in der Zeile auswählen und Berechtigung entfernen auswählen.
Wählen Sie Berechtigung hinzufügen und dann Microsoft Graph aus.
Wählen Sie Anwendungsberechtigungen aus.
Wählen Sie User.Read.All und dann Berechtigungen hinzufügen aus.
Wählen Sie Administratoreinwilligung erteilen für... und dann Ja aus, um die Administratoreinwilligung für die ausgewählte Berechtigung bereitzustellen.
Wählen Sie zertifikate und geheimnisse unter Verwalten und dann Neuer geheimer Clientschlüssel aus.
Geben Sie eine Beschreibung ein, wählen Sie eine Dauer aus, und wählen Sie Hinzufügen aus.
Kopieren Sie das Geheimnis aus der Spalte Wert . Sie benötigen es in den nächsten Schritten.
Wichtig
Dieser geheime Clientschlüssel wird nicht noch einmal angezeigt, stellen Sie daher sicher, dass Sie ihn jetzt kopieren.
Hinweis
Beachten Sie, dass Sie im Gegensatz zu den Schritten bei der Registrierung für die Benutzerauthentifizierung in diesem Abschnitt Microsoft Graph-Berechtigungen für die App-Registrierung konfiguriert haben. Dies liegt daran, dass die reine App-Authentifizierung den Clientanmeldeinformationsflow verwendet, der erfordert, dass Berechtigungen für die App-Registrierung konfiguriert werden. Ausführliche Informationen finden Sie unter .default-Bereich .
Erstellen einer JavaScript-Konsolen-App
Erstellen Sie zunächst ein neues Node.js-Projekt. Öffnen Sie Ihre Befehlszeilenschnittstelle (CLI) in einem Verzeichnis, in dem Sie das Projekt erstellen möchten. Führen Sie den folgenden Befehl aus.
npm init
Beantworten Sie die Eingabeaufforderungen, indem Sie entweder Ihre eigenen Werte angeben oder die Standardwerte akzeptieren.
Installieren von Abhängigkeiten
Bevor Sie mit dem Vorgang fortfahren, fügen Sie einige zusätzliche Abhängigkeiten hinzu, die Sie später verwenden werden.
- Azure Identity-Clientbibliothek für JavaScript zum Authentifizieren des Benutzers und Abrufen von Zugriffstoken.
- Microsoft Graph JavaScript-Clientbibliothek , um Aufrufe an Microsoft Graph zu senden.
-
isomorphic-fetch zum Hinzufügen
fetch
einer API zu Node.js. Dies ist eine Abhängigkeit für die JavaScript-Clientbibliothek von Microsoft Graph. - readline-sync zum Auffordern des Benutzers zur Eingabe.
Führen Sie die folgenden Befehle in Ihrer CLI aus, um die Abhängigkeiten zu installieren.
npm install @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch readline-sync
Laden von Anwendungseinstellungen
In diesem Abschnitt fügen Sie dem Projekt die Details Ihrer App-Registrierung hinzu.
Erstellen Sie im Stammverzeichnis Ihres Projekts eine Datei mit dem Namen appSettings.js , und fügen Sie den folgenden Code hinzu.
const settings = { clientId: 'YOUR_CLIENT_ID_HERE', clientSecret: 'YOUR_CLIENT_SECRET_HERE', tenantId: 'YOUR_TENANT_ID_HERE', }; export default settings;
Aktualisieren Sie die Werte in
settings
gemäß der folgenden Tabelle.Einstellung Wert clientId
Die Client-ID Ihrer App-Registrierung tenantId
Die Mandanten-ID Ihrer Organisation. clientSecret
Der im vorherigen Schritt generierte geheime Clientschlüssel
Entwerfen der App
In diesem Abschnitt erstellen Sie ein einfaches konsolenbasiertes Menü.
Erstellen Sie im Stammverzeichnis Ihres Projekts eine Datei mit dem Namen graphHelper.js , und fügen Sie den folgenden Platzhaltercode hinzu. Sie fügen dieser Datei in späteren Schritten weiteren Code hinzu.
module.exports = {};
Erstellen Sie im Stammverzeichnis Ihres Projekts eine Datei mit dem Namen index.js , und fügen Sie den folgenden Code hinzu.
import { keyInSelect } from 'readline-sync'; import settings from './appSettings.js'; import { initializeGraphForAppOnlyAuth, getAppOnlyTokenAsync, getUsersAsync, makeGraphCallAsync, } from './graphHelper.js'; async function main() { console.log('JavaScript Graph App-Only Tutorial'); let choice = 0; // Initialize Graph initializeGraph(settings); const choices = ['Display access token', 'List users', 'Make a Graph call']; while (choice != -1) { choice = keyInSelect(choices, 'Select an option', { cancel: 'Exit' }); switch (choice) { case -1: // Exit console.log('Goodbye...'); break; case 0: // Display access token await displayAccessTokenAsync(); break; case 1: // List emails from user's inbox await listUsersAsync(); break; case 2: // Run any Graph code await doGraphCallAsync(); break; default: console.log('Invalid choice! Please try again.'); } } } main();
Fügen Sie am Ende der Datei die folgenden Platzhaltermethoden hinzu. Sie implementieren sie in späteren Schritten.
function initializeGraph(settings) { // TODO } async function displayAccessTokenAsync() { // TODO } async function listUsersAsync() { // TODO } async function doGraphCallAsync() { // TODO }
Dadurch wird ein einfaches Menü implementiert und die Auswahl des Benutzers aus der Befehlszeile gelesen.
Hinzufügen einer reinen App-Authentifizierung
In diesem Abschnitt fügen Sie der Anwendung die reine App-Authentifizierung hinzu. Dies ist erforderlich, um das erforderliche OAuth-Zugriffstoken zum Aufrufen von Microsoft Graph abzurufen. In diesem Schritt integrieren Sie die Azure Identity-Clientbibliothek für JavaScript in die Anwendung und konfigurieren die Authentifizierung für die Microsoft Graph-JavaScript-Clientbibliothek.
Die Azure Identity-Bibliothek bietet eine Reihe von TokenCredential
Klassen, die OAuth2-Tokenflows implementieren. Die Microsoft Graph-Clientbibliothek verwendet diese Klassen, um Aufrufe von Microsoft Graph zu authentifizieren.
Konfigurieren des Graph-Clients für die reine App-Authentifizierung
In diesem Abschnitt verwenden Sie die ClientSecretCredential
-Klasse, um mithilfe des Clientanmeldeinformationsflows ein Zugriffstoken anzufordern.
Öffnen Sie graphHelper.js , und fügen Sie den folgenden Code hinzu.
import 'isomorphic-fetch'; import { ClientSecretCredential } from '@azure/identity'; import { Client } from '@microsoft/microsoft-graph-client'; // prettier-ignore import { TokenCredentialAuthenticationProvider } from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials/index.js'; let _settings = undefined; let _clientSecretCredential = undefined; let _appClient = undefined; export function initializeGraphForAppOnlyAuth(settings) { // Ensure settings isn't null if (!settings) { throw new Error('Settings cannot be undefined'); } _settings = settings; // Ensure settings isn't null if (!_settings) { throw new Error('Settings cannot be undefined'); } if (!_clientSecretCredential) { _clientSecretCredential = new ClientSecretCredential( _settings.tenantId, _settings.clientId, _settings.clientSecret, ); } if (!_appClient) { const authProvider = new TokenCredentialAuthenticationProvider( _clientSecretCredential, { scopes: ['https://graph.microsoft.com/.default'], }, ); _appClient = Client.initWithMiddleware({ authProvider: authProvider, }); } }
Ersetzen Sie die leere
initializeGraph
Funktion in index.js durch Folgendes.function initializeGraph(settings) { initializeGraphForAppOnlyAuth(settings); }
Dieser Code deklariert zwei private Eigenschaften, ein ClientSecretCredential
-Objekt und ein Client
-Objekt. Die InitializeGraphForAppOnlyAuth
-Funktion erstellt eine neue Instanz von ClientSecretCredential
und verwendet diese Instanz dann, um eine neue Instanz von Client
zu erstellen. Jedes Mal, wenn ein API-Aufruf an Microsoft Graph über _appClient
erfolgt, werden die bereitgestellten Anmeldeinformationen verwendet, um ein Zugriffstoken abzurufen.
Testen von ClientSecretCredential
Fügen Sie als Nächstes Code hinzu, um ein Zugriffstoken ClientSecretCredential
von abzurufen.
Fügen Sie graphHelper.jsdie folgende Funktion hinzu.
export async function getAppOnlyTokenAsync() { // Ensure credential isn't undefined if (!_clientSecretCredential) { throw new Error('Graph has not been initialized for app-only auth'); } // Request token with given scopes const response = await _clientSecretCredential.getToken([ 'https://graph.microsoft.com/.default', ]); return response.token; }
Ersetzen Sie die leere
displayAccessTokenAsync
Funktion in index.js durch Folgendes.async function displayAccessTokenAsync() { try { const appOnlyToken = await getAppOnlyTokenAsync(); console.log(`App-only token: ${appOnlyToken}`); } catch (err) { console.log(`Error getting app-only access token: ${err}`); } }
Führen Sie den folgenden Befehl in Ihrer CLI im Stammverzeichnis Ihres Projekts aus.
node index.js
Geben Sie ein
1
, wenn Sie zur Eingabe einer Option aufgefordert werden. Die Anwendung zeigt ein Zugriffstoken an.JavaScript Graph App-Only Tutorial [1] Display access token [2] List users [3] Make a Graph call [0] Exit Select an option [1...3 / 0]: 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
Tipp
Nur zu Validierungs- und Debugzwecken können Sie Nur-App-Zugriffstoken mithilfe des Onlinetokenparsers von Microsoft unter https://jwt.msdecodieren. Dies kann nützlich sein, wenn beim Aufrufen von Microsoft Graph Tokenfehler auftreten. Beispielsweise wird überprüft, ob der
role
Anspruch im Token die erwarteten Microsoft Graph-Berechtigungsbereiche enthält.
Benutzer auflisten
In diesem Abschnitt fügen Sie die Möglichkeit hinzu, alle Benutzer in Ihrer Azure Active Directory-Instanz mithilfe der reinen App-Authentifizierung aufzulisten.
Öffnen Sie graphHelper.js , und fügen Sie die folgende Funktion hinzu.
export async function getUsersAsync() { // Ensure client isn't undefined if (!_appClient) { throw new Error('Graph has not been initialized for app-only auth'); } return _appClient ?.api('/users') .select(['displayName', 'id', 'mail']) .top(25) .orderby('displayName') .get(); }
Ersetzen Sie die leere
listUsersAsync
Funktion in index.js durch Folgendes.async function listUsersAsync() { try { const userPage = await getUsersAsync(); const users = userPage.value; // Output each user's details for (const user of users) { console.log(`User: ${user.displayName ?? 'NO NAME'}`); console.log(` ID: ${user.id}`); console.log(` Email: ${user.mail ?? 'NO EMAIL'}`); } // If @odata.nextLink is not undefined, there are more users // available on the server const moreAvailable = userPage['@odata.nextLink'] != undefined; console.log(`\nMore users available? ${moreAvailable}`); } catch (err) { console.log(`Error getting users: ${err}`); } }
Führen Sie die App aus, und wählen Sie Option 2 aus, um Benutzer aufzulisten.
[1] Display access token [2] List users [3] Make a Graph call [0] Exit Select an option [1...3 / 0]: 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? true
Code erläutert
Betrachten Sie den Code in der getUsersAsync
Funktion.
- Es ruft eine Sammlung von Benutzern ab.
- Wird verwendet
select
, um bestimmte Eigenschaften anzufordern. - Wird verwendet
top
, um die Anzahl der zurückgegebenen Benutzer zu begrenzen. -
orderBy
Verwendet, um die Antwort zu sortieren.
Optional: Fügen Sie Ihren eigenen Code hinzu.
In diesem Abschnitt fügen Sie der Anwendung Ihre eigenen Microsoft Graph-Funktionen hinzu. Dies kann ein Codeausschnitt aus der Microsoft Graph-Dokumentation oder graph-Explorer oder code sein, den Sie erstellt haben. Dieser Abschnitt ist optional.
Aktualisieren der App
Öffnen Sie graphHelper.js , und fügen Sie die folgende Funktion hinzu.
// This function serves as a playground for testing Graph snippets // or other code export async function makeGraphCallAsync() { // INSERT YOUR CODE HERE }
Ersetzen Sie die leere
makeGraphCallAsync
Funktion in index.js durch Folgendes.async function doGraphCallAsync() { try { await makeGraphCallAsync(); } catch (err) { console.log(`Error making Graph call: ${err}`); } }
Auswählen einer API
Suchen Sie eine API in Microsoft Graph, die Sie ausprobieren möchten. Beispiel: Die Api zum Erstellen eines Ereignisses . Sie können eines der Beispiele in der API-Dokumentation verwenden, oder Sie können eine API-Anforderung im Graph-Explorer anpassen und den generierten Codeausschnitt verwenden.
Konfigurieren von Berechtigungen
Überprüfen Sie den Abschnitt Berechtigungen der Referenzdokumentation für Die ausgewählte API, um zu sehen, welche Authentifizierungsmethoden unterstützt werden. Einige APIs unterstützen z. B. keine reinen Apps oder persönlichen Microsoft-Konten.
- Informationen zum Aufrufen einer API mit Benutzerauthentifizierung (wenn die API die (delegierte) Benutzerauthentifizierung unterstützt), finden Sie im Tutorial zur benutzerseitig (delegierten) Authentifizierung .
- Um eine API mit nur app-Authentifizierung aufzurufen (sofern die API dies unterstützt), fügen Sie den erforderlichen Berechtigungsbereich im Azure AD Admin Center hinzu.
Fügen Sie Ihren Code hinzu
Kopieren Sie Ihren Code in die makeGraphCallAsync
Funktion in graphHelper.js. Wenn Sie einen Codeausschnitt aus der Dokumentation oder dem Graph-Explorer kopieren, müssen Sie den client
_appClient
in umbenennen.
Herzlichen Glückwunsch!
Sie haben das JavaScript-Tutorial für Microsoft Graph abgeschlossen. Nachdem Sie nun über eine funktionierende App verfügen, die Microsoft Graph aufruft, können Sie experimentieren und neue Features hinzufügen.
- Erfahren Sie, wie Sie die (delegierte) Benutzerauthentifizierung mit dem Microsoft Graph JavaScript SDK verwenden.
- Besuchen Sie die Übersicht über Microsoft Graph , um alle Daten anzuzeigen, auf die Sie mit Microsoft Graph zugreifen können.
Microsoft Graph-Toolkit
Wenn Sie JavaScript-Apps mit Benutzeroberfläche erstellen, bietet das Microsoft Graph-Toolkit eine Sammlung von Komponenten, die die Entwicklung vereinfachen können.
TypeScript/JavaScript-Beispiele
Liegt ein Problem mit diesem Abschnitt vor? Wenn ja, senden Sie uns Feedback, damit wir den Abschnitt verbessern können.