Szybki start — logowanie użytkowników i wywoływanie internetowego interfejsu API w przykładowej aplikacji internetowej Node.js

Dotyczy: Najemcy Workforce Najemcy zewnętrzni (dowiedzieć się więcej)

Z tego przewodnika Szybki start dowiesz się, jak logować użytkowników i wywoływać internetowy interfejs API z aplikacji internetowej Node.js w dzierżawie zewnętrznej. Przykładowa aplikacja wywołuje interfejs API platformy .NET. Przykładowa aplikacja internetowa używa biblioteki Microsoft Authentication Library (MSAL) dla środowiska Node do obsługi uwierzytelniania.

Warunki wstępne

• Wykonaj kroki i wymagania wstępne w Szybki start: logowanie użytkowników w przykładowej aplikacji internetowej artykule. W tym artykule pokazano, jak logować użytkowników przy użyciu przykładowej aplikacji internetowej Node.js.
• Najemca zewnętrzny. Aby go utworzyć, wybierz jedną z następujących metod:
  • (Zalecane) Użyj rozszerzenia Microsoft Entra External ID, aby skonfigurować dzierżawcę zewnętrznego bezpośrednio w programie Visual Studio Code.
  • Utwórz nowego tenant zewnętrznego w centrum administracyjnym Microsoft Entra.
• Zarejestruj nową aplikację dla internetowego interfejsu API w centrum administracyjnym firmy Microsoft Entra skonfigurowaną tylko dla kont w tym katalogu organizacyjnym. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji . Zapisz następujące wartości na stronie Przegląd aplikacji do późniejszego użycia:
  • Identyfikator aplikacji (klienta)
  • Identyfikator katalogu (klienta)
• Visual Studio Code lub inny edytor kodu.
• Node.js.
• .NET 7.0 lub nowszym.

Konfigurowanie zakresów i ról interfejsu API

Rejestrując web API, należy skonfigurować zakresy API, aby zdefiniować uprawnienia, o które aplikacja kliencka może wystąpić, aby uzyskać dostęp do web API. Ponadto należy skonfigurować role aplikacji, aby określić role dostępne dla użytkowników lub aplikacji i udzielić niezbędnych uprawnień interfejsu API do aplikacji internetowej, aby umożliwić jej wywoływanie internetowego interfejsu API.

Konfigurowanie zakresów interfejsu API

Interfejs API musi opublikować co najmniej jeden zakres, nazywany również uprawnieniami delegowanymi , 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ądzajwybierz pozycję Uwidaczniaj interfejs API.

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

4. Zaakceptuj proponowany URI aplikacji, taki jak api://{clientId}, a następnie wybierz opcję Zapisz. Gdy aplikacja internetowa żąda tokenu dostępu dla API, dodaje URI jako prefiks dla każdego zakresu zdefiniowanego dla 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 odczytu do interfejsu API, a następnie wybierz Dodaj zakres, aby zapisać zmiany.

   Własność	Wartość
   Nazwa zakresu	ToDoList.Read
   Kto może wyrazić zgodę	Tylko dla administratorów
   Nazwa wyświetlana zgody administratora	Odczytaj listę zadań użytkowników przy użyciu 'TodoListApi'
   Opis zgody administratora	Zezwól aplikacji na odczytywanie listy zadań użytkownika przy użyciu"TodoListApi".
   Stan	włączone

7. Wybierz ponownie Dodaj zakres, a następnie wprowadź następujące wartości definiujące zakres dostępu do odczytu i zapisu w interfejsie API. Wybierz Dodaj zakres, aby zapisać zmiany:

   Własność	Wartość
   Nazwa zakresu	ToDoList.ReadWrite
   Kto może wyrazić zgodę	Tylko dla administratorów
   Nazwa wyświetlana zgody administratora	odczytuj i zapisuj listę zadań użytkowników za pomocą "ToDoListApi"
   Opis zgody administratora	Zezwól aplikacji na odczyt i zapis listy zadań użytkownika przy użyciu "ToDoListApi"
   Stan	włączone

Dowiedz się więcej na temat zasady najniższych uprawnień podczas publikowania uprawnień dla internetowego interfejsu API.

Konfigurowanie ról aplikacji

Interfejs API musi opublikować co najmniej jedną rolę aplikacji, znaną również jako uprawnienia aplikacji , aby aplikacje klienckie mogły uzyskiwać token dostępu w swoim imieniu. Uprawnienia aplikacji to typ uprawnień, które interfejsy API powinny publikować, gdy chcą umożliwić aplikacjom klienckim pomyślne uwierzytelnienie się we własnym imieniu, bez potrzeby logowania użytkowników. Aby opublikować zezwolenie aplikacji, wykonaj następujące kroki:

1. Na stronie rejestracji aplikacji wybierz utworzoną aplikację (na przykład ciam-ToDoList-api), aby otworzyć jej stronę Przegląd.

2. W obszarze Zarządzajwybierz 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łasność	Wartość
   Nazwa wyświetlana	ToDoList.Read.All
   Dozwolone typy członków	aplikacje
   Wartość	ToDoList.Read.All
   Opis	Zezwól aplikacji na odczytywanie listy zadań każdego użytkownika przy użyciu "TodoListApi"
   Czy chcesz aktywować rolę tej aplikacji?	Zachowaj to zaznaczone

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łasność	Wartość
   Nazwa wyświetlana	ToDoList.ReadWrite.All
   Dozwolone typy członków	aplikacje
   Wartość	ToDoList.ReadWrite.All
   Opis	"Zezwól aplikacji na odczytywanie i zapisywanie list zadań wszystkich użytkowników przy użyciu 'ToDoListApi'"
   Czy chcesz aktywować rolę tej aplikacji?	Zachowaj to zaznaczone

Konfigurowanie opcjonalnych oświadczeń

Możesz dodać opcjonalne oświadczenie idtyp, aby ułatwić API sieci Web określenie, czy token jest tokenem aplikacji , czy tokenem aplikacji + użytkownika . Chociaż można użyć kombinacji oświadczeń scp i ról w tym samym celu, użycie oświadczenia idtyp jest najprostszym sposobem na rozróżnienie tokenu aplikacji od tokenu aplikacji + użytkownika. Na przykład wartość tego oświadczenia to apki, gdy token jest tokenem wyłącznie dla aplikacji.

Wykonaj kroki opisane w artykule Konfigurowanie opcjonalnych atrybutów, aby dodać atrybut idtyp w tokenie dostępu:

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

Przyznaj uprawnienia API aplikacji webowej

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

1. Na stronie Rejestracje aplikacji wybierz aplikację, którą utworzyłeś (taką jak ciam-client-app), aby otworzyć jej stronę Przegląd.

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

3. W obszarze Skonfigurowane uprawnieniawybierz pozycję Dodaj uprawnienie.

4. Na karcie Interfejsy API używane przez moją organizację wybierz.

5. Na liście API wybierz API, takie jak ciam-ToDoList-api.

6. Wybierz opcję uprawnienia delegowane .

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

8. Wybierz przycisk Dodaj uprawnienia. Na tym etapie poprawnie przydzieliłeś już uprawnienia. Jednak ponieważ dzierżawca jest najemcą klienta, użytkownicy końcowi nie mogą samodzielnie 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 Udziel zgody administratora dla <twojej dzierżawy>, a następnie kliknij Tak.

   2. Wybierz opcję Odśwież, a następnie sprawdź, czy udzielono dla <nazwy dzierżawy> pojawia się przy Stan dla obu zakresów.

9. Z listy Skonfigurowane uprawnienia wybierz ToDoList.Read i ToDoList.ReadWrite uprawnień, po jednym naraz, a następnie skopiuj pełny identyfikator URI uprawnienia do późniejszego użycia. Pełny identyfikator URI uprawnień przypomina 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ładowej aplikacji webowej klienta:

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

2. Znajdź symbol zastępczy:

   • Zastąp Enter_the_Application_Id_Here identyfikatorem aplikacji klienta, który zarejestrowałeś wcześniej. Aplikacja kliencka to ta, którą zarejestrowałeś w wymogach wstępnych.
   • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawcy jest contoso.onmicrosoft.com, użyj contoso. Jeśli nie masz nazwy dzierżawcy, dowiedz się, jak sprawdzać szczegóły dzierżawcy.
   • Enter_the_Client_Secret_Here i zastąp to wartością tajną aplikacji, skopiowaną wcześniej.
   • Enter_the_Web_Api_Application_Id_Here i zastąp go identyfikatorem klienta (ID aplikacji) interfejsu API sieci Web, który został skopiowany wcześniej w ramach wymagań wstępnych.

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

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

2. Znajdź symbol zastępczy:

   • Enter_the_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) skopiowanego internetowego interfejsu API. Aplikacja API to taka, którą zarejestrowano wcześniej jako część wymagań wstępnych.
   • Enter_the_Tenant_Id_Here i zastąp go wcześniej skopiowanym identyfikatorem katalogu (dzierżawy).
   • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawcy jest contoso.onmicrosoft.com, użyj contoso. Jeśli nie masz nazwy dzierżawcy, dowiedz się, jak sprawdzać szczegóły dzierżawcy.

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 install
   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 adres e-mail , wybierz pozycję Dalej, wpisz hasło , a następnie wybierz pozycję Zaloguj się. 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łaj API

1. Aby wywołać interfejs API, wybierz link Pokaż swoją listę zadań. Zostanie wyświetlona strona podobna do poniższego zrzutu ekranu.

   

2. Manipuluj listą to-do, 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 HTTP 401 Unauthorized.

Powiązana zawartość

• Samouczek: zabezpiecz internetowe API platformy ASP.NET Core zarejestrowane w zewnętrznym tenancie.