Szybki start: uzyskiwanie tokenu i wywoływanie programu Microsoft Graph z poziomu aplikacji konsolowej Node.js

W tym przewodniku Szybki start pobierzesz i uruchomisz przykładowy kod, który pokazuje, jak aplikacja konsolowa Node.js może uzyskać token dostępu przy użyciu tożsamości aplikacji w celu wywołania interfejsu API programu Microsoft Graph i wyświetlenia listy użytkowników w katalogu. Przykładowy kod przedstawia sposób uruchamiania zadania nienadzorowanego lub usługi systemu Windows przy użyciu tożsamości aplikacji zamiast tożsamości użytkownika.

W tym przewodniku Szybki start użyto biblioteki Microsoft Authentication Library dla Node.js (MSAL Node) z przyznawaniem poświadczeń klienta.

Wymagania wstępne

• Node.js
• Visual Studio Code lub inny edytor kodu

Rejestrowanie i pobieranie przykładowej aplikacji

Wykonaj poniższe kroki, aby rozpocząć pracę.

Krok 1. Rejestrowanie aplikacji

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

Aby ręcznie zarejestrować aplikację i dodać informacje na temat rejestracji aplikacji do rozwiązania, wykonaj następujące czynności:

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji.
2. Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
3. Wybierz opcjęNowa rejestracja.
4. Wprowadź nazwę aplikacji, na przykład msal-node-cli. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.
5. Wybierz pozycję Zarejestruj.
6. W obszarze Zarządzanie wybierz pozycję Certyfikaty i wpisy tajne.
7. W obszarze Wpisy tajne klienta wybierz pozycję Nowy klucz tajny klienta, wprowadź nazwę, a następnie wybierz pozycję Dodaj. Zarejestruj wartość wpisu tajnego w bezpiecznej lokalizacji do użycia w późniejszym kroku.
8. W obszarze Zarządzanie wybierz pozycję Uprawnienia>interfejsu API Dodaj uprawnienie. Wybierz pozycję Microsoft Graph.
9. Wybierz Uprawnienia aplikacji.
10. W węźle Użytkownik wybierz pozycję User.Read.All, a następnie wybierz pozycję Dodaj uprawnienia.

Krok 2. Pobieranie przykładowego projektu Node.js

Pobieranie przykładu kodu

Krok 3. Konfigurowanie przykładowego projektu Node.js

1. Wyodrębnij plik zip do folderu lokalnego w pobliżu katalogu głównego dysku, na przykład C:/Azure-Samples.

2. Edytuj plik env i zastąp wartości pól TENANT_ID, CLIENT_IDi CLIENT_SECRET następującym fragmentem kodu:

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

   Gdzie:

   • Enter_the_Application_Id_Here — to identyfikator aplikacji (klienta) zarejestrowanej wcześniej aplikacji. Znajdź ten identyfikator w przeglądzie rejestracji aplikacji.
   • Enter_the_Tenant_Id_Here— zastąp tę wartość identyfikatorem dzierżawy lub nazwą dzierżawy (na przykład contoso.microsoft.com). Znajdź te wartości w sekcji Przegląd rejestracji aplikacji.
   • Enter_the_Client_Secret_Here — zastąp tę wartość utworzonym wcześniej wpisem tajnym klienta. Aby wygenerować nowy klucz, użyj certyfikatów i wpisów tajnych w ustawieniach rejestracji aplikacji.

   Użycie wpisu tajnego w postaci zwykłego tekstu w kodzie źródłowym stanowi zwiększone zagrożenie bezpieczeństwa aplikacji. Chociaż przykład w tym przewodniku Szybki start używa wpisu tajnego klienta w postaci zwykłego tekstu, jest to tylko dla uproszczenia. Zalecamy używanie poświadczeń certyfikatu zamiast wpisów tajnych klienta w poufnych aplikacjach klienckich, zwłaszcza tych aplikacji, które mają zostać wdrożone w środowisku produkcyjnym.

3. Edytuj plik env i zastąp punkty końcowe Microsoft Entra ID i Microsoft Graph następującymi wartościami:

   • W przypadku punktu końcowego Microsoft Entra zastąp ciąg Enter_the_Cloud_Instance_Id_Here .https://login.microsoftonline.com
   • W przypadku punktu końcowego programu Microsoft Graph zastąp ciąg Enter_the_Graph_Endpoint_Here .https://graph.microsoft.com/

Krok 4. Zgoda administratora

Jeśli spróbujesz uruchomić aplikację w tym momencie, zostanie wyświetlony błąd HTTP 403 — Zabronione : Insufficient privileges to complete the operation. Ten błąd występuje, ponieważ każde uprawnienie tylko do aplikacji wymaga zgody administratora: ktoś przypisany co najmniej do roli Administrator aplikacji musi wyrazić zgodę na twoją aplikację. Wybierz jedną z poniższych opcji w zależności od twojej roli:

Administratorzy

Jeśli masz przypisaną co najmniej rolę Administratora aplikacji, przejdź do strony Uprawnienia interfejsu API w rejestracji aplikacji w witrynie Azure Portal i wybierz pozycję Udziel zgody administratora dla aplikacji {Nazwa dzierżawy} (gdzie {Nazwa dzierżawy} jest nazwą katalogu).

Użytkownicy standardowi

Jeśli jesteś użytkownikiem standardowym dzierżawy, musisz poprosić administratora aplikacji w chmurze o udzielenie zgody administratora aplikacji dla aplikacji. Aby to zrobić, udostępnij administratorowi następujący adres URL:

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

Gdzie:

• Enter_the_Tenant_Id_Here — zastąp tę wartość wartością Identyfikator dzierżawy lub Nazwa dzierżawy (na przykład contoso.microsoft.com)
• Enter_the_Application_Id_Here jest identyfikatorem aplikacji (klienta) dla zarejestrowanej aplikacji.

Krok 5. Uruchomienie aplikacji

Znajdź folder główny przykładu (gdzie package.json się znajduje) w wierszu polecenia lub konsoli. Musisz zainstalować zależności wymagane przez przykładową aplikację przed uruchomieniem jej po raz pierwszy:

npm install

Następnie uruchom aplikację za pomocą wiersza polecenia lub konsoli:

node . --op getUsers

W konsoli powinien zostać wyświetlony fragment kodu JSON reprezentujący listę użytkowników w katalogu Microsoft Entra.

Informacje o kodzie

Poniżej omówiono niektóre ważne aspekty przykładowej aplikacji.

Węzeł BIBLIOTEKI MSAL

Biblioteka MSAL Node to biblioteka używana do logowania użytkowników i żądania tokenów używanych do uzyskiwania dostępu do interfejsu API chronionego przez Platforma tożsamości Microsoft. Zgodnie z opisem ten przewodnik Szybki start żąda tokenów według uprawnień aplikacji (przy użyciu własnej tożsamości aplikacji) zamiast uprawnień delegowanych. Przepływ uwierzytelniania używany w tym przypadku jest nazywany przepływem poświadczeń klienta OAuth 2.0. Aby uzyskać więcej informacji na temat używania środowiska MSAL Node z aplikacjami demona, zobacz Scenariusz: aplikacja demona.

Węzeł MSAL można zainstalować, uruchamiając następujące polecenie npm.

npm install @azure/msal-node --save

Inicjowanie biblioteki MSAL

Aby dodać odwołanie do biblioteki MSAL, dodaj następujący kod:

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

Następnie zainicjuj bibliotekę MSAL, używając następującego kodu:

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);

Gdzie:	opis
clientId	Jest identyfikatorem aplikacji (klienta) dla aplikacji zarejestrowanej w witrynie Azure Portal. Tę wartość można znaleźć na stronie Przegląd aplikacji w witrynie Azure Portal.
authority	Punkt końcowy usługi STS na potrzeby uwierzytelnienia użytkownika. Zwykle https://login.microsoftonline.com/{tenant} w przypadku chmury publicznej, gdzie {tenant} jest nazwą dzierżawy lub identyfikatorem dzierżawy.
clientSecret	Czy klucz tajny klienta jest tworzony dla aplikacji w witrynie Azure Portal.

Więcej informacji można znaleźć w dokumentacji dotyczącej metody ConfidentialClientApplication

Przesyłanie żądań tokenów

Aby zażądać tokenu przy użyciu tożsamości aplikacji, należy użyć metody acquireTokenByClientCredential:

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

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);

Gdzie:	opis
tokenRequest	Zawiera żądane zakresy. W przypadku klientów poufnych należy użyć formatu podobnego do {Application ID URI}/.default wskazującego, że żądane zakresy są statycznie zdefiniowane w obiekcie aplikacji ustawionym w witrynie Azure Portal (w przypadku programu Microsoft Graph {Application ID URI} wskazuje wartość https://graph.microsoft.com). W przypadku niestandardowych internetowych interfejsów {Application ID URI} API jest definiowana w sekcji Uwidacznianie interfejsu API w obszarze Rejestracja aplikacji w witrynie Azure Portal.
tokenResponse	Odpowiedź zawiera token dostępu dla żądanych zakresów.

Pomoc i obsługa techniczna

Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.

Następne kroki

Aby dowiedzieć się więcej na temat programowania aplikacji demona/konsoli za pomocą biblioteki MSAL Node, zobacz samouczek:

Aplikacja demona, która wywołuje internetowe interfejsy API