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

Den här artikeln visar hur du anropar ett skyddat ASP.NET Core-webb-API med hjälp av klient-URL (cURL). cURL är ett kommandoradsverktyg som utvecklare använder för att överföra data till och från en server. I den här artikeln registrerar du en webbapp och ett webb-API i en klientorganisation. Webbappen används för att hämta en åtkomsttoken som genereras av Microsofts identitetsplattform. Sedan använder du token för att göra ett auktoriserat anrop till webb-API:et med hjälp av cURL.

Den här artikeln visar hur du anropar ett skyddat ASP.NET Core-webb-API med hjälp av klient-URL (cURL). cURL är ett kommandoradsverktyg som utvecklare använder för att överföra data till och från en server. I självstudien: Implementera en skyddad slutpunkt till ditt API, där du skapade ett skyddat API, måste du registrera ett webbprogram med Microsofts identitetsplattform för att generera en åtkomsttoken. Sedan använder du token för att göra ett auktoriserat anrop till API:et med hjälp av cURL.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Det här Azure-kontot måste ha behörighet att hantera program. Någon av följande Microsoft Entra-roller innehåller de behörigheter som krävs:
  • Programadministratör
  • Programutvecklare
  • Molnprogramadministratör
• Ladda ned och installera cURL på arbetsstationsdatorn.
• Ett minimikrav på .NET 8.0 SDK.

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Det här Azure-kontot måste ha behörighet att hantera program. Någon av följande Microsoft Entra-roller innehåller de behörigheter som krävs:
  • Programadministratör
  • Programutvecklare
  • Molnprogramadministratör
• Slutförande av självstudieserien:
  • Självstudie: Registrera webb-API med Microsofts identitetsplattform.
  • Självstudie: Skapa och konfigurera ett ASP.NET Core-projekt för autentisering.
  • Självstudie: Implementera en skyddad slutpunkt i ditt API.
• Ladda ned och installera cURL på arbetsstationsdatorn.

Registrera en app på Microsoft Identity Platform

Microsofts identitetsplattform kräver att ditt program registreras innan du tillhandahåller identitets- och åtkomsthanteringstjänster. Med programregistreringen kan du ange namnet och typen av programmet och inloggningspubliken. Inloggningspubliken anger vilka typer av användarkonton som tillåts logga in på ett visst program.

Registrera webb-API:et

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

Följ dessa steg för att skapa webb-API-registreringen:

1. Logga in på administrationscentret för Microsoft Entra som minst 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 den klientorganisation där du vill registrera programmet från menyn Kataloger + prenumerationer.

3. Bläddra till Identitetsprogram>> Appregistreringar.

4. Välj Ny registrering.

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

6. För Kontotyper som stöds väljer du Endast konton i den här organisationskatalogen. Om du vill ha information om olika kontotyper väljer du Alternativet Hjälp mig att välja .

7. Välj Registrera.

   

8. Programmets översiktsfönster visas när registreringen är klar. Registrera katalog-ID:t (klient)-ID:t och program-ID:t (klient) som ska användas i programmets källkod.

   

Kommentar

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

Exponera API:et

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 är giltig.

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

   1. Som Omfångsnamn anger du Forecast.Read.
   2. För Vem kan samtycka kontrollerar du att alternativet Administratörer och användare är valt.
   3. I rutan Visningsnamn för administratörsmedgivande anger du Read forecast data.
   4. I rutan Beskrivning av administratörsmedgivande anger 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 tillståndet är inställt på Aktiverad.

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

   

Registrera webbappen

Att ha ett webb-API räcker dock inte eftersom en webbapp också behövs för att hämta en åtkomsttoken för att få åtkomst till webb-API:et som du har skapat.

Följ dessa steg för att skapa registrering av webbappar:

1. Välj Start för att återgå till startsidan. Bläddra till Identitetsprogram>> Appregistreringar.
2. Välj Ny registrering.
3. Ange ett namn för programmet, till exempel web-app-calls-web-api.
4. För Kontotyper som stöds väljer du Endast konton i den här organisationskatalogen. Om du vill ha information om olika kontotyper väljer du alternativet Hjälp mig .
5. Under Omdirigerings-URI (valfritt) väljer du Webb och anger http://localhost sedan i textrutan URL.
6. Välj Registrera.

1. Logga in på administrationscentret för Microsoft Entra som minst 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 den klientorganisation där du vill registrera programmet från menyn Kataloger + prenumerationer.
3. Bläddra till Identitetsprogram>> Appregistreringar.
4. Välj Ny registrering.
5. Ange ett namn för programmet, till exempel web-app-calls-web-api.
6. För Kontotyper som stöds väljer du Endast konton i den här organisationskatalogen. Om du vill ha information om olika kontotyper väljer du alternativet Hjälp mig .
7. Under Omdirigerings-URI (valfritt) väljer du Webb och anger http://localhost sedan i textrutan URL.
8. Välj Registrera.

När registreringen är klar visas appregistreringen i fönstret Översikt . Registrera katalog-ID:t (klient)-ID:t och program-ID:t (klient) som ska användas i senare steg.

Lägg till en klienthemlighet

En klienthemlighet är ett strängvärde som appen kan använda för själva identiteten och kallas ibland för ett programlösenord. Webbappen använder klienthemligheten för att bevisa sin identitet när den begär token.

Följ dessa steg för att konfigurera en klienthemlighet:

1. I fönstret Översikt går du till Hantera och väljer Certifikat och hemligheter>Klienthemligheter>Ny klienthemlighet.

2. Lägg till en beskrivning för din klienthemlighet, till exempel Min klienthemlighet.

3. Välj en förfallotidpunkt för hemligheten eller ange en anpassad livslängd.

   • En klienthemlighets livslängd är begränsad till två år (24 månader) eller mindre. Du kan inte ange en anpassad livslängd som är längre än 24 månader.
   • Microsoft rekommenderar att du anger ett förfallovärde på mindre än 12 månader.

4. Markera Lägga till.

5. Se till att registrera värdet för klienthemligheten. Det här hemliga värdet visas aldrig igen när du har lämnat den här sidan.

Lägga till programbehörigheter för att tillåta åtkomst till ett webb-API

Genom att ange webb-API:ets omfång i webbappregistreringen kan webbappen hämta en åtkomsttoken som innehåller de omfång som tillhandahålls av Microsofts identitetsplattform. I koden kan webb-API:et sedan ge behörighetsbaserad åtkomst till dess resurser baserat på de omfång som finns i åtkomsttoken.

Följ dessa steg för att konfigurera webbappens behörigheter till webb-API:et:

1. I fönstret Översikt i webbprogrammet (web-app-that-calls-web-api) under Hantera väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder.
2. Välj NewWebAPI1 eller det API som du vill lägga till behörigheter till.
3. Markera kryssrutan bredvid Forecast.Read under Välj behörigheter. Du kan behöva expandera behörighetslistan. Detta väljer de behörigheter som klientappen ska ha för den inloggade användarens räkning.
4. Välj Lägg till behörigheter för att slutföra processen.

När du har lagt till dessa behörigheter i ditt API bör du se de valda behörigheterna under Konfigurerade behörigheter.

Du kan också märka behörigheten User.Read för Microsoft Graph-API:et. Den här behörigheten läggs till automatiskt när du registrerar en app.

Testa webb-API:et

1. Klona lagringsplatsen ms-identity-docs-code-dotnet.

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

2. Gå till ms-identity-docs-code-dotnet/web-api mappen och öppna ./appsettings.json filen, ersätt {APPLICATION_CLIENT_ID} och {DIRECTORY_TENANT_ID} med:

   • {APPLICATION_CLIENT_ID}är webb-API-program-ID :t (klient) i appens översiktsfönster Appregistreringar.
   • {DIRECTORY_TENANT_ID}är webb-API-katalog-ID :t (klientorganisation) i appens översiktsfönster Appregistreringar.

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

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

4. Utdata som liknar följande visas. Registrera portnumret i https://localhost:{port} URL:en.

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

Testa webb-API:et

1. Navigera till webb-API:et som skapades i Självstudie: Skapa ett ASP.NET Core-projekt och konfigurera API:et, till exempel NewWebAPILocal, och öppna mappen.

2. Öppna ett nytt terminalfönster och navigera till mappen där webb-API-projektet finns.

.NET 6.0

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

   dotnet run
   

.NET 7.0

1. Kör följande kommando för att starta appen på profilen https :

   dotnet run --launch-profile https
   

1. Utdata som liknar följande visas. Registrera portnumret i https://localhost:{port} URL:en.

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

Begära en auktoriseringskod

Auktoriseringskodflödet börjar med att klienten dirigerar användaren till /authorize slutpunkten. I den här begäran begär klienten behörigheten Forecast.Read från användaren.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

1. Kopiera URL:en, ersätt följande parametrar och klistra in den i webbläsaren:

   • {tenant_id} är webbappens katalog-ID (klientorganisation).
   • {web-app-calls-web-api_application_client_id}är program-ID:t (klient) i webbappens översiktsfönster (web-app-calls-web-api).
   • {web_API_application_client_id}är program-ID :t (klient) i webb-API:ets översiktsfönster (NewWebAPI1).

2. Logga in som en användare i Microsoft Entra-klientorganisationen där apparna är registrerade. Godkänn eventuella begäranden om åtkomst, om det behövs.

3. Webbläsaren omdirigeras till http://localhost/. Läs webbläsarens navigeringsfält och kopiera det som {authorization_code} ska användas i följande steg. URL:en har formen av följande kodfragment:

   http://localhost/?code={authorization_code}
   

Använda en auktoriseringskod och cURL för att hämta en åtkomsttoken

cURL kan nu användas för att begära en åtkomsttoken från Microsofts identitetsplattform.

1. Kopiera cURL-kommandot i följande kodfragment. Ersätt värdena i parenteser med följande parametrar till terminalen. Se till att ta bort parenteserna:

   Våldsamt slag

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
   -d 'client_id={web-app-calls-web-api_application_client_id}' \
   -d 'api://{web_API_application_client_id}/Forecast.Read' \
   -d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
   -d 'redirect_uri=http://localhost' \
   -d 'grant_type=authorization_code' \
   -d 'client_secret={client_secret}'
   

   Kommandotolken i Windows

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
    -d "client_id={web-app-calls-web-api_application_client_id}" ^
    -d "api://{web_API_application_client_id}/Forecast.Read" ^
    -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
    -d "redirect_uri=http://localhost" ^
    -d "grant_type=authorization_code" ^
    -d "client_secret={client_secret}"
   

   • {tenant_id} är webbappens katalog-ID (klientorganisation).
   • client_id={web-app-calls-web-api_application_client_id}, och session_state={web-app-calls-web-api_application_client_id} är program-ID:t (klient) i webbprogrammets översiktsfönster (web-app-calls-web-api).
   • api://{web_API_application_client_id}/Forecast.Readär program-ID :t (klient) i webb-API:ets översiktsfönster (NewWebAPI1).
   • code={authorization_code} är auktoriseringskoden som togs emot i Begär en auktoriseringskod. På så sätt kan cURL-verktyget begära en åtkomsttoken.
   • client_secret={client_secret}är det värde för klienthemlighet som registrerats i Lägg till en klienthemlighet.

2. Kör cURL-kommandot och om det anges korrekt bör du få ett JSON-svar som liknar följande utdata:

   {
      "token_type": "Bearer",
      "scope": "api://{web_API_application_client_id}/Forecast.Read",
      "expires_in": 3600,
      "ext_expires_in": 3600,
      "access_token": "{access_token}"
   }
   

Anropa webb-API med åtkomsttoken

Genom att köra föregående cURL-kommando har Microsofts identitetsplattform angett en åtkomsttoken. Den förvärvade token kan nu användas som en bärare i en HTTP-begäran för att anropa webb-API:et.

1. Om du vill anropa webb-API:et kopierar du följande cURL-kommando, ersätter följande värden inom parenteser och klistrar in det i terminalen:

   curl -X GET https://localhost:{port}/weatherforecast -ki \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer {access_token}"
   

   • {access_token} värdet för åtkomsttoken som registrerats från JSON-utdata i föregående avsnitt.
   • {port} portnumret från webb-API:et som registrerades när API:et kördes i terminalen. Kontrollera att det är https portnumret.

2. Med en giltig åtkomsttoken som ingår i begäran är HTTP/2 200 det förväntade svaret med utdata som liknar följande utdata:

   HTTP/2 200
   content-type: application/json; charset=utf-8
   date: Day, DD Month YYYY HH:MM:SS
   server: Kestrel
   [{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]
   

Nästa steg

Mer information om OAuth 2.0-auktoriseringskodflöde och programtyper finns i:

• Microsofts identitetsplattform och kodflöde för OAuth 2.0-auktorisering
• Programtyper för Microsofts identitetsplattform