Přihlášení uživatelů a volání webového rozhraní API v ukázkové Node.js webové aplikace

Tato příručka používá ukázku kódu, která ukazuje, jak přidat ověřování a autorizaci ve webové aplikaci Node.js. Ukázková aplikace se přihlásí k webové aplikaci Node.js, která pak volá rozhraní .NET API. Ověřování a autorizaci povolíte pomocí podrobností o externím tenantovi. Ukázková webová aplikace používá knihovnu MSAL (Microsoft Authentication Library) pro zpracování ověřování pomocí uzlu.

V tomto článku dokončíte následující úlohy:

• Zaregistrujte a nakonfigurujte webové rozhraní API v Centru pro správu Microsoft Entra.

• Aktualizujte ukázkovou webovou aplikaci Node a ASP.NET webové rozhraní API tak, aby používalo podrobnosti o externím tenantovi.

• Spusťte a otestujte ukázkovou webovou aplikaci a rozhraní API.

Požadavky

• Dokončete kroky v části Přihlášení uživatelů a volání rozhraní API v ukázkovém článku Node.js webové aplikace . V tomto článku se dozvíte, jak přihlásit uživatele pomocí ukázkové webové aplikace Node.js.
• Visual Studio Code nebo jiný editor kódu
• Node.js.
• .NET 7.0 nebo novější.
• Externí tenant. Pokud ho chcete vytvořit, zvolte některou z následujících metod:
  • (Doporučeno) Pomocí rozšíření Microsoft Entra Externí ID nastavte externího tenanta přímo v editoru Visual Studio Code.
  • V Centru pro správu Microsoft Entra vytvořte nového externího tenanta .

Registrace webového rozhraní API

V tomto kroku vytvoříte web a registraci aplikace webového rozhraní API a zadáte rozsahy webového rozhraní API.

Registrace aplikace webového rozhraní API

1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.

2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte do externího tenanta z nabídky Adresáře a předplatná.

3. Přejděte k aplikacím> identit>Registrace aplikací.

4. Vyberte + Nová registrace.

5. Na stránce Registrace aplikace , která se zobrazí, zadejte registrační informace vaší aplikace:

   1. V části Název zadejte smysluplný název aplikace, který se zobrazí uživatelům aplikace, například ciam-ToDoList-api.

   2. V části Podporované typy účtů vyberte Pouze účty v tomto organizačním adresáři.

6. Výběrem možnosti Registrovat aplikaci vytvořte.

7. Po dokončení registrace se zobrazí podokno Přehled aplikace. Poznamenejte si ID adresáře (tenanta) a ID aplikace (klienta), které se má použít ve zdrojovém kódu aplikace.

Konfigurace oborů rozhraní API

Toto rozhraní API musí zveřejnit oprávnění, která klient potřebuje získat pro volání rozhraní API:

Rozhraní API musí publikovat minimálně jeden obor, označovaný také jako Delegovaná oprávnění, aby klientské aplikace získaly přístupový token pro uživatele. Pokud chcete obor publikovat, postupujte takto:

1. Na stránce Registrace aplikací vyberte aplikaci API, kterou jste vytvořili (ciam-ToDoList-api) a otevřete její stránku Přehled.

2. V části Spravovat vyberte Zveřejnit rozhraní API.

3. V horní části stránky vedle identifikátoru URI ID aplikace vyberte odkaz Přidat a vygenerujte jedinečný identifikátor URI pro tuto aplikaci.

4. Přijměte navrhovaný identifikátor URI ID aplikace, například api://{clientId}, a vyberte Uložit. Když vaše webová aplikace požádá o přístupový token pro webové rozhraní API, přidá identifikátor URI jako předponu pro každý obor, který definujete pro rozhraní API.

5. V části Obory definované tímto rozhraním API vyberte Přidat obor.

6. Zadejte následující hodnoty, které definují přístup pro čtení k rozhraní API, a pak výběrem možnosti Přidat obor uložte změny:

   Vlastnost	Hodnota
   Název oboru	ToDoList.Read
   Kdo může vyjádřit souhlas	Pouze správci
   Zobrazovaný název souhlasu správce	Čtení seznamu úkolů uživatelů pomocí todoListApi
   Popis souhlasu správce	Umožňuje aplikaci číst seznam úkolů uživatele pomocí todo 'TodoApi'.
   State	Povoleno

7. Znovu vyberte Přidat obor a zadejte následující hodnoty, které definují obor přístupu pro čtení a zápis do rozhraní API. Výběrem možnosti Přidat obor uložte změny:

   Vlastnost	Hodnota
   Název oboru	ToDoList.ReadWrite
   Kdo může vyjádřit souhlas	Pouze správci
   Zobrazovaný název souhlasu správce	Čtení a zápis uživatelů seznamu úkolů pomocí toDoListApi
   Popis souhlasu správce	Povolení čtení a zápisu seznamu úkolů uživatele pomocí toDoApi
   State	Povoleno

8. V části Spravovat vyberte Manifest a otevřete editor manifestu rozhraní API.

9. Nastavit accessTokenAcceptedVersion vlastnost na 2hodnotu .

10. Zvolte Uložit.

Přečtěte si další informace o principu nejnižšího oprávnění při publikování oprávnění pro webové rozhraní API.

Konfigurace rolí aplikací

Rozhraní API musí publikovat minimálně jednu roli aplikace pro aplikace, označované také jako oprávnění aplikace, aby klientské aplikace získaly přístupový token jako vlastní. Oprávnění aplikace jsou typem oprávnění, která by rozhraní API měla publikovat, když chtějí klientským aplikacím umožnit úspěšné ověření jako sebe sama, a nemusí se přihlašovat uživatele. Pokud chcete publikovat oprávnění aplikace, postupujte takto:

1. Na stránce Registrace aplikací vyberte aplikaci, kterou jste vytvořili (například ciam-ToDoList-api), a otevřete její stránku Přehled.

2. V části Spravovat vyberte Role aplikace.

3. Vyberte Vytvořit roli aplikace a pak zadejte následující hodnoty a pak vyberte Použít , aby se změny uložily:

   Vlastnost	Hodnota
   Zobrazované jméno	ToDoList.Read.All
   Povolené typy členů	Aplikace
   Hodnota	ToDoList.Read.All
   Popis	Povolit aplikaci číst seznam úkolů každého uživatele pomocí todoListApi

4. Znovu vyberte Vytvořit roli aplikace a pak zadejte následující hodnoty pro druhou roli aplikace a pak vyberte Použít pro uložení změn:

   Vlastnost	Hodnota
   Zobrazované jméno	ToDoList.ReadWrite.All
   Povolené typy členů	Aplikace
   Hodnota	ToDoList.ReadWrite.All
   Popis	Povolit aplikaci čtení a zápisu seznamu úkolů každého uživatele pomocí toDoApi

Konfigurace volitelných deklarací identity

Volitelnou deklaraci identity idtypu můžete webovému rozhraní API pomoct určit, jestli se jedná o token aplikace nebo token aplikace + uživatelský token. I když můžete použít kombinaci deklarací identity scp a rolí pro stejný účel, použití deklarace identity idtypu je nejjednodušší způsob, jak token aplikace a token uživatele oddělit. Například hodnota této deklarace identity je aplikace , když je token pouze pro aplikaci.

Pomocí kroků v článku Konfigurace volitelných deklarací identity přidejte deklaraci identity idtypu do přístupového tokenu:

• Pro typ tokenu vyberte Přístup.
• V seznamu volitelných deklarací identity vyberte idtyp.

Udělení oprávnění rozhraní API webové aplikaci

Pokud chcete udělit oprávnění rozhraní API klientské aplikace (ciam-client-app), postupujte takto:

1. Na stránce Registrace aplikací vyberte aplikaci, kterou jste vytvořili (například ciam-client-app), a otevřete její stránku Přehled.

2. V části Spravovat vyberte oprávnění rozhraní API.

3. V části Nakonfigurovaná oprávnění vyberte Přidat oprávnění.

4. Vyberte rozhraní API, která moje organizace používá, kartu.

5. V seznamu rozhraní API vyberte rozhraní API, jako je ciam-ToDoList-api.

6. Vyberte možnost Delegovaná oprávnění .

7. V seznamu oprávnění vyberte ToDoList.Read, ToDoList.ReadWrite (v případě potřeby použijte vyhledávací pole).

8. Vyberte tlačítko Přidat oprávnění. V tomto okamžiku jste správně přiřadili oprávnění. Vzhledem k tomu, že se jedná o tenanta zákazníka, nemůžou uživatelé uživatele sami vyjádřit souhlas s těmito oprávněními. Pokud chcete tento problém vyřešit, musíte jako správce udělit souhlas s těmito oprávněními jménem všech uživatelů v tenantovi:

   1. Vyberte Udělit souhlas správce pro <název> vašeho tenanta a pak vyberte Ano.

   2. Vyberte Aktualizovat a pak ověřte, že se pro <název> vašeho tenanta zobrazuje v části Stav pro oba obory.

9. V seznamu Konfigurovaná oprávnění vyberte oprávnění ToDoList.Read a ToDoList.ReadWrite, a pak zkopírujte úplný identifikátor URI oprávnění pro pozdější použití. Úplný identifikátor URI oprávnění vypadá podobně jako api://{clientId}/{ToDoList.Read} api://{clientId}/{ToDoList.ReadWrite}nebo .

Klonování nebo stažení ukázkové webové aplikace a webového rozhraní API

Pokud chcete získat ukázkovou aplikaci, můžete ji buď naklonovat z GitHubu, nebo si ji stáhnout jako soubor .zip.

• Pokud chcete ukázku naklonovat, otevřete příkazový řádek a přejděte do umístění, kam chcete projekt vytvořit, a zadejte následující příkaz:

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

• Stáhněte soubor .zip. Extrahujte ho do cesty k souboru, kde délka názvu je menší než 260 znaků.

Instalace závislostí projektu

1. Otevřete okno konzoly a přejděte do adresáře, který obsahuje ukázkovou aplikaci Node.js/Express:

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

2. Spuštěním následujících příkazů nainstalujte závislosti webové aplikace:

   npm install && npm update
   

Konfigurace ukázkové webové aplikace a rozhraní API

Použití registrace aplikace v ukázce klientské webové aplikace:

1. V editoru kódu otevřete App\authConfig.js soubor.

2. Vyhledejte zástupný symbol:

   • Enter_the_Application_Id_Here a nahraďte ho ID aplikace (klienta), kterou jste zaregistrovali dříve.
   • Enter_the_Tenant_Subdomain_Here a nahraďte ji subdoménou adresáře (tenanta). Pokud je například primární doména vašeho tenanta contoso.onmicrosoft.com, použijte contoso. Pokud nemáte název tenanta, přečtěte si, jak si přečíst podrobnosti o tenantovi.
   • Enter_the_Client_Secret_Here a nahraďte ji hodnotou tajného kódu aplikace, kterou jste zkopírovali dříve.
   • Enter_the_Web_Api_Application_Id_Here a nahraďte ho ID aplikace (klienta) webového rozhraní API, které jste zkopírovali dříve.

Použití registrace aplikace v ukázce webového rozhraní API:

1. V editoru kódu otevřete API\ToDoListAPI\appsettings.json soubor.

2. Vyhledejte zástupný symbol:

   • Enter_the_Application_Id_Here a nahraďte ho ID aplikace (klienta) webového rozhraní API, které jste zkopírovali.
   • Enter_the_Tenant_Id_Here a nahraďte ho ID adresáře (tenanta), které jste zkopírovali dříve.
   • Enter_the_Tenant_Subdomain_Here a nahraďte ji subdoménou adresáře (tenanta). Pokud je například primární doména vašeho tenanta contoso.onmicrosoft.com, použijte contoso. Pokud nemáte název tenanta, přečtěte si, jak si přečíst podrobnosti o tenantovi.

Spuštění a testování ukázkové webové aplikace a rozhraní API

1. Otevřete okno konzoly a pak spusťte webové rozhraní API pomocí následujících příkazů:

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

2. Spusťte klienta webové aplikace pomocí následujících příkazů:

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

3. Otevřete prohlížeč a přejděte na http://localhost:3000.

4. Vyberte tlačítko Přihlásit se. Zobrazí se výzva k přihlášení.

   

5. Na přihlašovací stránce zadejte svoji e-mailovou adresu, vyberte Další, zadejte heslo a pak vyberte Přihlásit se. Pokud účet nemáte, vyberte Možnost Žádný účet? Vytvořte jeden odkaz, který spustí tok registrace.

6. Pokud zvolíte možnost registrace po vyplnění e-mailu, jednorázového hesla, nového hesla a dalších podrobností účtu, dokončíte celý tok registrace. Zobrazí se stránka podobná následujícímu snímku obrazovky. Pokud zvolíte možnost přihlášení, zobrazí se podobná stránka.

   

Volání rozhraní API

1. Pokud chcete volat rozhraní API, vyberte odkaz Zobrazit seznam úkolů . Zobrazí se stránka podobná následujícímu snímku obrazovky.

   

2. Manipulace se seznamem úkolů vytvořením a odebráním položek

Jak to funguje

Každé zobrazení, přidání nebo odebrání úlohy aktivujete volání rozhraní API. Pokaždé, když aktivujete volání rozhraní API, klientská webová aplikace získá přístupový token s požadovanými oprávněními (obory) pro volání koncového bodu rozhraní API. Například ke čtení úlohy musí klientská webová aplikace získat přístupový token s oprávněním nebo oborem ToDoList.Read .

Koncový bod webového rozhraní API musí zkontrolovat, jestli jsou oprávnění nebo obory v přístupovém tokenu poskytované klientskou aplikací platné. Pokud je přístupový token platný, koncový bod odpoví na požadavek HTTP, jinak odpoví chybou 401 Unauthorized HTTP.

Související obsah

• Přihlaste se uživatele a volejte rozhraní API ve vlastní webové aplikaci Node.js.
• Povolte resetování hesla.
• Přizpůsobte výchozí branding.
• Nakonfigurujte přihlášení pomocí Googlu.