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

  • Článek

Tento článek používá ukázkovou aplikaci démona Node.js, která vám ukáže, jak aplikace démona získá token pro volání webového rozhraní API. Microsoft Entra ID pro zákazníky chrání webové rozhraní API.

Aplikace démona získá token jménem sebe (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 předložením ID aplikace, přihlašovacích údajů (heslo nebo certifikát) a identifikátoru URI ID aplikace externímu 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 používá ukázka, která používáme v tomto článku, knihovnu Microsoft Authentication Library for Node (UZEL MSAL).

Požadavky

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

V tomto kroku vytvoříte registraci aplikace démona a webového rozhraní API a určíte rozsahy webového rozhraní API.

Registrace aplikace webového rozhraní API

  1. Přihlaste se k Centru pro správu Microsoft Entra alespoň jako 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 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 Úč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 aplikačních rolí

Rozhraní API musí publikovat minimálně jednu roli aplikace, označovanou také jako Oprávnění aplikace, aby klientské aplikace mohly získat přístupový token jako samy. Oprávnění aplikací jsou typ 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 nepotřebují se 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 tak její stránku Přehled.

  2. V části Spravovat vyberte Role aplikací.

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

    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 roli aplikace a pak vyberte Použít a uložte změny:

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

Konfigurace volitelných deklarací identity

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

Pomocí následujících kroků nakonfigurujte volitelnou deklaraci identity idtyp :

  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 aplikace démona

Pokud chcete aplikaci povolit přihlašování uživatelů pomocí Microsoft Entra, musí být Microsoft Entra ID pro zákazníky informováno 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, která se používá k identifikaci vaší 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 k Centru pro správu Microsoft Entra alespoň jako 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.

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 tak 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 tajný klíč klienta aplikace 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. Zaznamenejte hodnotu tajného klíče. Tuto hodnotu použijete pro konfiguraci v pozdějším kroku.

Poznámka

Po přechodu ze stránky Certifikáty a tajné kódy se hodnota tajného kódu znovu nezobrazí a v žádném případě se nedá načíst, proto ji nezapomeňte zaznamenat.
V případě zvýšeného zabezpečení zvažte použití certifikátů místo tajných klíčů klienta.

Udělení oprávnění rozhraní API k 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 kartu Moje rozhraní API .

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

  6. Vyberte Možnost Oprávnění aplikace . Tuto možnost vybereme, protože se aplikace přihlašuje jako sama, 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 tuto chvíli jste oprávnění přiřadili správně. Vzhledem k tomu, že aplikace démona neumožňuje uživatelům s ní pracovat, nemůžou s těmito oprávněními souhlasit samotní 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 pak ověřte, že pro <název> vašeho tenanta je v části Stav u obou oprávnění uvedeno Uděleno.

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

Pokud chcete získat ukázkový kód webové aplikace, můžete provést některou z následujících úloh:

Pokud se rozhodnete stáhnout soubor.zip , 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:

        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 a rozhraní API démona

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 démona, 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 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. 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é aplikace a rozhraní API démona

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

    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 aplikace démona a webové rozhraní API úspěšně spustily, mělo by se v okně konzoly zobrazit něco podobného následujícímu 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á udělené přihlašovací údaje klienta OAuth 2.0 k získání přístupového tokenu pro sebe, nikoli 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 uživatelských oborů pro tokeny aplikace. Tato oprávnění aplikace jste ve webovém rozhraní API zveřejnili dříve a pak jste je 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ý tak, aby přijímal volání od 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í uživatele přes delegovaná oprávnění nebo obory obdrží seznam úkolů uživatele s daty. 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 provádíme jenom volání aplikace, takže jsme nemuseli konfigurovat delegovaná oprávnění nebo obory.

Další kroky