Rychlý start: Volání webového rozhraní API chráněného platformou Microsoft Identity Platform

Platí pro: Tenanti pracovních sil Externí tenanti (další informace)

V tomto rychlém startu použijete ukázkovou webovou aplikaci, která vám ukáže, jak chránit webové rozhraní API ASP.NET pomocí platformy Microsoft Identity Platform. Ukázka používá Microsoft Authentication Library (MSAL) ke zajištění ověřování a autorizace.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Zaregistrujte novou aplikaci v Centru pro správu Microsoft Entra a poznamenejte si jeho identifikátory ze stránky Přehled aplikace. Další informace najdete v tématu Registrace aplikace.
  • Název: NewWebAPI1
  • podporované typy účtů: Účty v tomto organizačním adresáři (pouze jeden tenant)

ASP.NET

• Visual Studio 2022. Stáhněte si Visual Studio zdarma.

ASP.NET Core

• Visual Studio Code

Zveřejnit rozhraní API

Po registraci rozhraní API můžete nakonfigurovat jeho oprávnění definováním oborů, které rozhraní API zveřejňuje klientským aplikacím. Klientské aplikace požadují oprávnění k provádění operací předáním přístupového tokenu spolu s požadavky na chráněné webové rozhraní API. Webové rozhraní API pak provede požadovanou operaci pouze v případě, že přístupový token, který obdrží, obsahuje požadované obory.

ASP.NET

1. V části Spravovatvyberte Zveřejnit rozhraní API>Přidat obor. Přijměte navrhovaný identifikátor URI ID aplikace (api://{clientId}) tak, že vyberete Uložit a pokračovata pak zadáte následující informace:

   1. Jako název oboruzadejte access_as_user.
   2. U možnosti Kdo může souhlasit, ujistěte se, že je vybraná možnost Správci a uživatelé .
   3. Do pole Zobrazovaný název souhlasu správce zadejte .
   4. Do pole popis souhlasu správce zadejte Accesses the TodoListService web API as a user.
   5. Do pole Zobrazovaný název souhlasu uživatele zadejte Access TodoListService as a user.
   6. Do pole Popis souhlasu uživatele zadejte Accesses the TodoListService web API as a user.
   7. Pro Stav ponechte Povoleno.

2. Vyberte Přidat rozsah.

ASP.NET Core

Přidání delegovaných oprávnění (oborů)

Rozhraní API musí publikovat minimálně jeden obor, označovaný také jako delegované oprávnění, aby klientské aplikace mohly úspěšně získat přístupový token pro uživatele. Chcete-li publikovat rozsah, postupujte takto:

1. Na stránce Registrace aplikací vyberte API aplikaci, kterou jste vytvořili (ciam-ToDoList-api), abyste otevřeli stránku jejího Přehledu.

2. V části Spravovatvyberte Zpřístupnit rozhraní API.

3. V horní části stránky vedle Application ID URIvyberte odkaz Přidat pro vygenerování jedinečného URI pro tuto aplikaci.

4. Přijměte navrhovaný identifikátor URI ID aplikace, například api://{clientId}, a vyberte Uložit. Když vaše webová aplikace požádá o přístupový token pro webové rozhraní API, přidá identifikátor URI jako předponu pro každý obor, který definujete pro rozhraní API.

5. V části Obory definované tímto rozhraním APIvyberte Přidat obor.

6. Zadejte následující hodnoty, které definují přístup pro čtení k API, a pak vyberte Přidat obor pro uložení změn.

   Vlastnictví	Hodnota
   Název oboru	ToDoList.Read
   Kdo může vyjádřit souhlas	Pouze správci
   Zobrazovaný název souhlasu správce	Číst seznam úkolů uživatele pomocí TodoListApi
   Popis souhlasu správce	Povolit aplikaci, aby mohla číst uživatelův seznam úkolů pomocíTodoListApi.
   Stát	Povoleno

7. Vyberte Znovu přidat obor a zadejte následující hodnoty, které definují obor přístupu pro čtení a zápis do rozhraní API. Vyberte Přidat obor a uložte provedené změny:

   Vlastnictví	Hodnota
   Název oboru	toDoList.ReadWrite
   Kdo může vyjádřit souhlas	Pouze správci
   Zobrazovaný název souhlasu správce	Číst a zapisovat seznam úkolů uživatelů pomocí ToDoListApi
   Popis souhlasu správce	Povolit aplikaci číst a zapisovat seznam úkolů uživatele pomocí ToDoListApi
   Stát	Povoleno

Přečtěte si další informace o principu nejnižšího oprávnění při publikování oprávnění pro webové rozhraní API.

Přidat oprávnění aplikace (role aplikace)

Rozhraní API musí publikovat pro aplikace minimálně jednu roli aplikace, označovanou také jako oprávnění aplikace, aby klientské aplikace mohly získat přístupový token jako takové. Oprávnění aplikace jsou typem oprávnění, která by rozhraní API měla publikovat, aby klientské aplikace mohly úspěšně ověřit samy sebe, aniž by bylo potřeba 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, zadejte následující hodnoty a poté vyberte Použít k uložení změn:

   Vlastnictví	Hodnota
   Zobrazované jméno	ToDoList.Read.All
   Povolené typy členů	Aplikace
   Hodnota	ToDoList.Read.All
   Popis	Povolit aplikaci číst pomocí TodoListApi seznam úkolů každého uživatele
   Chcete tuto roli aplikace povolit?	Ponechat zaškrtnuté

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:

   Vlastnictví	Hodnota
   Zobrazované jméno	ToDoList.ReadWrite.All
   Povolené typy členů	Aplikace
   Hodnota	ToDoList.ReadWrite.All
   Popis	Povolit aplikaci číst a zapisovat seznam úkolů každého uživatele pomocí 'ToDoListApi'
   Chcete tuto roli aplikace povolit?	Ponechat zaškrtnuté

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.

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• Stáhnout jako soubor ZIP.

Návod

Pokud se chcete vyhnout chybám způsobeným omezením délky cesty ve Windows, doporučujeme extrahovat archiv nebo klonovat úložiště do adresáře blízko kořenového adresáře jednotky.

ASP.NET Core

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

• Stáhnout soubor .zip. Rozbalte to do složky s délkou názvu menší než 260 znaků.

Konfigurace ukázkové aplikace

Nakonfigurujte ukázku kódu tak, aby odpovídala registrovanému webovému rozhraní API.

ASP.NET

1. Otevřete řešení v sadě Visual Studio a pak otevřete soubor appsettings.json v kořenovém adresáři projektu TodoListService.

2. Hodnotu Enter_the_Application_Id_here nahraďte hodnotou ID klienta (ID aplikace) z aplikace, kterou jste zaregistrovali na portálu Portal ve vlastnostech ClientID i Audience.

Přidání nového oboru do souboru app.config

Chcete-li přidat nový obor do souboru todoListClient app.config, postupujte takto:

1. V kořenové složce projektu TodoListClient otevřete soubor app.config.

2. Do parametru TodoListServiceScope vložte ID aplikace z aplikace, kterou jste zaregistrovali pro projekt TodoListService a nahraďte řetězec {Enter the Application ID of your TodoListService from the app registration portal}.

Poznámka:

Ujistěte se, že ID aplikace používá následující formát: api://{TodoListService-Application-ID}/access_as_user (kde {TodoListService-Application-ID} je identifikátor GUID představující ID aplikace pro vaši aplikaci TodoListService).

Registrace webové aplikace (TodoListClient)

Zaregistrujte aplikaci TodoListClient v registracích aplikací v Centru pro správu Microsoft Entra a nakonfigurujte kód v projektu TodoListClient. Pokud se klient a server považují za stejnou aplikaci, můžete aplikaci zaregistrovanou v kroku 2 znovu použít. Stejnou aplikaci použijte, pokud chcete, aby se uživatelé přihlásili pomocí osobního účtu Microsoft.

Registrace aplikace

Aplikaci TodoListClient zaregistrujete takto:

1. Přihlaste se do centra pro správu Microsoft Entra alespoň jako správce cloudových aplikací.

2. Přejděte doregistrace aplikace> a vyberte Nová registrace.

3. Vyberte Nová registrace.

4. Když se otevře stránka Zaregistrovat aplikaci, 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 NativeClient-DotNet-TodoListClient).
   2. U podporovaných typů účtůvyberte Účty v libovolném adresáři organizace.
   3. Výběrem možnosti Registrovat aplikaci vytvořte.

   Poznámka:

   V souboru projektu TodoListClient app.config je výchozí hodnota ida:Tenant nastavena na common. Možné hodnoty:

   • common: Můžete se přihlásit pomocí pracovního nebo školního účtu nebo osobního účtu Microsoft (protože jste vybrali Účty v libovolném adresáři organizace v předchozím kroku).
   • organizations: Můžete se přihlásit pomocí pracovního nebo školního účtu.
   • consumers: Můžete se přihlásit jenom pomocí osobního účtu Microsoft.

5. Na stránce Přehled aplikace vyberte Ověřovánía poté dokončete následující kroky pro přidání platformy.

   1. V části Konfigurace platformyklikněte na tlačítko Přidat platformu.
   2. Pro Mobilní a desktopové aplikacevyberte možnost Mobilní a desktopové aplikace.
   3. Pro přesměrování identifikátorů URI zaškrtněte políčko https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Vyberte a nakonfigurujte.

6. Vyberte oprávnění rozhraní APIa dokončete následující kroky pro přidání oprávnění:

   1. Vyberte tlačítko Přidat oprávnění.
   2. Vyberte kartu Moje rozhraní API.
   3. V seznamu rozhraní API vyberte AppModelv2-NativeClient-DotNet-TodoListService API nebo název, který jste zadali pro webové rozhraní API.
   4. Zaškrtněte políčko pro oprávnění access_as_user, pokud ještě není zaškrtnuté. V případě potřeby použijte vyhledávací pole.
   5. Vyberte tlačítko Přidat oprávnění.

Konfigurace projektu

Nakonfigurujte projekt TodoListClient přidáním ID aplikace do souboru app.config.

1. Na portálu Registrace aplikací na stránce Přehled zkopírujte hodnotu ID aplikace (klienta).

2. Z kořenové složky projektu TodoListClient otevřete soubor app.config a vložte hodnotu ID aplikace do parametru ida:ClientId.

ASP.NET Core

1. V integrovaném vývojovém prostředí otevřete složku projektu ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI obsahující ukázku.

2. Otevřete soubor appsettings.json, který obsahuje následující fragment kódu:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Najděte následující hodnoty:

   • ClientId – identifikátor aplikace, označovaný také jako klient. Nahraďte text v uvozovkách value textem ID aplikace (klienta), který byl zaznamenán dříve na stránce Přehled registrované aplikace.
   • TenantId – identifikátor tenanta, ve kterém je aplikace zaregistrovaná. Nahraďte text value v uvozovkách hodnotou ID adresáře (tenanta), která byla zaznamenána dříve ze stránky Přehled registrované aplikace.
   • Instance – Určuje adresář, ze kterého může knihovna MSAL (Microsoft Authentication Library) požadovat tokeny. V závislosti na vašem scénáři nahraďte Enter_the_Authority_URL_Here některou z následujících hodnot:
     • Pro tenanty pracovních sil použijte https://login.microsoftonline.com/ jako instanci.
     • Pro externí tenanty přidejte adresu URL autority ve formě https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Spuštění ukázkové aplikace

ASP.NET

Zahajte oba projekty. Pro uživatele sady Visual Studio;

1. Klikněte pravým tlačítkem na řešení sady Visual Studio a vyberte Vlastnosti

2. V Části Společné vlastnosti vyberte Spouštěný projekt a pak Více spouštěných projektů.

3. U obou projektů jako akci zvolte Spustit.

4. Pomocí šipky nahoru se ujistěte, že služba TodoListService začne nejprve tím, že ji přesunete na první pozici v seznamu.

Přihlaste se a spusťte projekt TodoListClient.

1. Stisknutím klávesy F5 spusťte projekty. Otevře se stránka služby i desktopová aplikace.

2. V todoListClient v pravém horním rohu vyberte Přihlásit sea pak se přihlaste pomocí stejných přihlašovacích údajů, které jste použili k registraci aplikace, nebo se přihlaste jako uživatel ve stejném adresáři.

   Pokud se přihlašujete poprvé, může se zobrazit výzva k vyjádření souhlasu s webovým rozhraním API TodoListService.

   Pro usnadnění přístupu k webovému rozhraní API todoListService a manipulaci se seznamem úkolů vyžaduje přihlášení také přístupový token do oboru access_as_user.

Předběžná autorizace klientské aplikace

Uživatelům z jiných adresářů můžete povolit přístup k webovému rozhraní API tak, že předem autorizujete klientskou aplikaci pro přístup k webovému rozhraní API. Uděláte to tak, že přidáte ID aplikace z klientské aplikace do seznamu předvyvěřovaných aplikací pro vaše webové rozhraní API. Přidáním předem autorizovaného klienta povolíte uživatelům přístup k webovému rozhraní API, aniž by museli poskytnout souhlas.

1. Na portálu Registrace aplikací otevřete vlastnosti vaší aplikace TodoListService.
2. V části Zveřejnit rozhraní API v části Autorizované klientské aplikacevyberte Přidat klientskou aplikaci.
3. Do pole ID klienta vložte ID aplikace TodoListClient.
4. V části Autorizované obory vyberte obor webového rozhraní API api://<Application ID>/access_as_user.
5. Vyberte Přidat aplikaci.

Spusťte svůj projekt

1. Stisknutím klávesy F5 spusťte projekt. Otevře se vaše aplikace TodoListClient.
2. V pravém horním rohu vyberte Přihlásit sea pak se přihlaste pomocí osobního účtu Microsoft, jako je live.com nebo hotmail.com účet nebo pracovní nebo školní účet.

Volitelné: Omezení přístupu k přihlášení určitým uživatelům

Ve výchozím nastavení můžou všechny osobní účty, jako jsou outlook.com nebo live.com účty, pracovní nebo školní účty z organizací integrovaných s Microsoft Entra ID požadovat tokeny a přistupovat k vašemu webovému rozhraní API.

Pokud chcete určit, kdo se může přihlásit k aplikaci, změnou vlastnosti TenantId v souboru appsettings.json.

ASP.NET Core

1. Spuštěním následujícího příkazu z kořenového adresáře projektu webového rozhraní API spusťte aplikaci:

   dotnet run
   

2. Pokud všechno fungovalo správně, zobrazí se v terminálu výstup podobný následujícímu:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Poznamenejte si číslo portu v https://localhost:{port} adrese URL.

3. Pokud chcete ověřit, že je koncový bod chráněný, aktualizujte základní adresu URL v následujícím příkazu cURL tak, aby odpovídala adrese URL, kterou jste obdrželi v předchozím kroku, a pak spusťte příkaz:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Očekávaná odpověď je 401 Neautorizováno.

Další kroky

Zjistěte, jak chránit webové rozhraní API ASP.NET Core pomocí platformy Microsoft Identity Platform.

Kurz: Sestavení a zabezpečení webového rozhraní API ASP.NET Core pomocí platformy Microsoft Identity Platform