Rövid útmutató: A Microsoft identitásplatformja által védett webes API meghívása

A következőkre vonatkozik: A munkaerő-bérlők Külső bérlők (további információ)

Ebben a rövid útmutatóban egy minta webalkalmazással mutatja be, hogyan védhet meg egy ASP.NET webes API-t a Microsoft identitásplatformjával. A minta a Microsoft Authentication Library (MSAL) használatával kezeli a hitelesítést és az engedélyezést.

Előfeltételek

• Egy Azure-fiók, aktív előfizetéssel. Hozzon létre egy fiókot ingyenesen.
• Regisztráljon egy új alkalmazást a Microsoft Entra Felügyeleti központban , és rögzítse annak azonosítóit az alkalmazás áttekintési oldalán. További információ: Alkalmazás regisztrálása.
  • Név: NewWebAPI1
  • Támogatott fióktípusok: Csak ebben a szervezeti címtárban lévő fiókok (egyetlen bérlő)

ASP.NET

• Visual Studio 2022. Töltse le ingyenesen a Visual Studiót.

ASP.NET Core

• Visual Studio Code

Az API felfedése

Az API regisztrálása után konfigurálhatja annak engedélyét az API által az ügyfélalkalmazások számára elérhetővé tott hatókörök meghatározásával. Az ügyfélalkalmazások engedélyt kérnek a műveletek végrehajtására azáltal, hogy átadnak egy hozzáférési jogkivonatot a kérésekkel együtt a védett webes API-nak. A webes API ezután csak akkor hajtja végre a kért műveletet, ha a kapott hozzáférési jogkivonat tartalmazza a szükséges hatóköröket.

ASP.NET

1. A Kezelés területen válassza az API közzététele>Hatókör hozzáadása lehetőséget. Fogadja el a javasolt alkalmazásazonosító URI-ját (api://{clientId}) a Mentés és folytatás gombra kattintva, majd adja meg a következő adatokat:

   1. A Hatókör neve mezőbe írja be a következőt access_as_user:
   2. A Ki tud hozzájárulni, győződjön meg arról, hogy a Rendszergazdák és a felhasználók lehetőség van kiválasztva.
   3. Rendszergazdai hozzájárulás megjelenítendő neve mezőbe írja be a következőt: .
   4. A Rendszergazdai hozzájárulás leírása mezőbe írja be a következőt Accesses the TodoListService web API as a user:
   5. A Felhasználói hozzájárulás megjelenítendő név mezőjébe írja be a következőt Access TodoListService as a user:
   6. A Felhasználói hozzájárulás leírás mezőjébe írja be a következőt Accesses the TodoListService web API as a user:
   7. Állapot alatt tartsa bekapcsolva.

2. Válassza a Hatókör hozzáadása lehetőséget.

ASP.NET Core

Delegált engedélyek (hatókörök) hozzáadása

Az API-nak legalább egy hatókört , más néven delegált engedélyt kell közzétennie ahhoz, hogy az ügyfélalkalmazások sikeresen beszerezhessék a felhasználó hozzáférési jogkivonatát. A hatókör közzétételéhez kövesse az alábbi lépéseket:

1. Az Alkalmazásregisztrációk lapon válassza ki a létrehozott API-alkalmazást (ciam-ToDoList-api) az Áttekintés lap megnyitásához.

2. A Kezelés területen válassza az API-k felfedése lehetőséget.

3. A lap tetején, az alkalmazásazonosító URI-ja mellett válassza a Hozzáadás hivatkozást az alkalmazáshoz egyedi URI létrehozásához.

4. Fogadja el a javasolt alkalmazásazonosító URI-ját, például api://{clientId}, és válassza a Mentés lehetőséget. Amikor a webalkalmazás hozzáférési jogkivonatot kér a webes API-hoz, hozzáadja az URI-t az API-hoz definiált egyes hatókörök előtagjaként.

5. Az API által definiált hatókörök alatt válassza a Hatókör hozzáadása lehetőséget.

6. Adja meg a következő értékeket, amelyek olvasási hozzáférést határoznak meg az API-hoz, majd válassza a Hatókör hozzáadása lehetőséget a módosítások mentéséhez:

   Ingatlan	Érték
   Hatókör neve	ToDoList.Olvassa el
   Kik járulhatnak hozzá	Csak rendszergazdák
   A rendszergazda hozzájárulásának megjelenítendő neve	Felhasználók ToDo-listájának olvasása a "TodoListApi" használatával
   Rendszergazdai hozzájárulás leírása	Engedélyezze az alkalmazás számára a felhasználó ToDo-listájának olvasását a "TodoListApi" használatával.
   Állam	Engedélyezve

7. Válassza ismét a Hatókör hozzáadása lehetőséget, és adja meg az alábbi értékeket, amelyek írási és olvasási hozzáférési hatókört határoznak meg az API-hoz. A módosítások mentéséhez válassza a Hatókör hozzáadása lehetőséget:

   Ingatlan	Érték
   Hatókör neve	ToDoList.ReadWrite
   Kik járulhatnak hozzá	Csak rendszergazdák
   A rendszergazda hozzájárulásának megjelenítendő neve	Felhasználók ToDo-listájának olvasása és írása a "ToDoListApi" használatával
   Rendszergazdai hozzájárulás leírása	Lehetővé teszi az alkalmazás számára a felhasználó ToDo-listájának olvasását és írását a "ToDoListApi" használatával
   Állam	Engedélyezve

Tudjon meg többet arról, hogyan alkalmazhatja a legkisebb jogosultság elvét, amikor engedélyeket tesz közzé egy webes API-hoz.

Alkalmazásengedélyek (alkalmazásszerepkörök) hozzáadása

Az API-nak legalább egy alkalmazásszerepkört kell közzétennie az alkalmazásokhoz, más néven alkalmazásengedélyekhez, hogy az ügyfélalkalmazások maguk is beszerezhessék a hozzáférési jogkivonatot. Az alkalmazásengedélyek olyan típusú engedélyek, amelyeket az API-knak közzé kell tenniük, ha engedélyezni szeretnék az ügyfélalkalmazások számára a sikeres hitelesítést, és nem kell bejelentkezniük a felhasználóknak. Alkalmazásengedély közzétételéhez kövesse az alábbi lépéseket:

1. Az Alkalmazásregisztrációk lapon válassza ki a létrehozott alkalmazást (például a ciam-ToDoList-api-t) az Áttekintés lap megnyitásához.

2. A Kezelés csoportban válassza az Alkalmazásszerepkörök lehetőséget.

3. Válassza az Alkalmazásszerepkör létrehozása lehetőséget, majd adja meg a következő értékeket, majd kattintson az Alkalmaz gombra a módosítások mentéséhez:

   Ingatlan	Érték
   Megjelenítendő név	ToDoList.Read.All
   Engedélyezett tagtípusok	Alkalmazások
   Érték	ToDoList.Read.All
   Leírás	Minden felhasználó ToDo-listájának olvasásának engedélyezése az alkalmazás számára a "TodoListApi" használatával
   Szeretné engedélyezni ezt az alkalmazásszerepkört?	Maradjon bejelölve

4. Válassza ismét az Alkalmazásszerepkör létrehozása lehetőséget, majd adja meg a következő értékeket a második alkalmazásszerepkörhöz, majd kattintson az Alkalmaz gombra a módosítások mentéséhez:

   Ingatlan	Érték
   Megjelenítendő név	ToDoList.ReadWrite.All
   Engedélyezett tagtípusok	Alkalmazások
   Érték	ToDoList.ReadWrite.All
   Leírás	Az alkalmazás a ToDoListApi használatával elolvashatja és megírhatja minden felhasználó ToDo-listáját
   Szeretné engedélyezni ezt az alkalmazásszerepkört?	Maradjon bejelölve

A mintaalkalmazás klónozása vagy letöltése

A mintaalkalmazás beszerzéséhez vagy klónozhatja a GitHubról, vagy letöltheti ".zip" formátumú fájlként.

ASP.NET

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

• Töltse le ZIP-fájlként.

Jótanács

A Windows elérési úthossz-korlátozásai által okozott hibák elkerülése érdekében javasoljuk, hogy bontsa ki az archívumot, vagy klónozza az adattárat a meghajtó gyökeréhez közeli könyvtárba.

ASP.NET Core

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

• Töltse le a .zip fájlt. Bontsa ki olyan fájl elérési útvonalra, ahol a név hossza kevesebb mint 260 karakter.

A mintaalkalmazás konfigurálása

A kódmintát úgy konfigurálja, hogy megfeleljen a regisztrált webes API-nak.

ASP.NET

1. Nyissa meg a megoldást a Visual Studióban, majd nyissa meg a appsettings.json fájlt a TodoListService projekt gyökerében.

2. Cserélje le az Enter_the_Application_Id_here értékét az ügyfélazonosító (alkalmazásazonosító) értékre az alkalmazásregisztrációs portálon regisztrált alkalmazásból, mind a ClientID és a Audience tulajdonságoknál.

Az új hatókör hozzáadása a app.config fájlhoz

Ha hozzá szeretné adni az új hatókört a TodoListClient app.config fájlhoz, kövesse az alábbi lépéseket:

1. A TodoListClient projekt gyökérmappájában nyissa meg a app.config fájlt.

2. Illessze be az alkalmazásazonosítót a TodoListService-projekthez regisztrált alkalmazásból a TodoListServiceScope paraméterbe, és cserélje le a {Enter the Application ID of your TodoListService from the app registration portal} sztringet.

Megjegyzés:

Győződjön meg arról, hogy az alkalmazásazonosító a következő formátumot használja: api://{TodoListService-Application-ID}/access_as_user (ahol a {TodoListService-Application-ID} a TodoListService alkalmazás alkalmazásazonosítóját képviselő GUID).

A webalkalmazás regisztrálása (TodoListClient)

Regisztrálja a TodoListClient alkalmazást az alkalmazásregisztrációkban a Microsoft Entra Felügyeleti központban, majd konfigurálja a kódot a TodoListClient projektben. Ha az ügyfél és a kiszolgáló azonos alkalmazásnak minősül, a 2. lépésben regisztrált alkalmazást újra felhasználhatja. Használja ugyanazt az alkalmazást, ha azt szeretné, hogy a felhasználók személyes Microsoft-fiókkal jelentkezzenek be.

Az alkalmazás regisztrálása

A TodoListClient alkalmazás regisztrálásához kövesse az alábbi lépéseket:

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább felhőalkalmazás-rendszergazdaként.

2. Keresse meg az Entra-azonosító>alkalmazásregisztrációit, és válassza az Új regisztráció lehetőséget.

3. Válassza az Új regisztráció lehetőséget.

4. Amikor megnyílik az Alkalmazás regisztrálása lap , adja meg az alkalmazás regisztrációs adatait:

   1. A Név szakaszban adjon meg egy értelmes alkalmazásnevet, amely megjelenik az alkalmazás felhasználói számára (például NativeClient-DotNet-TodoListClient).
   2. Támogatott fióktípusok esetén válassza a Bármely szervezeti címtárban lévő Fiókok lehetőséget.
   3. Az alkalmazás létrehozásához válassza a Regisztráció lehetőséget.

   Megjegyzés:

   A TodoListClient projekt app.config fájlban az alapértelmezett érték ida:Tenant a következőre commonvan állítva: . A lehetséges értékek a következők:

   • common: Munkahelyi vagy iskolai fiókkal vagy személyes Microsoft-fiókkal is bejelentkezhet (mivel az előző lépésben bármelyik szervezeti címtárban kiválasztotta a Fiókokat ).
   • organizations: Munkahelyi vagy iskolai fiókkal jelentkezhet be.
   • consumers: Csak microsoftos személyes fiókkal jelentkezhet be.

5. Az alkalmazás áttekintési lapján válassza a Hitelesítés lehetőséget, majd hajtsa végre az alábbi lépéseket egy platform hozzáadásához:

   1. A Platformkonfigurációk területen válassza a Platform hozzáadása gombot .
   2. Mobil- és asztali alkalmazások esetén válassza a Mobil és asztali alkalmazások lehetőséget.
   3. Átirányítási URI-k esetén jelölje be a https://login.microsoftonline.com/common/oauth2/nativeclient jelölőnégyzetet.
   4. Válassza a Konfigurálás lehetőséget.

6. Válassza ki az API-engedélyeket, majd végezze el az alábbi lépéseket az engedélyek hozzáadásához:

   1. Válassza az Engedély hozzáadása gombot .
   2. Válassza a Saját API-k lapot.
   3. Az API-k listájában válassza az AppModelv2-NativeClient-DotNet-TodoListService API-t vagy a webes API-hoz megadott nevet.
   4. Jelölje be a access_as_user engedély jelölőnégyzetet, ha még nincs bejelölve. Szükség esetén használja a Keresőmezőt.
   5. Válassza az Engedélyek hozzáadása gombot.

A projekt konfigurálása

Konfigurálja a TodoListClient-projektet úgy, hogy hozzáadja az alkalmazásazonosítót a app.config fájlhoz.

1. Az Alkalmazásregisztrációk portál Áttekintés lapján másolja ki az alkalmazás (ügyfél) azonosítójának értékét.

2. A TodoListClient projekt gyökérmappájában nyissa meg a app.config fájlt, majd illessze be az alkalmazásazonosító értékét a ida:ClientId paraméterbe.

ASP.NET Core

1. Az IDE-ben nyissa meg a mintát tartalmazó ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI projektmappát.

2. Nyissa meg appsettings.json fájlt, amely a következő kódrészletet tartalmazza:

   {
     "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": "*"
   }
   

   Keresse meg a következő értékeket:

   • ClientId – Az alkalmazás azonosítója, más néven az ügyfél. Cserélje le az value idézőjelek szövegét a regisztrált alkalmazás Áttekintés lapján korábban rögzített alkalmazás-(ügyfél-) azonosítóra.
   • TenantId – Annak a bérlőnek az azonosítója, amelyben az alkalmazás regisztrálva van. Cserélje le az value idézőjelek szövegét a címtár (bérlő) azonosítójának korábban rögzített értékére a regisztrált alkalmazás Áttekintés lapján.
   • Instance – Megadja azt a könyvtárat, amelyből a Microsoft Authentication Library (MSAL) jogkivonatokat kérhet. Cserélje le Enter_the_Authority_URL_Here az alábbi értékek egyikére a forgatókönyvtől függően:
     • A munkaerő-bérlők esetében a https://login.microsoftonline.com/ példaként használja.
     • Külső bérlők esetén adjon hozzá egy szolgáltatói URL-címet a következő formában: https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

A mintaalkalmazás futtatása

ASP.NET

Indítsa el mindkét projektet. Visual Studio-felhasználók számára;

1. Kattintson a jobb gombbal a Visual Studio-megoldásra, és válassza a Tulajdonságok lehetőséget

2. A Közös tulajdonságok területen válassza az Indítási projekt , majd a Több indítási projekt lehetőséget.

3. Mindkét projektnél válassza a Start műveletet

4. Győződjön meg arról, hogy a TodoListService szolgáltatás először elindul, ha a felfelé mutató nyíllal a lista első helyére helyezi.

Jelentkezzen be a TodoListClient-projekt futtatásához.

1. Nyomja le az F5 billentyűt a projektek elindításához. Megnyílik a szolgáltatáslap, valamint az asztali alkalmazás.

2. A TodoListClient jobb felső részén válassza a Bejelentkezés lehetőséget, majd jelentkezzen be ugyanazokkal a hitelesítő adatokkal, amelyeket az alkalmazás regisztrálásához használt, vagy jelentkezzen be felhasználóként ugyanabban a könyvtárban.

   Ha első alkalommal jelentkezik be, előfordulhat, hogy a rendszer kérni fogja, hogy járuljon hozzá a TodoListService webes API-hoz.

   A TodoListService webes API eléréséhez és a teendőlista kezeléséhez a bejelentkezés hozzáférési jogkivonatot is kér a access_as_user hatókörhöz.

Az ügyfélalkalmazás előzetes engedélyezése

Engedélyezheti más könyvtárak felhasználói számára, hogy hozzáférjenek a webes API-hoz, ha előzetesen engedélyezi az ügyfélalkalmazás számára a webes API elérését. Ezt úgy teheti meg, hogy hozzáadja az ügyfélalkalmazás alkalmazásazonosítóját a webes API előhitelesített alkalmazásainak listájához. Egy előhitelesített ügyfél hozzáadásával lehetővé teszi a felhasználók számára, hogy hozzájárulás megadása nélkül férhessenek hozzá a webes API-hoz.

1. Az Alkalmazásregisztrációk portálon nyissa meg a TodoListService alkalmazás tulajdonságait.
2. Az API-k felfedése szakaszban, az Engedélyezett ügyfélalkalmazások területen válassza az Ügyfélalkalmazás hozzáadása lehetőséget.
3. Az Ügyfélazonosító mezőbe illessze be a TodoListClient alkalmazás alkalmazásazonosítóját.
4. Az Engedélyezett hatókörök szakaszban válassza ki a webes API hatókörét api://<Application ID>/access_as_user .
5. Válassza az Alkalmazás hozzáadása lehetőséget.

A projekt futtatása

1. Nyomja le az F5 billentyűt a projekt futtatásához. Megnyílik a TodoListClient alkalmazás.
2. A jobb felső sarokban válassza a Bejelentkezés lehetőséget, majd jelentkezzen be személyes Microsoft-fiókkal, például live.com vagy hotmail.com fiókkal, illetve munkahelyi vagy iskolai fiókkal.

Nem kötelező: Bizonyos felhasználók bejelentkezési hozzáférésének korlátozása

Alapértelmezés szerint minden személyes fiók, például outlook.com vagy live.com fiókok, illetve a Microsoft Entra-azonosítóval integrált szervezetek munkahelyi vagy iskolai fiókjai jogkivonatokat kérhetnek, és hozzáférhetnek a webes API-hoz.

Ha meg szeretné adni, hogy ki tud bejelentkezni az alkalmazásba, módosítsa a tulajdonságot TenantId a appsettings.json fájlban.

ASP.NET Core

1. Futtassa a következő parancsot a webes API-projektkönyvtár gyökeréből az alkalmazás elindításához:

   dotnet run
   

2. Ha minden megfelelően működött, a terminál az alábbihoz hasonló kimenetet jelenít meg:

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

   Jegyezze fel a portszámot az https://localhost:{port} URL-címben.

3. A végpont védelmének ellenőrzéséhez frissítse az alábbi cURL-parancs alap URL-címét úgy, hogy az megfeleljen az előző lépésben kapottnak, majd futtassa a parancsot:

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

   A várt válasz: 401 Jogosulatlan.

Következő lépések

Megtudhatja, hogyan védheti meg a ASP.NET Core webes API-t a Microsoft identitásplatformjával.

Oktatóanyag: ASP.NET Core webes API létrehozása és védelme a Microsoft identitásplatformjával