Logowanie użytkowników i wywoływanie internetowego interfejsu API w przykładowej aplikacji internetowej Node.js

W tym przewodniku użyto przykładowego kodu, aby pokazać, jak dodać uwierzytelnianie i autoryzację w aplikacji internetowej Node.js. Przykładowa aplikacja loguje użytkowników do aplikacji internetowej Node.js, która następnie wywołuje interfejs API platformy .NET. Uwierzytelnianie i autoryzacja można włączyć przy użyciu szczegółów dzierżawy zewnętrznej. Przykładowa aplikacja internetowa używa biblioteki Microsoft Authentication Library (MSAL) dla środowiska Node do obsługi uwierzytelniania.

W tym artykule wykonasz następujące zadania:

• Zarejestruj i skonfiguruj internetowy interfejs API w centrum administracyjnym firmy Microsoft Entra.

• Zaktualizuj przykładową aplikację internetową node i ASP.NET internetowy interfejs API, aby użyć szczegółów dzierżawy zewnętrznej.

• Uruchom i przetestuj przykładową aplikację internetową i interfejs API.

Wymagania wstępne

• Wykonaj kroki opisane w artykule Logowanie użytkowników i wywoływanie interfejsu API w przykładowym artykule Node.js aplikacji internetowej. W tym artykule przedstawiono sposób logowania użytkowników przy użyciu przykładowej aplikacji internetowej Node.js.
• Visual Studio Code lub inny edytor kodu.
• Node.js.
• .NET 7.0 lub nowszy.
• Dzierżawa zewnętrzna. Aby go utworzyć, wybierz jedną z następujących metod:
  • (Zalecane) Użyj rozszerzenia Tożsamość zewnętrzna Microsoft Entra, aby skonfigurować dzierżawę zewnętrzną bezpośrednio w programie Visual Studio Code.
  • Utwórz nową dzierżawę zewnętrzną w centrum administracyjnym firmy Microsoft Entra.

Rejestrowanie internetowego interfejsu API

W tym kroku utworzysz internet i rejestrację aplikacji internetowego interfejsu API, a następnie określisz zakresy internetowego interfejsu API.

Rejestrowanie aplikacji internetowego interfejsu API

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.

2. Jeśli masz dostęp do wielu dzierżaw, użyj ikony Ustawienia w górnym menu, aby przełączyć się do dzierżawy zewnętrznej z menu Katalogi i subskrypcje.

3. Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.

4. Wybierz pozycję + Nowa rejestracja.

5. Na wyświetlonej stronie Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:

   1. W sekcji Nazwa wprowadź zrozumiałą nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji, na przykład ciam-ToDoList-api.

   2. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.

6. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

7. Po zakończeniu rejestracji zostanie wyświetlone okienko Przegląd aplikacji. Zapisz identyfikator katalogu (dzierżawy) i identyfikator aplikacji (klienta) do użycia w kodzie źródłowym aplikacji.

Konfigurowanie zakresów interfejsu API

Ten interfejs API musi uwidocznić uprawnienia, które klient musi uzyskać do wywoływania interfejsu API:

Interfejs API musi opublikować co najmniej jeden zakres, nazywany również uprawnieniem delegowanym, aby aplikacje klienckie pomyślnie uzyskały token dostępu dla użytkownika. Aby opublikować zakres, wykonaj następujące kroki:

1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację interfejsu API (ciam-ToDoList-api), aby otworzyć stronę Przegląd.

2. W obszarze Zarządzanie wybierz pozycję Uwidaczniaj interfejs API.

3. W górnej części strony obok pozycji Identyfikator URI identyfikatora aplikacji wybierz link Dodaj , aby wygenerować identyfikator URI unikatowy dla tej aplikacji.

4. Zaakceptuj proponowany identyfikator URI identyfikatora aplikacji, taki jak api://{clientId}, i wybierz pozycję Zapisz. Gdy aplikacja internetowa żąda tokenu dostępu dla internetowego interfejsu API, dodaje identyfikator URI jako prefiks dla każdego zakresu zdefiniowanego dla interfejsu API.

5. W obszarze Zakresy zdefiniowane przez ten interfejs API wybierz pozycję Dodaj zakres.

6. Wprowadź następujące wartości, które definiują dostęp do odczytu do interfejsu API, a następnie wybierz pozycję Dodaj zakres , aby zapisać zmiany:

   Właściwości	Wartość
   Nazwa zakresu	ToDoList.Read
   Kto może wyrazić zgodę	Tylko administratorzy
   Zgodę administratora wyświetlana nazwa	Odczytywanie listy zadań do wykonania użytkowników przy użyciu listy "TodoListApi"
   Opis zgody administratora	Zezwól aplikacji na odczytywanie listy zadań do wykonania użytkownika przy użyciu listy "TodoListApi".
   Stan	Włączono

7. Ponownie wybierz pozycję Dodaj zakres i wprowadź następujące wartości, które definiują zakres dostępu do odczytu i zapisu w interfejsie API. Wybierz pozycję Dodaj zakres , aby zapisać zmiany:

   Właściwości	Wartość
   Nazwa zakresu	ToDoList.ReadWrite
   Kto może wyrazić zgodę	Tylko administratorzy
   Zgodę administratora wyświetlana nazwa	Odczytywanie i zapisywanie listy zadań do wykonania użytkowników przy użyciu listy "ToDoListApi"
   Opis zgody administratora	Zezwalaj aplikacji na odczytywanie i zapisywanie listy zadań do wykonania użytkownika przy użyciu listy "ToDoListApi"
   Stan	Włączono

8. W obszarze Zarządzanie wybierz pozycję Manifest , aby otworzyć edytor manifestu interfejsu API.

9. Ustaw accessTokenAcceptedVersion właściwość na 2.

10. Wybierz pozycję Zapisz.

Dowiedz się więcej o zasadzie najniższych uprawnień podczas publikowania uprawnień dla internetowego interfejsu API.

Konfigurowanie ról aplikacji

Interfejs API musi opublikować co najmniej jedną rolę aplikacji dla aplikacji, nazywanych również uprawnieniem aplikacji, aby aplikacje klienckie uzyskały token dostępu jako siebie. Uprawnienia aplikacji to typ uprawnień, które interfejsy API powinny publikować, gdy chcą umożliwić aplikacjom klienckim pomyślne uwierzytelnienie się jako siebie i nie trzeba logować użytkowników. Aby opublikować uprawnienie aplikacji, wykonaj następujące kroki:

1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-ToDoList-api), aby otworzyć stronę Przegląd.

2. W obszarze Zarządzanie wybierz pozycję Role aplikacji.

3. Wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości, a następnie wybierz pozycję Zastosuj , aby zapisać zmiany:

   Właściwości	Wartość
   Display name	ToDoList.Read.All
   Dozwolone typy składowych	Aplikacje
   Wartość	ToDoList.Read.All
   opis	Zezwalaj aplikacji na odczytywanie listy zadań do wykonania każdego użytkownika przy użyciu listy "TodoListApi"

4. Ponownie wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości dla drugiej roli aplikacji, a następnie wybierz pozycję Zastosuj , aby zapisać zmiany:

   Właściwości	Wartość
   Display name	ToDoList.ReadWrite.All
   Dozwolone typy składowych	Aplikacje
   Wartość	ToDoList.ReadWrite.All
   opis	Zezwalaj aplikacji na odczytywanie i zapisywanie listy zadań do wykonania każdego użytkownika przy użyciu listy "ToDoListApi"

Konfigurowanie opcjonalnych oświadczeń

Możesz idtyp opcjonalne oświadczenie, aby ułatwić interfejsowi API sieci Web określenie, czy token jest tokenem aplikacji, czy aplikacją i tokenem użytkownika. Mimo że w tym samym celu można użyć kombinacji oświadczeń scp i ról , użycie oświadczenia idtyp jest najprostszym sposobem przekazania tokenu aplikacji i tokenu użytkownika. Na przykład wartość tego oświadczenia to aplikacja , gdy token jest tokenem tylko dla aplikacji.

Wykonaj kroki opisane w artykule Konfigurowanie opcjonalnych oświadczeń, aby dodać oświadczenie idtyp do tokenu dostępu:

• W polu Typ tokenu wybierz pozycję Dostęp.
• Z listy opcjonalnych oświadczeń wybierz pozycję idtyp.

Udzielanie uprawnień interfejsu API do aplikacji internetowej

Aby udzielić aplikacji klienckiej (ciam-client-app) uprawnień interfejsu API, wykonaj następujące kroki:

1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-client-app), aby otworzyć stronę Przegląd.

2. W obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API.

3. W obszarze Skonfigurowane uprawnienia wybierz pozycję Dodaj uprawnienie.

4. Wybierz kartę Interfejsy API używane przez moją organizację.

5. Na liście interfejsów API wybierz interfejs API, taki jak ciam-ToDoList-api.

6. Wybierz opcję Delegowane uprawnienia .

7. Z listy uprawnień wybierz pozycję ToDoList.Read, ToDoList.ReadWrite (w razie potrzeby użyj pola wyszukiwania).

8. Wybierz przycisk Dodaj uprawnienia. W tym momencie przypisano uprawnienia poprawnie. Jednak ponieważ dzierżawa jest dzierżawą klienta, użytkownicy odbiorcy sami nie mogą wyrazić zgody na te uprawnienia. Aby rozwiązać ten problem, administrator musi wyrazić zgodę na te uprawnienia w imieniu wszystkich użytkowników w dzierżawie:

   1. Wybierz pozycję Udziel zgody administratora dla <swojej nazwy> dzierżawy, a następnie wybierz pozycję Tak.

   2. Wybierz pozycję Odśwież, a następnie sprawdź, czy w obszarze Stan dla obu zakresów jest wyświetlana wartość Przyznane dla <nazwy> dzierżawy.

9. Z listy Skonfigurowane uprawnienia wybierz uprawnienia ToDoList.Read i ToDoList.ReadWrite, pojedynczo, a następnie skopiuj pełny identyfikator URI uprawnienia do późniejszego użycia. Pełny identyfikator URI uprawnień wygląda podobnie do api://{clientId}/{ToDoList.Read} lub api://{clientId}/{ToDoList.ReadWrite}.

Klonowanie lub pobieranie przykładowej aplikacji internetowej i internetowego interfejsu API

Aby uzyskać przykładową aplikację, możesz ją sklonować z usługi GitHub lub pobrać jako plik .zip.

• Aby sklonować przykład, otwórz wiersz polecenia i przejdź do miejsca, w którym chcesz utworzyć projekt, a następnie wprowadź następujące polecenie:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

• Pobierz plik .zip. Wyodrębnij go do ścieżki pliku, w której długość nazwy jest mniejsza niż 260 znaków.

Instalowanie zależności projektu

1. Otwórz okno konsoli i przejdź do katalogu zawierającego przykładową aplikację Node.js/Express:

   cd 2-Authorization\4-call-api-express\App
   

2. Uruchom następujące polecenia, aby zainstalować zależności aplikacji internetowej:

   npm install && npm update
   

Konfigurowanie przykładowej aplikacji internetowej i interfejsu API

Aby użyć rejestracji aplikacji w przykładzie aplikacji internetowej klienta:

1. W edytorze kodu otwórz App\authConfig.js plik.

2. Znajdź symbol zastępczy:

   • Enter_the_Application_Id_Here zastąp ją identyfikatorem aplikacji (klienta) zarejestrowanej wcześniej aplikacji.
   • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy to contoso.onmicrosoft.com, użyj polecenia contoso. Jeśli nie masz swojej nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
   • Enter_the_Client_Secret_Here i zastąp ją skopiowaną wcześniej wartością wpisu tajnego aplikacji.
   • Enter_the_Web_Api_Application_Id_Here zastąp go identyfikatorem aplikacji (klienta) skopiowanego wcześniej internetowego interfejsu API.

Aby użyć rejestracji aplikacji w przykładowym internetowym interfejsie API:

1. W edytorze kodu otwórz API\ToDoListAPI\appsettings.json plik.

2. Znajdź symbol zastępczy:

   • Enter_the_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) skopiowanego internetowego interfejsu API.
   • Enter_the_Tenant_Id_Here i zastąp go skopiowanymi wcześniej identyfikatorami katalogu (dzierżawy).
   • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy to contoso.onmicrosoft.com, użyj polecenia contoso. Jeśli nie masz swojej nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.

Uruchamianie i testowanie przykładowej aplikacji internetowej i interfejsu API

1. Otwórz okno konsoli, a następnie uruchom internetowy interfejs API przy użyciu następujących poleceń:

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Uruchom klienta aplikacji internetowej przy użyciu następujących poleceń:

   cd 2-Authorization\4-call-api-express\App
   npm start
   

3. Otwórz przeglądarkę, a następnie przejdź do http://localhost:3000.

4. Wybierz przycisk Zaloguj się. Zostanie wyświetlony monit o zalogowanie się.

   

5. Na stronie logowania wpisz swój adres e-mail, wybierz pozycję Dalej, wpisz hasło, a następnie wybierz pozycję Zaloguj. Jeśli nie masz konta, wybierz pozycję Nie masz konta? Utwórz jeden link, który uruchamia przepływ rejestracji.

6. Jeśli wybierzesz opcję rejestracji, po wypełnieniu adresu e-mail, jednorazowego kodu dostępu, nowego hasła i dodatkowych szczegółów konta, ukończ cały przepływ rejestracji. Zostanie wyświetlona strona podobna do poniższego zrzutu ekranu. Po wybraniu opcji logowania zostanie wyświetlona podobna strona.

   

Wywoływanie interfejsu API

1. Aby wywołać interfejs API, wybierz link Wyświetl todolist . Zostanie wyświetlona strona podobna do poniższego zrzutu ekranu.

   

2. Manipuluj listą zadań do wykonania, tworząc i usuwając elementy.

Jak to działa

Wywołanie interfejsu API jest wyzwalane za każdym razem, gdy wyświetlasz, dodajesz lub usuwasz zadanie. Za każdym razem, gdy wyzwalasz wywołanie interfejsu API, aplikacja internetowa klienta uzyskuje token dostępu z wymaganymi uprawnieniami (zakresami) w celu wywołania punktu końcowego interfejsu API. Aby na przykład odczytać zadanie, aplikacja internetowa klienta musi uzyskać token dostępu z uprawnieniem/zakresem ToDoList.Read .

Punkt końcowy internetowego interfejsu API musi sprawdzić, czy uprawnienia lub zakresy w tokenie dostępu udostępniane przez aplikację kliencka są prawidłowe. Jeśli token dostępu jest prawidłowy, punkt końcowy odpowiada na żądanie HTTP, w przeciwnym razie odpowiada za pomocą błędu 401 Unauthorized HTTP.

Powiązana zawartość

• Zaloguj użytkowników i wywołaj interfejs API we własnej aplikacji internetowej Node.js.
• Włącz resetowanie hasła.
• Dostosuj domyślne znakowanie.
• Konfigurowanie logowania w usłudze Google.