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

  • Článek

Tento návod používá ukázkovou Node.js webové aplikace, která vám ukáže, jak přidat ověřování a autorizaci. Ukázková aplikace přihlašuje uživatele k Node.js webové aplikaci, která pak volá rozhraní API .NET. Ověřování a autorizaci povolíte pomocí id Microsoft Entra pro podrobnosti tenanta zákazníka. Ukázková webová aplikace používá knihovnu Microsoft Authentication Library (MSAL) pro node ke zpracování ověřování.

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

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

  • Zaregistrujte a nakonfigurujte webovou aplikaci klienta v centru pro správu Microsoft Entra.

  • V centru pro správu Microsoft Entra vytvořte tok uživatelů registrace a přihlašování a přidružte k němu klientskou webovou aplikaci.

  • Aktualizujte ukázkovou webovou aplikaci Node a ASP.NET webové rozhraní API tak, aby pro podrobnosti tenanta zákazníků používalo vaše externí ID.

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

Požadavky

Registrace webové aplikace a webového rozhraní API

V tomto kroku vytvoříte registraci webových aplikací a webových rozhraní API a zadáte obory webového rozhraní API.

Registrace aplikace webového rozhraní API

  1. Přihlaste se k centru pro správu Microsoft Entra jako aspoň vývojář aplikací.

  2. Pokud máte přístup k více tenantům, přepněte na tenanta zákazníka pomocí filtru Adresáře a předplatná v horní nabídce.

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

  4. Vyberte + Nová registrace.

  5. Na stránce Zaregistrovat aplikaci , která se zobrazí, zadejte informace o registraci 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 Účty pouze 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 mají použít ve zdrojovém kódu aplikace.

Konfigurace oborů rozhraní API

Toto rozhraní API musí zpřístupnit oprávnění, která klient musí 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. Chcete-li publikovat obor, 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 identifikátor URI, který je pro tuto aplikaci jedinečný.

  4. Přijměte navrhovaný identifikátor URI ID aplikace, například api://{clientId}, a vyberte Uložit. Když 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ý pro rozhraní API definujete.

  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 vyberte Přidat obor , aby se změny uložily:

    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 Povolte aplikaci čtení seznamu úkolů uživatele pomocí todoListApi.
    Stav Povoleno

  7. Znovu vyberte Přidat obor a zadejte následující hodnoty, které definují obor přístupu pro čtení a zápis rozhraní API. Vyberte Přidat obor a 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 seznamu úkolů uživatelů pomocí toDoListApi
    Popis souhlasu správce Povolit aplikaci čtení a zápis seznamu úkolů uživatele pomocí toDoListApi
    Stav Povoleno

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

  9. Vlastnost nastavte accessTokenAcceptedVersion na 2.

  10. Vyberte Uložit.

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

Konfigurace aplikačních rolí

Rozhraní API musí publikovat minimálně jednu roli aplikace, která se označuje také jako oprávnění aplikace, aby klientské aplikace získaly přístupový token jako samy. Oprávnění aplikací 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 oni sami a nepotřebují přihlašovat uživatele. Chcete-li 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 aplikací.

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

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

  4. Znovu vyberte Vytvořit aplikační roli , zadejte následující hodnoty pro druhou aplikační roli a pak vyberte Použít , aby se změny uložily:

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

Konfigurace volitelných deklarací identity

Tokeny vrácené identitou Microsoftu se udržují menší, aby se zajistil optimální výkon ze strany klientů, kteří je požadují. V důsledku toho se v tokenu ve výchozím nastavení několik deklarací identity nenachází a je potřeba je požádat o konkrétní žádost pro jednotlivé aplikace. Pro tuto aplikaci zahrnete volitelnou deklaraci identity idtyp , která webovému rozhraní API pomůže určit, jestli je tokenem aplikace nebo tokenem app+user. I když se ke stejnému účelu dá použít kombinace deklarací identity scp a rolí , je použití deklarace identity idtyp nejjednodušším způsobem, jak token aplikace a token app+user oddělit. Například hodnota této deklarace identity je app , pokud je token tokenem pouze pro aplikaci.

Ke konfiguraci volitelné deklarace identity idtyp použijte následující postup:

  1. V části Spravovat vyberte Konfigurace tokenu.

  2. Vyberte Přidat volitelnou deklaraci identity.

  3. V části Typ tokenu zvolte Přístup.

  4. Vyberte volitelný idtyp deklarace identity.

  5. Vyberte Přidat a uložte změny.

Registrace webové aplikace

Pokud chcete aplikaci umožnit přihlašování uživatelů pomocí Microsoft Entra, musí Microsoft Entra ID pro zákazníky vědět o aplikaci, kterou vytvoříte. Registrace aplikace vytvoří vztah důvěryhodnosti mezi aplikací a Microsoft Entra. Když zaregistrujete aplikaci, externí ID vygeneruje jedinečný identifikátor označovaný jako ID aplikace (klienta), což je hodnota používaná k identifikaci vaší aplikace při vytváření žádostí o ověření.

Následující postup ukazuje, jak zaregistrovat aplikaci v Centru pro správu Microsoft Entra:

  1. Přihlaste se k centru pro správu Microsoft Entra jako aspoň vývojář aplikací.

  2. Pokud máte přístup k více tenantům, přepněte na tenanta zákazníka pomocí filtru Adresáře a předplatná v horní nabídce.

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

  4. Vyberte + Nová registrace.

  5. Na stránce Zaregistrovat aplikaci , která se zobrazí;

    1. Zadejte smysluplný název aplikace, který se zobrazí uživatelům aplikace, například ciam-client-app.
    2. V části Podporované typy účtů vyberte Účty pouze v tomto organizačním adresáři.

  6. Vyberte Zaregistrovat.

  7. Po úspěšné registraci se zobrazí podokno Přehled aplikace. Poznamenejte si ID aplikace (klienta), které se má použít ve zdrojovém kódu aplikace.

Pokud chcete zadat typ aplikace pro registraci aplikace, postupujte takto:

  1. V části Spravovat vyberte Ověřování.
  2. Na stránce Konfigurace platformy vyberte Přidat platformu a pak vyberte možnost Web .
  3. Jako identifikátory URI pro přesměrování zadejte . http://localhost:3000/auth/redirect
  4. Vyberte Konfigurovat a uložte změny.
  5. Na stránce Konfigurace platformy v části Web vyberte Přidat identifikátor URI a pak zadejte http://localhost:3000/
  6. Vyberte Uložit , aby se změny uložily, a ujistěte se, že jsou uvedené oba identifikátory URI.

Vytvoření tajného klíče klienta

Vytvořte tajný klíč klienta pro zaregistrovanou aplikaci. Aplikace používá tajný klíč klienta k prokázání své identity při žádosti o tokeny.

  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 Tajné kódy certifikátů&.
  3. Vyberte Nový tajný klíč klienta.
  4. Do pole Popis zadejte popis tajného klíče klienta (například ciam app secret).
  5. V části Konec platnosti vyberte dobu platnosti tajného kódu (podle pravidel zabezpečení vaší organizace) a pak vyberte Přidat.
  6. Poznamenejte si hodnotu tajného kódu. Tuto hodnotu použijete ke konfiguraci v pozdějším kroku.

Poznámka

Hodnota tajného kódu se po přechodu ze stránky Certifikáty a tajné kódy znovu nezobrazí a není možné ji žádným způsobem načíst, proto ji nezapomeňte zaznamenat.
Kvůli rozšířenému zabezpečení zvažte použití certifikátů místo tajných klíčů klientů.

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 kartu Rozhraní API Microsoftu .

  5. V části Běžně používaná rozhraní API Microsoftu vyberte Microsoft Graph.

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

  7. V části Vybrat oprávnění vyhledejte a vyberte oprávnění openid i offline_access .

  8. Vyberte tlačítko Přidat oprávnění .

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

  10. Vyberte kartu Moje rozhraní API .

  11. V seznamu rozhraní API vyberte rozhraní API, například ciam-ToDoList-api.

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

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

  14. Vyberte tlačítko Přidat oprávnění .

  15. V tomto okamžiku jste oprávnění přiřadili správně. Vzhledem k tomu, že tenant je tenantem zákazníka, nemůžou s těmito oprávněními souhlasit samotní uživatelé tohoto uživatele. 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> tenanta a pak vyberte Ano.

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

  16. V seznamu Konfigurovaná oprávnění vyberte jednu po druhé 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á nějak podobně jako api://{clientId}/{ToDoList.Read} nebo api://{clientId}/{ToDoList.ReadWrite}.

Vytvoření toku uživatele

Postupujte podle těchto kroků a vytvořte tok uživatelů, pomocí které se zákazník může přihlásit nebo zaregistrovat k aplikaci.

  1. Přihlaste se k centru pro správu Microsoft Entra jako alespoň správce toku uživatelů s externím ID.

  2. Pokud máte přístup k více tenantům, přepněte na tenanta zákazníka pomocí filtru Adresáře a předplatná v horní nabídce.

  3. Přejděte naToky uživatelůIdentita>externích identit>.

  4. Vyberte + Nový tok uživatele.

  5. Na stránce Vytvořit :

    1. Zadejte Název toku uživatele, například SignInSignUpSample.

    2. V seznamu Zprostředkovatelé identity vyberte Email Účty. Tento zprostředkovatel identity umožňuje uživatelům přihlášení nebo registraci pomocí jejich e-mailové adresy.

      Poznámka

      Další zprostředkovatelé identity tady budou uvedeni až poté, co s nimi nastavíte federaci. Pokud například nastavíte federaci s Googlem nebo Facebookem, budete tady moct vybrat tyto další zprostředkovatele identity.

    3. V části Email účty můžete vybrat jednu ze dvou možností. Pro účely tohoto kurzu vyberte Email s heslem.

      • Email s heslem: Umožňuje novým uživatelům zaregistrovat se a přihlásit se pomocí e-mailové adresy jako přihlašovacího jména a hesla jako přihlašovacích údajů.

      • Email jednorázové heslo: Umožňuje novým uživatelům zaregistrovat se a přihlásit se pomocí e-mailové adresy jako přihlašovacího jména a e-mailového jednorázového hesla jako přihlašovacích údajů.

        Poznámka

        Email jednorázové heslo musí být povolené na úrovni tenanta (Všichni zprostředkovatelé> identity Email jednorázové heslo), aby tato možnost byla dostupná na úrovni toku uživatele.

    4. V části Atributy uživatele zvolte atributy, které chcete od uživatele při registraci shromáždit. Když vyberete Zobrazit více, můžete zvolit atributy a deklarace identity pro zemi/oblast, Zobrazované jméno a PSČ. Vyberte OK. (Uživatelům se zobrazí výzva k zadání atributů pouze při první registraci.)

  6. Vyberte Vytvořit. Nový tok uživatele se zobrazí v seznamu Toky uživatelů . V případě potřeby stránku aktualizujte.

Pokud chcete povolit samoobslužné resetování hesla, použijte postup v článku Povolení samoobslužného resetování hesla .

Přidružení webové aplikace k toku uživatele

I když k toku uživatele může být přidruženo mnoho aplikací, jedna aplikace může být přidružena pouze k jednomu toku uživatele. Tok uživatele umožňuje konfiguraci uživatelského prostředí pro konkrétní aplikace. Můžete například nakonfigurovat tok uživatele, který vyžaduje, aby se uživatelé přihlásili nebo se zaregistrovali pomocí telefonního čísla nebo e-mailové adresy.

  1. V nabídce bočního panelu vyberte Identita.

  2. Vyberte Externí identity a pak Toky uživatelů.

  3. Na stránce Toky uživatelů vyberte název toku uživatele , který jste vytvořili dříve, například SignInSignUpSample.

  4. V části Použít vyberte Aplikace.

  5. Vyberte Přidat aplikaci.

  6. Vyberte aplikaci ze seznamu, například ciam-client-app , nebo ji vyhledejte pomocí vyhledávacího pole a pak ji vyberte.

  7. Zvolte Vybrat.

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

Pokud chcete získat kód webové aplikace a ukázkového webového rozhraní API, stáhněte si soubor .zip nebo naklonujte ukázkovou webovou aplikaci z GitHubu spuštěním následujícího příkazu:

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

Pokud se rozhodnete stáhnout .zip soubor, extrahujte soubor ukázkové aplikace do složky, kde je celková délka cesty 260 nebo méně 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ých aplikací:

    npm install && npm update

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

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

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

  2. Najděte zástupný symbol:

    • Enter_the_Application_Id_Here a nahraďte ho ID aplikace (klienta) aplikace, kterou jste zaregistrovali dříve.

    • Enter_the_Tenant_Subdomain_Here a nahraďte ji subdoménou Adresáře (tenanta). Pokud je contoso.onmicrosoft.comnapříklad primární doménou vašeho tenanta , 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. Najděte 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 contoso.onmicrosoft.comnapříklad primární doménou vašeho tenanta , 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 pomocí následujících příkazů spusťte webové rozhraní API:

    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 pak přejděte na http://localhost:3000.

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

    Snímek obrazovky s přihlášením k webové aplikaci uzlu

  5. Na přihlašovací stránce zadejte svoji Email adresu, vyberte Další, zadejte heslo a 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í o úč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.

    Snímek obrazovky s přihlášením k webové aplikaci uzlu a voláním rozhraní API

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.

    Snímek obrazovky se seznamem úkolů pro manipulaci s rozhraním API

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

Jak to funguje

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

Na straně webového rozhraní API musí koncový bod ověřit, jestli jsou oprávnění nebo obory v přístupovém tokenu, který klientská aplikace prezentuje, platné. Pokud je přístupový token platný, koncový bod odpoví na požadavek HTTP, jinak odpoví chybou 401 Unauthorized HTTP.

Další kroky

Naučte se: