Volání rozhraní API v ukázkové aplikaci démon .NET

Tato příručka používá ukázkovou aplikaci démona .NET, která vám ukáže, jak aplikace démona získá token pro volání chráněného 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 předložení ID aplikace, přihlašovacích údajů (hesla nebo certifikátu) a identifikátoru URI ID aplikace pro Microsoft Entra Externí ID.

Požadavky

• Visual Studio Code nebo jiný editor kódu
• .NET 7.0 nebo novější.

• Externí tenant. Pokud ho chcete vytvořit, zvolte některou z následujících metod:
  • (Doporučeno) Pomocí rozšíření Microsoft Entra Externí ID nastavte externího tenanta přímo v editoru Visual Studio Code.
  • V Centru pro správu Microsoft Entra vytvořte nového externího tenanta .

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 aplikačních rolí

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 jako aplikaci, která se přihlásí 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 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-dotnet-tutorial.git
  

• Stáhněte soubor .zip. Extrahujte ho do cesty k souboru, kde délka názvu je menší než 260 znaků.

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 ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json 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 ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/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-own-api-dotnet-core-daemon\ToDoListAPI
   dotnet run
   

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

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
   dotnet run
   

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 následující pole JSON:

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Jak to funguje

Aplikace démona používá přihlašovací údaje klienta OAuth2.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. Aplikace démon v tomto článku používá knihovnu Microsoft Authentication Library pro .NET ke zjednodušení procesu získání tokenu.

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 odmítne přístupové tokeny, které nemají požadovaná oprávnění.

Související obsah

• Použití naší vícedílné série kurzů k sestavení této aplikace démona .NET od začátku
• Povolte resetování hesla.
• Přizpůsobte výchozí branding.
• Nakonfigurujte přihlášení pomocí Googlu.