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

platí pro: nájemníci pracovních sil externí nájemníci (Další informace).

V tomto rychlém startu se dozvíte, jak přihlásit uživatele a volat API z webové aplikace Node.js ve vaší externí doméně. Ukázková aplikace volá .NET API. Ukázková webová aplikace používá knihovnu MSAL (Microsoft Authentication Library) pro Node.js ke zpracování ověřování.

Požadavky

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

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 minimálně na úrovni vývojáře 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 na Identity>Applications>App registrations.

4. Vyberte + Nová registrace.

5. Na stránce Zaregistrovat aplikaci, 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. Vyberte Registr a vytvořte aplikaci.

7. Po dokončení registrace se zobrazí podokno Přehled aplikace. Poznamenejte ID adresáře (tenanta) a ID aplikace (klient), které se mají 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 úspěšně 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), abyste otevřeli její stránku Přehled.

2. V části Spravovatvyberte Zpřístupnit rozhraní API.

3. V horní části stránky vedle Application ID URIvyberte odkaz Přidat pro vygenerování jedinečného URI pro tuto aplikaci.

4. Přijměte navrhovaný identifikátor URI 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 APIvyberte Přidat obor.

6. Zadejte následující hodnoty, které definují přístup pro čtení k API, a pak vyberte Přidat obor pro uložení změn.

   Vlastnost	Hodnota
   Název oboru	ToDoList.Read
   Kdo může souhlasit	pouze správci
   Zobrazované jméno souhlasu správce	Přečíst seznam úkolů uživatelů pomocí TodoListApi
   Popis souhlasu správce	Povolit aplikaci číst uživatelův seznam úkolů pomocíTodoListApi.
   Stát	Povoleno

7. Vyberte Znovu přidat obor a zadejte následující hodnoty, které definují obor přístupu pro čtení a zápis do rozhraní API. Vyberte Přidat oboru a uložte provedené změny:

   Vlastnost	Hodnota
   Název oboru	toDoList.ReadWrite
   Kdo může souhlasit	pouze správci
   Zobrazované jméno souhlasu správce	Číst a zapisovat seznam úkolů uživatelů pomocí ToDoListApi
   Popis souhlasu správce	Povolit aplikaci číst a zapisovat seznam úkolů uživatele pomocí ToDoListApi
   Stát	Povoleno

8. V části Spravovatvyberte Manifest a otevřete Editor manifestu rozhraní API.

9. Nastavte vlastnost accessTokenAcceptedVersion na 2.

10. Vyberte 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čovanou také jako oprávnění aplikace, aby klientské aplikace získaly přístupový token samy za sebe. Oprávnění aplikace jsou typem oprávnění, která by rozhraní API měla publikovat, když chtějí umožnit klientským aplikacím úspěšně se autentizovat samy za sebe a nemusí 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), abyste otevřeli její stránku Přehled.

2. V části Spravovatvyberte role aplikace.

3. Vyberte Vytvořit roli aplikace, zadejte následující hodnoty, a pak vyberte Použít, aby uložil vaše změny.

   Vlastnost	Hodnota
   Zobrazovaný název	SeznamÚkolů.Číst.Vše
   Povolené typy členů	Aplikace
   Hodnota	ToDoList.Číst.Vše
   Popis	Povolit aplikaci číst pomocí TodoListApi seznam úkolů každého uživatele

4. Znovu vyberte Vytvořit roli aplikace. Poté zadejte následující hodnoty pro druhou roli aplikace a následně vyberte Použít, abyste uložili změny.

   Vlastnost	Hodnota
   Zobrazovaný název	ToDoList.ReadWrite.All
   Povolené typy členů	aplikací
   Hodnota	ToDoList.ReadWrite.All
   Popis	Povolit aplikaci čtení a zápisu seznamů úkolů všech uživatelů pomocí 'ToDoListApi'

Konfigurace volitelných nároků

Můžete přidat idtyp volitelnou deklaraci identity, která webovému rozhraní API pomůže určit, jestli je tokenem aplikace nebo tokenem aplikace + token uživatele. I když můžete použít kombinaci scp a rolí deklarací identity pro stejný účel, použití idtypu deklarace identity je nejjednodušší způsob, jak odlišit token aplikace od tokenu aplikace + uživatele. Například hodnota této deklarace identity je aplikace, když je token jen pro aplikaci.

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

• Pro typ tokenu vyberte Access.
• Ze seznamu volitelných nároků vyberte idtyp.

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

Pokud chcete klientské aplikaci udělit oprávnění rozhraní API (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 tak její stránku Přehled.

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

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

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

5. V seznamu rozhraní API vyberte například rozhraní API 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, nemohou koncoví uživatelé sami udělit 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 Aktualizovata ověřte, že uděleno pro <název vašeho tenanta,> se zobrazí v části Stav pro oba obory.

9. V seznamu Konfigurovaná oprávnění vyberte ToDoList.Read a oprávnění ToDoList.ReadWrite, po jednom a 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} nebo api://{clientId}/{ToDoList.ReadWrite}.

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áhnout soubor .zip. Extrahujte ho do cesty k souboru, kde délka názvu je menší než 260 znaků.

Nainstalujte závislosti 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 soubor App\authConfig.js.

2. Vyhledejte zástupný symbol:

   • Enter_the_Application_Id_Here a nahraďte ho za 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, naučte se, jak [přečíst podrobnosti o tenantovi](../external-id/customers/how-to-create-external-tenant-portal.md#get-the-external-tenant-details).
   • 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.

Chcete-li použít registraci aplikace v ukázce webového rozhraní API:

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

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 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 e-mailovou adresu, vyberte Další, zadejte Hesloa pak vyberte Přihlásit se. Pokud účet nemáte, vyberte Žá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.

   

Rozhraní API pro volání

1. Chcete-li zavolat rozhraní API, vyberte odkaz Zobrazit váš seznam úkolů. Zobrazí se stránka podobná následujícímu snímku obrazovky.

   

2. Manipulujte se seznamem to-do 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í 401 Unauthorized chybou HTTP.

Související obsah

• Kurz : Zabezpečení webového rozhraní API ASP.NET Core zaregistrovaného v externím tenantovi.