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

Tento článek 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 ID pro zákazníky chrání webové rozhraní API.

Aplikace démona získá token jménem sebe sama (ne jménem uživatele). Uživatelé nemůžou interagovat 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ů (hesla nebo certifikátu) a identifikátoru URI ID aplikace externímu ID.

Požadavky

• .NET 7.0 nebo novější.

• Visual Studio Code nebo jiný editor kódu.

• Microsoft Entra ID tenanta zákazníka. Pokud ho ještě nemáte, zaregistrujte si bezplatnou zkušební verzi.

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

V tomto kroku vytvoříte registraci aplikace démona a webového 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 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 aplikace démona

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.

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 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:

• Spuštěním následujícího příkazu stáhněte soubor .zip nebo naklonujte ukázkovou webovou aplikaci z GitHubu:

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

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

Konfigurace ukázkové aplikace a rozhraní API démona

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

1. V editoru kódu otevřete soubor ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json .

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

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-own-api-dotnet-core-daemon\ToDoListAPI
   dotnet run
   

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

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

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.

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Bake bread
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
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á udělení přihlašovacích údajů klienta OAuth2.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. Aplikace démona 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í.

Viz také

Projděte si kurz o tom, jak vytvořit vlastní aplikaci démona .NET, která volá rozhraní API.