Sdílet prostřednictvím

Volání rozhraní API v ukázkové aplikaci démona Node.js

  • Článek

Tato příručka používá ukázkovou aplikaci démona Node.js, která vám ukáže, jak aplikace démon získá token pro volání webového rozhraní API. Microsoft Entra chrání webové rozhraní API.

Aplikace démona získá token jménem samotného (nikoli jménem uživatele). Uživatelé nemůžou pracovat s aplikací démona, protože vyžaduje vlastní identitu. Tento typ aplikace vyžaduje přístupový token pomocí své identity aplikace a prezentování ID aplikace, přihlašovacích údajů (hesla nebo certifikátu) a identifikátoru URI ID aplikace na externí ID.

Aplikace démona používá standardní udělení přihlašovacích údajů klienta OAuth 2.0. Pro zjednodušení procesu získání tokenu se v ukázce, která používáme v tomto článku, používá knihovna Microsoft Authentication Library pro uzel (MSAL Node).

Požadavky

Registrace aplikace démona a webového rozhraní API

V tomto kroku vytvoříte proces démon a registraci aplikací 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 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.

Registrace aplikace démona

Pokud chcete aplikaci umožnit přihlášení uživatelů pomocí Microsoft Entra, Microsoft Entra Externí ID musí být informována 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žitá k identifikaci aplikace při vytváření žádostí o ověření.

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

  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 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 Pouze účty 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.

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 Certifikáty a tajné kódy.
  3. Vyberte Nový tajný klíč klienta.
  4. Do pole Popis zadejte popis tajného klíče klienta (například tajný klíč klienta ciam).
  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 pro konfiguraci v pozdějším kroku. Hodnota tajného kódu se znovu nezobrazí a po přechodu z certifikátů a tajných kódů se nezobrazí žádným způsobem. Ujistěte se, že jste ho nahráli.

Udělení oprávnění rozhraní API pro aplikaci démona

  1. Na stránce Registrace aplikací vyberte aplikaci, kterou jste vytvořili, například ciam-client-app.

  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 Oprávnění aplikace. Tuto možnost vybereme, protože se aplikace přihlásí jako sama o sobě, ne jako uživatelé.

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

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

  9. V tomto okamžiku jste správně přiřadili oprávnění. Vzhledem k tomu, že aplikace démona neumožňuje uživatelům pracovat s ním, nemůžou s těmito oprávněními souhlasit sami uživatelé. 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 ověřte, že se pro <název> vašeho tenanta zobrazuje v části Stav pro obě oprávnění.

Klonování nebo stažení ukázkové aplikace démona 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:

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

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

    npm install && npm update

Konfigurace ukázkové aplikace démona 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) aplikace démona, 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 démona, 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é aplikace démona 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\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

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

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

  • Pokud se vaše aplikace démona a webové rozhraní API úspěšně spustily, měli byste v okně konzoly vidět něco podobného jako v následujícím poli 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 funguje

Aplikace Node.js používá přihlašovací údaje klienta OAuth 2.0 k získání přístupového tokenu pro sebe, a ne pro uživatele. Přístupový token, který aplikace požaduje, obsahuje oprávnění reprezentovaná jako role. Tok přihlašovacích údajů klienta používá tuto sadu oprávnění místo oborů uživatelů pro tokeny aplikace. Tato oprávnění aplikace jste zpřístupnili ve webovém rozhraní API dříve a pak jim udělili aplikaci démona.

Na straně rozhraní API musí webové rozhraní API ověřit, že přístupový token má požadovaná oprávnění (oprávnění aplikace). Webové rozhraní API nemůže přijmout přístupový token, který nemá požadovaná oprávnění.

Přístup k datům

Koncový bod webového rozhraní API by měl být připravený přijímat volání uživatelů i aplikací. Proto by měl mít způsob, jak odpovídajícím způsobem reagovat na každou žádost. Například volání od uživatele prostřednictvím delegovaných oprávnění nebo oborů obdrží seznam úkolů uživatele. Na druhou stranu volání z aplikace prostřednictvím oprávnění nebo rolí aplikace může obdržet celý seznam úkolů. V tomto článku ale voláme jenom aplikaci, takže jsme nemuseli konfigurovat delegovaná oprávnění nebo obory.

Související obsah