Snabbstart: Anropa ett webb-API som skyddas av Microsofts identitetsplattform

Gäller för: medarbetarklienter externa klienter (läs mer)

I den här snabbstarten använder du en exempelwebbapp för att visa hur du skyddar ett ASP.NET webb-API med hjälp av Microsofts identitetsplattform. Exemplet använder Microsoft Authentication Library (MSAL) för att hantera autentisering.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
• Visual Studio 2022. Ladda ned Visual Studio kostnadsfritt.

Registrera webb-API-program

För att slutföra registreringen anger du ett namn för programmet och anger vilka kontotyper som stöds. När det har registrerats visar Översiktssidan de identifierare som behövs i programmets källkod.

1. Logga in på Microsoft Entra-administrationscentret som minst en Programutvecklare.

2. Om du har åtkomst till flera klienter använder du ikonen Inställningar på den översta menyn för att växla till klientorganisationen där du vill registrera programmet från menyn Kataloger + prenumerationer.

3. Bläddra till Identity>Applications>App registrations.

4. Välj Ny registrering.

5. Ange ett Namn för programmet, till exempel NewWebAPI1.

6. För Stödda kontotyper, välj Endast konton i denna organisationskatalog. Om du vill ha information om olika kontotyper väljer du Hjälp mig att välja alternativ.

7. Välj Registrera.

   

8. Programmets översiktsfönster visas när registreringen är klar. Registrera katalog-ID (klientorganisation) och program-ID (klient) för att användas i programmets källkod.

   

Notera

De kontotyper som stöds kan ändras genom att referera till Ändra konton som stöds av ett program.

Exponera ett API

När API:et har registrerats kan du konfigurera dess behörighet genom att definiera de omfång som API:et exponerar för klientprogram. Klientprogram begär behörighet att utföra åtgärder genom att skicka en åtkomsttoken tillsammans med dess begäranden till det skyddade webb-API:et. Webb-API:et utför sedan endast den begärda åtgärden om den åtkomsttoken som den tar emot innehåller de nödvändiga omfången.

ASP.NET

1. Under Hanteraväljer du Exponera ett API>Lägg till ett omfång. Godkänn den föreslagna program-ID-URI:n (api://{clientId}) genom att välja Spara och fortsättaoch ange sedan följande information:

   1. För Omfångsnamnanger du access_as_user.
   2. För Vem kan godkännakontrollerar du att alternativet Administratörer och användare är valt.
   3. I rutan visningsnamn för administratörsmedgivande anger du Access TodoListService as a user.
   4. I rutan Beskrivning av administratörsmedgivande anger du Accesses the TodoListService web API as a user.
   5. I rutan visningsnamn för användarmedgivande anger du Access TodoListService as a user.
   6. I rutan Beskrivning av användarmedgivande anger du Accesses the TodoListService web API as a user.
   7. Behåll Aktiveradför Tillstånd.

2. Välj Lägg till omfång.

ASP.NET CORE

1. Under Hantera, välj Exponera ett API > Lägg till ett omfång. Acceptera den föreslagna program-ID-URI:n(api://{clientId}) genom att välja Spara och fortsätta. {clientId} är värdet som registrerats från sidan Översikt. Ange sedan följande information:

   1. För Omfångsnamnanger du Forecast.Read.
   2. För Vem kan godkännakontrollerar du att alternativet Administratörer och användare är valt.
   3. I rutan för administratörsmedgivandets visningsnamn anger du Read forecast data.
   4. I rutan Administratörsmedgivandebeskrivning skriver du Allows the application to read weather forecast data.
   5. I rutan visningsnamn för användarmedgivande anger du Read forecast data.
   6. I rutan Beskrivning av användarmedgivande anger du Allows the application to read weather forecast data.
   7. Kontrollera att State är inställt på Aktiverad.

2. Välj Lägg till omfång. Om omfånget har angetts korrekt visas det i fönstret Exponera ett API.

   

Klona eller ladda ned exempelprogrammet

Om du vill hämta exempelprogrammet kan du antingen klona det från GitHub eller ladda ned det som en .zip fil.

ASP.NET

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

• Ladda ned den som en ZIP-fil.

Tips

För att undvika fel som orsakas av sökvägslängdsbegränsningar i Windows rekommenderar vi att du extraherar arkivet eller klonar lagringsplatsen till en katalog nära roten på enheten.

ASP.NET CORE

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

• Ladda ned filen .zip. Extrahera den till en filsökväg där namnets längd är mindre än 260 tecken.

Konfigurera exempelprogrammet

Konfigurera kodexemplet så att det matchar det registrerade webb-API:et.

ASP.NET

1. Öppna lösningen i Visual Studio och öppna sedan filen appsettings.json under roten i TodoListService-projektet.

2. Ersätt värdet på Enter_the_Application_Id_here med värdet för klient-ID (program-ID) från det program som du registrerade i appenregistreringarnas portal både i ClientID och Audience egenskaper.

Lägg till det nya omfånget i filen app.config

Följ dessa steg om du vill lägga till det nya omfånget i filen TodoListClient app.config:

1. I rotmappen för TodoListClient-projektet öppnar du filen app.config.

2. Klistra in program-ID:t från det program som du registrerade för ditt TodoListService-projekt i parametern TodoListServiceScope och ersätt {Enter the Application ID of your TodoListService from the app registration portal} strängen.

Not

Kontrollera att program-ID:t använder följande format: api://{TodoListService-Application-ID}/access_as_user (där {TodoListService-Application-ID} är DET GUID som representerar program-ID:t för din TodoListService-app).

Registrera webbappen (TodoListClient)

Registrera din TodoListClient-app i Appregistreringar i Azure-portalen och konfigurera sedan koden i Projektet TodoListClient. Om klienten och servern anses vara samma program kan du återanvända programmet som är registrerat i steg 2. Använd samma program om du vill att användarna ska logga in med ett personligt Microsoft-konto.

Registrera appen

Följ dessa steg för att registrera TodoListClient-appen:

1. Logga in på administrationscentret för Microsoft Entra som minst en molnprogramadministratör.

2. Navigera till Identity>Applications>App registrations och välj Ny registrering.

3. Välj Ny registrering.

4. När Registrera en programsida öppnas anger du programmets registreringsinformation:

   1. I avsnittet Namn anger du ett beskrivande programnamn som ska visas för appens användare (till exempel NativeClient-DotNet-TodoListClient).
   2. För kontotyper som stödsväljer du Konton i en organisationskatalog.
   3. Välj Registrera för att skapa programmet.

   Not

   I filen TodoListClient-projektet app.config anges standardvärdet för ida:Tenant till common. Möjliga värden är:

   • common: Du kan logga in med ett arbets- eller skolkonto eller ett personligt Microsoft-konto (eftersom du valde Konton i en organisationskatalog i ett tidigare steg).
   • organizations: Du kan logga in med hjälp av ett arbets- eller skolkonto.
   • consumers: Du kan bara logga in med ett personligt Microsoft-konto.

5. På sidan Översikt väljer du Authenticationoch slutför sedan de här stegen för att lägga till en plattform:

   1. Under Platform-konfigurationerväljer du knappen Lägg till en plattform.
   2. För Mobil- och skrivbordsprogramväljer du Mobil- och skrivbordsprogram.
   3. För omdirigerings-URI:er , välj kryssrutan https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Välj Konfigurera.

6. Välj API-behörigheteroch slutför sedan de här stegen för att lägga till behörigheter:

   1. Välj knappen Lägg till en behörighet.
   2. Välj fliken Mina API:er.
   3. I listan över API:er väljer du AppModelv2-NativeClient-DotNet-TodoListService API- eller det namn som du angav för webb-API:et.
   4. Markera kryssrutan för access_as_user behörigheten om den inte redan är markerad. Använd sökrutan om det behövs.
   5. Välj knappen Lägg till behörigheter.

Konfigurera projektet

Konfigurera ditt TodoListClient-projekt genom att lägga till program-ID:t i filen app.config.

1. I Appregistreringar-portalen, på sidan Översikt, kopierar du värdet för Application (klient)-ID:t.

2. Från rotmappen TodoListClient-projektet öppnar du filen app.config och klistrar sedan in program-ID-värdet i parametern ida:ClientId.

ASP.NET CORE

1. I din IDE öppnar du projektmappen ms-identity-docs-code-dotnet/web-api, som innehåller exemplet.

2. Öppna appsettings.json fil som innehåller följande kodfragment:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   Hitta följande key:

   • ClientId – Programmets identifierare, även kallad klienten. Ersätt den value texten inom citattecken med program-ID (klient) som spelades in tidigare från sidan Översikt i det registrerade programmet.
   • TenantId – identifieraren för den klientorganisation där programmet är registrerat. Ersätt texten i citattecken value med Directory (tenant) ID-värde som registrerades tidigare från sidan Översikt för den registrerade applikationen.

Kör exempelprogrammet

ASP.NET

Starta båda projekten. För Visual Studio-användare;

1. Högerklicka på Visual Studio-lösningen och välj Egenskaper

2. I Vanliga egenskaper väljer du Startprojekt och sedan Flera startprojekt.

3. För båda projekten väljer du Starta som åtgärd

4. Kontrollera att TodoListService-tjänsten startar först genom att flytta den till den första positionen i listan med hjälp av uppåtpilen.

Logga in för att köra ditt TodoListClient-projekt.

1. Tryck på F5 för att starta projekten. Tjänstsidan öppnas samt skrivbordsprogrammet.

2. I TodoListClient, längst upp till höger, väljer du Logga inoch loggar sedan in med samma autentiseringsuppgifter som du använde för att registrera ditt program eller logga in som en användare i samma katalog.

   Om du loggar in för första gången kan du uppmanas att godkänna Webb-API:et TodoListService.

   För att hjälpa dig att komma åt TodoListService-webb-API:et och ändra att-göra--listan begär inloggningen också en åtkomsttoken för access_as_user behörighet.

Förauktorisera klientprogrammet

Du kan tillåta användare från andra kataloger att komma åt webb-API:et genom att förauktorisera klientprogrammet för åtkomst till webb-API:et. Det gör du genom att lägga till program-ID:t från klientappen i listan över förauktoriserade program för webb-API:et. Genom att lägga till en förauktoriserat klient tillåter du användare att komma åt ditt webb-API utan att behöva ge medgivande.

1. Öppna egenskaperna för din TodoListService-app i portalen för appregistreringar.
2. I avsnittet Exponera ett API går du till Auktoriserade klientprogramoch väljer Lägg till ett klientprogram.
3. I rutan klient-ID klistrar du in program-ID:t för TodoListClient-appen.
4. I avsnittet Auktoriserade omfång väljer du omfånget för api://<Application ID>/access_as_user webb-API.
5. Välj Lägg till program.

Kör projektet

1. Tryck på F5 för att köra projektet. Din TodoListClient-app öppnas.
2. Längst upp till höger väljer du Logga inoch loggar sedan in med ett personligt Microsoft-konto, till exempel ett live.com- eller hotmail.com-konto eller ett arbets- eller skolkonto.

Valfritt: Begränsa inloggningsåtkomsten till vissa användare

Som standard kan alla personliga konton, till exempel outlook.com eller live.com konton eller arbets- eller skolkonton från organisationer som är integrerade med Microsoft Entra-ID, begära token och komma åt ditt webb-API.

Om du vill ange vem som kan logga in på ditt program ändrar du egenskapen TenantId i filen appsettings.json.

ASP.NET CORE

1. Kör följande kommando för att starta appen:

   dotnet run
   

2. Utdata som följande exempel visas:

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:{port}
   ...
   

   Registrera portnumret i http://localhost:{port}-URL:en.

3. Kontrollera att slutpunkten är skyddad genom att uppdatera bas-URL:en i följande cURL-kommando så att den matchar den du fick i föregående steg och kör sedan kommandot:

   curl -X GET https://localhost:5001/weatherforecast -ki
   

   Det förväntade svaret är 401 Obehörig med utdata som liknar:

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

Nästa steg

ASP.NET

Läs mer genom att skapa ett skyddat ASP.NET Core-webb-API i följande självstudieserie:

Skyddat webb-API handledning

ASP.NET CORE

Gå vidare till nästa artikel för att lära dig hur du anropar det skyddade webb-API:et med hjälp av cURL.

Instruktioner: Anropa ett ASP.NET Core-webb-API med cURL-