Sdílet prostřednictvím

Rychlý start: Volání webového rozhraní API v ukázkové aplikaci démona

  • Článek

V tomto rychlém startu použijete ukázkovou aplikaci démona k získání přístupového tokenu a volání chráněného webového rozhraní API pomocí knihovnyMicrosoft Authentication Library (MSAL).

Než začnete, použijte selektor Zvolte typ tenanta v horní části této stránky pro výběr typu tenanta. Microsoft Entra ID poskytuje dvě konfigurace tenantů, firemní a externí. Konfigurace tenanta pracovních sil je určená pro zaměstnance, interní aplikace a další organizační prostředky. Externí tenant je určený pro vaše aplikace určené pro zákazníky.

Ukázková aplikace, kterou použijete v tomto rychlém startu, získá přístupový token pro volání rozhraní Microsoft Graph API.

Požadavky

Registrace identifikátorů aplikace a záznamů

K dokončení registrace zadejte název aplikace a zadejte podporované typy účtů. Po registraci aplikace podokno Přehled zobrazí identifikátory potřebné ve zdrojovém kódu aplikace.

  1. Přihlaste se do administrátorského centra Microsoft Entra.

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

  3. Přejděte na Identity>Applications>App registrations, vyberte Nová registrace.

  4. Zadejte Název aplikace, například identity-client-daemon-app.

  5. U podporovaných typů účtůvyberte pouze účty v tomto organizačním adresáři. Pokud chcete získat informace o různých typech účtů, vyberte možnost Pomozte mi zvolit možnost.

  6. Vyberte Zaregistrovat.

    Snímek obrazovky, který ukazuje, jak zadat jméno a vybrat typ účtu v Centru pro správu Microsoft Entra.

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

    Snímek obrazovky, který zobrazuje hodnoty identifikátoru na stránce přehledu v Centru pro správu Microsoft Entra

    Poznámka

    Typy podporovaných účtů lze změnit odkazem na Upravit účty podporované aplikací.

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 žádostech o tokeny:

  1. Na stránce Registrace aplikací vyberte aplikaci, kterou jste vytvořili (například klientský tajný kód webové aplikace), a otevřete její stránku Přehled.
  2. V části Spravovatvyberte Certifikáty & tajných kódů>Tajné kódy klienta>Nový tajný klíč klienta.
  3. Do pole Popis zadejte popis tajného klíče klienta (například tajný kód klienta webové aplikace).
  4. V části Konec platnostivyberte dobu, po kterou je tajemství platné (podle pravidel zabezpečení vaší organizace), a poté zvolte Přidat.
  5. Zaznamenejte hodnotu tajného . Tuto hodnotu použijete pro konfiguraci v pozdějším kroku. Tajná hodnota nebude znovu zobrazena a nelze ji žádným způsobem načíst poté, co opustíte Certifikáty a tajné kódy. Ujistěte se, že jste ho nahráli.

Při vytváření přihlašovacích údajů pro důvěrnou klientskou aplikaci:

  • Microsoft doporučuje, abyste před přesunutím aplikace do produkčního prostředí používali certifikát místo tajného klíče klienta. Další informace o tom, jak používat certifikát, najdete v pokynech v přihlašovacích údajů ověřovacího certifikátu aplikace Microsoft Identity Platform.

  • Pro účely testování můžete vytvořit certifikát podepsaný svým držitelem a nakonfigurovat aplikace tak, aby se s ním ověřily. Nicméně v produkčnímbyste měli zakoupit certifikát podepsaný dobře známou certifikační autoritou a pak použít Azure Key Vault ke správě přístupu k certifikátu a jeho životnosti.

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

Aby aplikace démona přistupovala k datům v rozhraní Microsoft Graph API, udělíte jí oprávnění, která potřebuje. Démonní aplikace potřebuje oprávnění typu aplikace. Uživatelé nemůžou pracovat s aplikací démona, takže správce tenanta musí s těmito oprávněními souhlasit. Pomocí následujících kroků udělte oprávnění a odsouhlaste je:

Pro aplikaci démona .NET nemusíte udělovat žádná oprávnění ani s tím souhlasit. Tato aplikace démona čte své vlastní informace o registraci aplikace, takže to může provést bez udělení oprávnění aplikace.

Klonování nebo stažení ukázkové aplikace

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-docs-code-dotnet.git

Konfigurace projektu

Pokud chcete v ukázce aplikace démona klienta použít podrobnosti o registraci aplikace, postupujte následovně:

  1. Otevřete okno konzoly a přejděte do ms-identity-docs-code-dotnet/console-daemon adresář:

    cd ms-identity-docs-code-dotnet/console-daemon

  2. Otevřete Program.cs a nahraďte obsah souboru následujícím fragmentem kódu;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
 Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
 // 'Enter the client ID obtained from the Microsoft Entra admin center
 ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
 // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
 ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center",
 // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
 ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    • Authority – autorita je adresa URL, která označuje adresář, ze kterého může knihovna MSAL požadovat tokeny. Nahraďte Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center hodnotou Adresář (nájemce) ID, která byla zaznamenána dříve.
    • ClientId – identifikátor aplikace, označovaný také jako klient. Nahraďte text v uvozovkách hodnotou Application (client) ID, která byla zaznamenána dříve ze stránky přehledu registrované aplikace.
    • ClientSecret – tajný klíč klienta vytvořený pro aplikaci v Centru pro správu Microsoft Entra. Zadejte hodnotu tajného klíče klienta.
    • ClientObjectId – ID objektu klientské aplikace. Nahraďte text v uvozovkách hodnotou Object ID, kterou jste si poznamenali dříve ze stránky přehledu registrované aplikace.

Spuštění a otestování aplikace

Nakonfigurovali jste ukázkovou aplikaci. Můžete pokračovat spuštěním a otestováním.

V okně konzoly spusťte následující příkaz, který sestaví a spustí aplikaci:

dotnet run

Po úspěšném spuštění aplikace se zobrazí odpověď podobná následujícímu fragmentu kódu (zkrácená kvůli stručnosti):

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Jak to funguje

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í identity aplikace tak, že předá ID aplikace, přihlašovací údaje (tajný klíč nebo certifikát) a identifikátor URI ID aplikace. Aplikace démona používá standardní tok přihlašovacích údajů klienta OAuth 2.0 k získání přístupového tokenu.

Aplikace získá přístupový token z platformy Microsoft Identity Platform. Přístupový token je vymezený pro rozhraní Microsoft Graph API. Aplikace pak použije přístupový token k vyžádání vlastních podrobností o registraci aplikace z rozhraní Microsoft Graph API. Aplikace může požádat o libovolný prostředek z rozhraní Microsoft Graph API, pokud má přístupový token správná oprávnění.

Ukázka ukazuje, jak může bezobslužná úloha nebo služba Systému Windows běžet s identitou aplikace místo identity uživatele.

Související obsah

Požadavky

Registrace aplikací a identifikátorů záznamů

V tomto kroku zaregistrujete aplikaci démona a webovou aplikaci API v Centru pro správu Microsoft Entra 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 alespoň jako Application Developer.

  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 Účty pouze 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. Zaznamenejte ID adresáře (tenanta) a ID aplikace (klienta), které použijete ve zdrojovém kódu vaší aplikace.

Konfigurace rolí aplikací

Rozhraní API musí publikovat minimálně jednu roli aplikace, také nazývanou oprávnění aplikace, aby klientské aplikace mohly získat 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é ověření vlastní identity, aniž by bylo nutné 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 Spravovatvyberte role aplikace.

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

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

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

    Vlastnost Hodnota
    Zobrazovaný název ToDoList.ReadWrite.All
    Povolené typy členů Aplikace
    Hodnota ToDoList.ReadWrite.All
    Popis Povolit aplikaci čtení a zápisu ToDo seznamu každého uživatele 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 deklarací identity scp a rolí , použití deklarace identity idtyp je nejjednodušší způsob, jak odlišit token aplikace od tokenu aplikace + tokenu uživatele. Například hodnota této deklarace identity je aplikace, když je token jen pro aplikaci.

Registrace aplikace démona

Aby vaše aplikace mohla přihlašovat uživatele pomocí Microsoft Entra, je třeba zajistit, aby Microsoft Entra External ID byl informován o aplikaci, kterou vytváří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 (klient), 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 alespoň jako 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 na Identity>Applications>App registrations.

  4. Vyberte + Nová registrace.

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

    1. Zadejte smysluplnou aplikaci Název, 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 žádostech o tokeny:

  1. Na stránce Registrace aplikací vyberte aplikaci, kterou jste vytvořili (například tajný kód klienta webové aplikace ), a otevřete tím její stránku Přehled.
  2. V části Spravovatvyberte Certifikáty & tajných kódů>Tajné kódy klienta>Nový tajný klíč klienta.
  3. Do pole Popis zadejte popis tajného klíče klienta (například tajný kód klienta webové aplikace).
  4. V části Konec platnostivyberte dobu, po kterou je tajemství platné (podle pravidel zabezpečení vaší organizace), a poté vyberte Přidat.
  5. Zaznamenejte hodnotu tajemství. Tuto hodnotu použijete pro konfiguraci v pozdějším kroku. Hodnota tajného kódu se znovu nezobrazí a není možné ji žádným způsobem načíst, když přejdete mimo Certifikáty a tajné kódy. Ujistěte se, že jste ho nahráli.

Při vytváření přihlašovacích údajů pro důvěrnou klientskou aplikaci:

  • Microsoft doporučuje, abyste před přesunutím aplikace do produkčního prostředí používali certifikát místo tajného klíče klienta. Další informace o tom, jak používat certifikát, najdete v pokynech v přihlašovacích údajů ověřovacího certifikátu aplikace Microsoft Identity Platform.

  • Pro účely testování můžete vytvořit certifikát podepsaný svým držitelem a nakonfigurovat aplikace tak, aby se s ním ověřily. Ale v produkcibyste měli zakoupit certifikát podepsaný dobře známou certifikační autoritou a pak použijte Azure Key Vault ke správě přístupu k certifikátům a životnosti.

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 aplikaci ciam-client-app.

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

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

  4. Vyberte záložku rozhraní API, která moje organizace používá.

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

  6. Vyberte možnost Oprávnění aplikace. Tuto možnost vybereme, protože aplikace se přihlašuje jako sama sebe, ale ne jménem uživatele.

  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>, poté vyberte Ano.
    2. Vyberte Aktualizovata potom ověřte, že uděleno pro <název vašeho tenanta,> se zobrazí 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

  • Případně stáhněte soubor s ukázkami .zipa pak ho extrahujte 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

Pokud chcete v ukázce klientské webové aplikace použít podrobnosti o registraci aplikace, postupujte následovně:

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

  2. Vyhledejte zástupný symbol:

    • Enter_the_Application_Id_Here a nahraďte jej ID 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 neznáte název klienta, zjistěte, jak zjistit podrobnosti o klientovi.

    • 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.

Pro použití registrace aplikace v příkladu webového 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 nájemníka, zjistěte, jak číst podrobnosti o nájemníkovi.

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

Nakonfigurovali jste ukázkovou aplikaci. Můžete pokračovat spuštěním a otestováním.

  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á pro sebe, a ne pro uživatele, grantový tok přihlašovacích údajů klienta OAuth 2.0 k získání přístupového tokenu. 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řístupnit dříve ve webovém rozhraní API a pak jim udělena aplikaci démona.

Na straně rozhraní API musí ukázkové webové rozhraní API .NET 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 s delegovanými oprávněními/delegovanými obory obdrží seznam dat uživatele to-do. Na druhou stranu volání z aplikace prostřednictvím oprávnění nebo rolí aplikace může obdržet celý seznam to-do. V tomto článku ale voláme jenom aplikaci, takže jsme nemuseli konfigurovat delegovaná oprávnění nebo obory.

Související obsah