Wywoływanie interfejsu API w przykładowej aplikacji demona Node.js

  • Artykuł

W tym artykule użyto przykładowej aplikacji demona Node.js, aby pokazać, jak aplikacja demona uzyskuje token w celu wywołania internetowego interfejsu API. Microsoft Entra identyfikator dla klientów chroni internetowy interfejs API.

Aplikacja demona uzyskuje token w imieniu samego siebie (nie w imieniu użytkownika). Użytkownicy nie mogą wchodzić w interakcje z aplikacją demona, ponieważ wymaga własnej tożsamości. Ten typ aplikacji żąda tokenu dostępu przy użyciu tożsamości aplikacji i przedstawienia identyfikatora aplikacji, poświadczeń (hasła lub certyfikatu) oraz identyfikatora URI aplikacji do identyfikatora zewnętrznego.

Aplikacja demona używa standardowego przyznawania poświadczeń klienta OAuth 2.0. Aby uprościć proces uzyskiwania tokenu, przykład używany w tym artykule korzysta z biblioteki Microsoft Authentication Library for Node (MSAL Node).

Wymagania wstępne

Rejestrowanie aplikacji demona i internetowego interfejsu API

W tym kroku utworzysz demona 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 Microsoft Entra co najmniej jako deweloper aplikacji.

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

  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 dla użytkowników 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 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 samodzielnie. 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 muszą 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ść Wartość
    Nazwa wyświetlana ToDoList.Read.All
    Dozwolone typy elementów członkowskich 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ść Wartość
    Nazwa wyświetlana ToDoList.ReadWrite.All
    Dozwolone typy elementów członkowskich 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ń

Tokeny zwracane przez tożsamość firmy Microsoft są mniejsze, aby zapewnić optymalną wydajność przez klientów, którzy ich żądają. W związku z tym kilka oświadczeń nie jest już obecnych w tokenie domyślnie i musi zostać poproszonych o konkretne oświadczenia dla poszczególnych aplikacji. W przypadku tej aplikacji dołącz opcjonalne oświadczenie idtyp , aby ułatwić interfejsowi API sieci Web określenie, czy token jest tokenem aplikacji, czy tokenem aplikacji i tokenem użytkownika. Mimo że kombinacja oświadczeń scp i ról może być używana w tym samym celu, użycie oświadczenia idtyp jest najprostszym sposobem przekazania tokenu aplikacji i tokenu użytkownika od siebie. Na przykład wartość tego oświadczenia to aplikacja , gdy token jest tokenem tylko dla aplikacji.

Aby skonfigurować opcjonalne oświadczenie idtypu , wykonaj następujące kroki:

  1. W obszarze Zarządzanie wybierz pozycję Konfiguracja tokenu.

  2. Wybierz pozycję Dodaj opcjonalne oświadczenie.

  3. W obszarze Typ tokenu wybierz pozycję Dostęp.

  4. Wybierz opcjonalny typ oświadczenia.

  5. Wybierz opcję Dodaj, aby zapisać zmiany.

Rejestrowanie aplikacji demona

Aby umożliwić aplikacji logowanie użytkowników przy użyciu Microsoft Entra, Microsoft Entra identyfikator dla klientów musi być świadomy tworzonej aplikacji. Rejestracja aplikacji ustanawia relację zaufania między aplikacją a Microsoft Entra. Podczas rejestrowania aplikacji identyfikator zewnętrzny generuje unikatowy identyfikator znany jako identyfikator aplikacji (klienta) — wartość używana do identyfikowania aplikacji podczas tworzenia żądań uwierzytelniania.

W poniższych krokach pokazano, jak zarejestrować aplikację w centrum administracyjnym Microsoft Entra:

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

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

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

  4. Wybierz pozycję + Nowa rejestracja.

  5. Na wyświetlonej stronie Rejestrowanie aplikacji ;

    1. Wprowadź zrozumiałą nazwę aplikacji wyświetlaną dla użytkowników aplikacji, na przykład ciam-client-app.
    2. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.

  6. Wybierz pozycję Zarejestruj.

  7. Po pomyślnej rejestracji zostanie wyświetlone okienko Przegląd aplikacji. Zapisz identyfikator aplikacji (klienta) do użycia w kodzie źródłowym aplikacji.

Tworzenie wpisu tajnego klienta

Utwórz klucz tajny klienta dla zarejestrowanej aplikacji. Aplikacja używa klucza tajnego klienta, aby udowodnić swoją tożsamość, gdy żąda tokenów.

  1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-client-app), aby otworzyć stronę Przegląd.
  2. W obszarze Zarządzanie wybierz pozycję Wpisy tajne certyfikatów&.
  3. Wybierz pozycję Nowy klucz tajny klienta.
  4. W polu Opis wprowadź opis wpisu tajnego klienta (na przykład wpis tajny klienta aplikacji ciam).
  5. W obszarze Wygasa wybierz czas trwania, dla którego wpis tajny jest prawidłowy (zgodnie z regułami zabezpieczeń organizacji), a następnie wybierz pozycję Dodaj.
  6. Zapisz wartość wpisu tajnego. Ta wartość zostanie użyta do konfiguracji w późniejszym kroku.

Uwaga

Wartość wpisu tajnego nie będzie ponownie wyświetlana i nie jest pobierana w żaden sposób, po opuszczeniu strony Certyfikaty i wpisy tajne , dlatego upewnij się, że został zarejestrowany.
W przypadku zwiększonych zabezpieczeń rozważ użycie certyfikatów zamiast wpisów tajnych klienta.

Udzielanie uprawnień interfejsu API do aplikacji demona

  1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację, taką jak ciam-client-app.

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

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

  4. Wybierz kartę Moje interfejsy API .

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

  6. Wybierz opcję Uprawnienia aplikacji . Wybieramy tę opcję, gdy aplikacja loguje się jako sama, a nie użytkownicy.

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

  8. Wybierz przycisk Dodaj uprawnienia .

  9. W tym momencie uprawnienia zostały przypisane poprawnie. Jednak ponieważ aplikacja demona nie zezwala użytkownikom na interakcję z nią, użytkownicy 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 uprawnień jest wyświetlana wartość Udzielono dla <nazwy> dzierżawy.

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

Aby uzyskać przykładowy kod aplikacji internetowej, możesz wykonać jedno z następujących zadań:

  • Pobierz plik .zip lub sklonuj przykładową aplikację internetową z usługi GitHub, uruchamiając następujące polecenie:

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

Jeśli zdecydujesz się pobrać plik .zip , wyodrębnij przykładowy plik aplikacji do folderu, w którym całkowita długość ścieżki wynosi 260 lub mniej znaków.

Instalowanie zależności projektu

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

        cd 2-Authorization\3-call-api-node-daemon\App

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

        npm install && npm update

Konfigurowanie przykładowej aplikacji demona 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 demona.

    • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Directory (tenant). Jeśli na przykład domena podstawowa dzierżawy to contoso.onmicrosoft.com, użyj polecenia contoso. Jeśli nie masz 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 demona.

    • Enter_the_Web_Api_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) skopiowanego wcześniej interfejsu API sieci Web.

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 zastąp go identyfikatorem aplikacji (klienta) skopiowanego internetowego interfejsu API.

    • Enter_the_Tenant_Id_Here zastąp go skopiowanymi wcześniej identyfikatorami katalogu (dzierżawy).

    • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Directory (tenant). Jeśli na przykład domena podstawowa dzierżawy to contoso.onmicrosoft.com, użyj polecenia contoso. Jeśli nie masz nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.

Uruchamianie i testowanie przykładowej aplikacji demona 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\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

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

        2-Authorization\3-call-api-node-daemon\App
     node . --op getToDos

Jeśli aplikacja demona i internetowy interfejs API zostały pomyślnie uruchomione, w oknie konsoli powinien zostać wyświetlony kod podobny do poniższej tablicy JSON.

{
    id: 1,
    owner: '3e8....-db63-43a2-a767-5d7db...',
    description: 'Pick up grocery'
},
{
    id: 2,
    owner: 'c3cc....-c4ec-4531-a197-cb919ed.....',
    description: 'Finish invoice report'
},
{
    id: 3,
    owner: 'a35e....-3b8a-4632-8c4f-ffb840d.....',
    description: 'Water plants'
}

Jak to działa

Aplikacja Node.js używa poświadczeń klienta OAuth 2.0 w celu uzyskania tokenu dostępu dla siebie, a nie dla użytkownika. Token dostępu, którego żąda aplikacja, zawiera uprawnienia reprezentowane jako role. Przepływ poświadczeń klienta używa tego zestawu uprawnień zamiast zakresów użytkownika dla tokenów aplikacji. Te uprawnienia aplikacji zostały ujawnione wcześniej w internetowym interfejsie API, a następnie przyznano je aplikacji demona.

Po stronie interfejsu API internetowy interfejs API musi sprawdzić, czy token dostępu ma wymagane uprawnienia (uprawnienia aplikacji). Internetowy interfejs API nie może zaakceptować tokenu dostępu, który nie ma wymaganych uprawnień.

Dostęp do danych

Punkt końcowy internetowego interfejsu API powinien być przygotowany do akceptowania wywołań zarówno od użytkowników, jak i aplikacji. W związku z tym powinna mieć możliwość odpowiedniego reagowania na każde żądanie. Na przykład wywołanie od użytkownika za pośrednictwem delegowanych uprawnień/zakresów odbiera listę zadań do wykonania użytkownika. Z drugiej strony wywołanie z aplikacji za pośrednictwem uprawnień/ról aplikacji może otrzymać całą listę zadań do wykonania. Jednak w tym artykule wykonujemy tylko wywołanie aplikacji, więc nie musieliśmy konfigurować delegowanych uprawnień/zakresów.

Następne kroki