Snabbstart: Skydda ett ASP.NET Core webb-API

I den här snabbstarten skyddar du ett ASP.NET Core webb-API med Microsoft Entra ID med hjälp av Microsoft. Identity.Web. Du lägger till mellanprogram för autentisering som validerar ägartoken och begränsar åtkomsten till auktoriserade anropare.

Om du inte har en Azure-prenumeration, skapa ett gratis konto innan du börjar.

Förutsättningar

• .NET 9 SDK
• Microsoft Entra ID-klientorganisation. Om du inte har ett, skapa ett gratis konto.
• En appregistrering för ditt API

Alternativ 1: Skapa från mall (snabbast)

Använd mallen ASP.NET Core med inbyggd Microsoft Entra-autentisering för att skapa ett skyddat API-projekt.

1. Skapa projektet

Kör följande kommandon för att skapa ett nytt webb-API-projekt med en organisationsautentisering och navigera till projektkatalogen:

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Konfigurera appregistrering

Ersätt platshållarvärdena i appsettings.json med din Microsoft Entra appregistreringsinformation:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  }
}

3. Kör API:et

Starta programmet:

dotnet run

Ditt API är nu skyddat på https://localhost:5001.

Gjort! Begäranden kräver nu en giltig åtkomsttoken.

Alternativ 2: Lägg till i befintligt webb-API

Om du redan har ett ASP.NET Core webb-API lägger du till Microsoft Entra autentisering med följande steg.

1. Installera NuGet-paketet

Lägg till Microsoft. Identity.Web NuGet-paketet i projektet:

dotnet add package Microsoft.Identity.Web

2. Konfigurera autentisering i Program.cs

Registrera autentiserings- och auktoriseringstjänsterna i appens startpipeline. Följande kod konfigurerar JWT-ägarautentisering med Microsoft Entra validering:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapControllers();

app.Run();

3. Lägg till konfiguration i appsettings.json

Lägg till Microsoft Entra konfigurationsavsnittet med din klient- och programinformation. Ange loggningsnivån för Microsoft.Identity.Web till Information för att felsöka problem med tokenverifiering:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. Skydda dina API-slutpunkter

[Authorize] Använd attributet för kontrollanter eller åtgärder som kräver en giltig åtkomsttoken.

Kräv autentisering för alla slutpunkter:

Följande kontrollant kräver en giltig åtkomsttoken för alla åtgärder och visar hur du får åtkomst till användaranspråk:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Kräv specifika åtkomstomfång:

[RequiredScope] Använd attributet för att framtvinga detaljerade behörigheter för enskilda åtgärder:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Kör och testa

Starta programmet och kontrollera att oautentiserade begäranden avvisas:

dotnet run

Testa med ett verktyg som Postman eller curl. En oautentiserad begäran returnerar 401 Unauthorized:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Framgång! Api:et validerar nu ägartoken.

Konfiguration av appregistrering

Innan ditt API kan verifiera token behöver du en Microsoft Entra appregistrering. Följ de här stegen i Azure-portalen.

1. Registrera ditt API

1. Logga in på portalen Azure
2. Gå till Microsoft Entra ID>App registrations>Ny registrering
3. Ange ett namn (t.ex. "Mitt webb-API")
4. Välj Enskild klient (vanligast för API:er)
5. Ingen omdirigerings-URI behövs för API:er
6. Klicka på Registrera

2. Exponera ett API-omfång

Definiera de behörigheter (omfång) som klientappar kan begära när du anropar ditt API.

1. I din API-appregistrering går du till Exponera ett API
2. Klicka på Lägg till ett omfång
3. Acceptera standard-URI:n för program-ID eller anpassa den (t.ex. api://your-api-client-id)
4. Lägg till ett omfång:
   • Omfångsnamn:access_as_user
   • Vem kan samtycka: Administratörer och användare
   • Visningsnamn för administratörsmedgivande: "Åtkomst till mitt webb-API"
   • Beskrivning av administratörsmedgivande: "Tillåter att appen får åtkomst till webb-API:et för den inloggade användarens räkning"
5. Klicka på Lägg till omfång

3. Anteckna applikations-ID:t

Kopiera program-ID:t (klient) från översiktssidan för appregistrering. Det här värdet är ditt ClientId i appsettings.json.

Skapa en klientappsregistrering (för testning)

Om du vill testa ditt skyddade API registrerar du ett separat klientprogram som hämtar token och anropar API:et.

1. Registrera ett klientprogram

1. Skapa en ny registrering i Microsoft Entra ID>App registrations
2. Ge den namnet (t.ex. "Min API-klient")
3. Välj kontotyper
4. Lägg till omdirigerings-URI: https://localhost:7000/signin-oidc (om det är en webbapp)
5. Klicka på Registrera

2. Bevilja API-behörigheter

Ge klientprogrammet behörighet att anropa ditt API med de omfång som du har definierat.

1. I klientappregistreringen går du till API-behörigheter
2. Klicka på Lägg till en behörighet>Mina API:er
3. Välj din API-registrering
4. Kontrollera omfånget access_as_user
5. Klicka på Lägg till behörigheter
6. Klicka på Bevilja administratörsmedgivande (om det behövs)

3. Skapa en klienthemlighet (för konfidentiella klienter)

Om klientappen körs på en server (inte en webbläsare eller mobil enhet) skapar du en klienthemlighet för autentisering.

1. Gå till Certifikat och hemligheter
2. Klicka på Ny klienthemlighet
3. Lägg till en beskrivning och förfallodatum
4. Klicka på Lägg till
5. Kopiera det hemliga värdet omedelbart – du kommer inte att kunna se det igen

Testa ditt skyddade API

Kontrollera att API:et verifierar token korrekt genom att skicka autentiserade begäranden.

Använda Postman

Konfigurera OAuth 2.0-autentisering i Postman för att hämta en token och anropa ditt API.

1. Skapa en ny begäran i Postman
2. Konfigurera OAuth 2.0-autentisering:
   • Bevilja typ: Auktoriseringskod (för användarkontext) eller klientautentiseringsuppgifter (för appkontext)
   • Autentiserings-URL:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
   • URL för åtkomsttoken:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
   • Klient-ID: Klientappens klient-ID
   • Klienthemlighet: Klientappens hemlighet
   • Omfattning:api://your-api-client-id/access_as_user
3. Klicka på Hämta ny åtkomsttoken
4. Använda token för att anropa ditt API

Använda kod (C#-exempel)

I följande exempel används MSAL.NET för att hämta en token med autentiseringsuppgifterna för klienten och anropa det skyddade API:et:

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Vanliga konfigurationsalternativ

Microsoft. Identity.Web stöder flera konfigurationsmönster för olika scenarier.

Kräv specifika omfång i konfigurationen

I stället för att [RequiredScope] använda attributet kan du konfigurera nödvändiga omfång globalt i appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Acceptera token från flera hyresgäster

Om du vill acceptera token från valfri Microsoft Entra klientorganisation anger du TenantId till common:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Konfigurera tokenverifiering

Om ditt API anropar underordnade API:er (till exempel Microsoft Graph) aktiverar du tokeninsamling och konfigurerar en tokencache:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Nästa steg

Nu när du har ett skyddat API kan du utforska följande ämnen:

• Anropa underordnade API:er – Anropa Microsoft Graph eller andra API:er på användarnas vägnar.
• Konfigurera tokencache – Strategier för produktionscache för OBO-scenarier.
• Tidskrävande processer – Hantera bakgrundsjobb med OBO-token.
• Distribuera bakom en API-gateway – Azure API Management, Azure Front Door, Application Gateway.

Felsökning

401 Inte auktoriserad

Problem: API returnerar 401 även med en token.

Möjliga orsaker:

• Tokenmålgrupp (aud anspråk) matchar inte API:ts ClientId
• Token har upphört att gälla
• Token är för fel hyresgäst
• Obligatoriskt omfång saknas

Lösning: Avkoda token vid jwt.ms och verifiera anspråken. Mer information om felsökning finns i Loggning och diagnostik .

AADSTS50013: Ogiltig signatur

Problem: Valideringen av tokensignatur misslyckas.

Lösning: Se till att din TenantId och ClientId är korrekta. Ett token måste utfärdas av den förväntade utfärdaren. Aktivera detaljerad loggning för att se verifieringsfel.

Scope hittades inte i token

Problem:[RequiredScope] attributet misslyckas.

Lösning:

1. Kontrollera att klientappen har behörighet till omfånget
2. Se till att administratörsmedgivande har beviljats (om det behövs)
3. Se auktoriseringsguiden för fullständiga omfångsverifieringsmönster
4. Kontrollera att omfånget begärs när token hämtas (t.ex. api://your-api/.default eller specifika omfång)

Läs mer:Felsökningsguide för webb-API

Relaterat innehåll

• Auktoriseringsguide – Attributet RequiredScope, auktoriseringsprinciper, klientfiltrering
• Anpassningsguide – Konfigurera JWT-ägaralternativ och valideringsparametrar
• Loggning och diagnostik – Felsöka autentiseringsproblem med korrelations-ID:t
• Självstudie om skyddat webb-API
• API-exempel