Quickstart: Een ASP.NET Core-web-API beveiligen

In deze quickstart beveiligt u een ASP.NET Core web-API met Microsoft Entra ID met behulp van Microsoft. Identity.Web. U voegt verificatie-middleware toe waarmee bearer-tokens worden gevalideerd en de toegang wordt beperkt tot geautoriseerde bellers.

Als je geen Azure-abonnement hebt, maak dan een gratis account aan voordat je begint.

Vereiste voorwaarden

Optie 1: Maken van sjabloon (snelste)

Gebruik de ASP.NET Core-sjabloon met ingebouwde Microsoft Entra verificatie om een beveiligd API-project te maken.

1. Het project maken

Voer de volgende opdrachten uit om een nieuw web-API-project te maken met verificatie met één organisatie en navigeer naar de projectmap:

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

2. App-registratie configureren

Vervang de waarden van de tijdelijke aanduidingen in appsettings.json door de registratiegegevens van uw Microsoft Entra-app:

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

3. Voer de API uit

Start de toepassing:

dotnet run

Uw API is nu beveiligd op https://localhost:5001.

Gereed! Aanvragen vereisen nu een geldig toegangstoken.

Optie 2: Toevoegen aan bestaande web-API

Als u al een ASP.NET Core web-API hebt, voegt u Microsoft Entra verificatie toe met de volgende stappen.

1. NuGet-pakket installeren

Voeg het Microsoft.Identity.Web NuGet-pakket aan uw project toe.

dotnet add package Microsoft.Identity.Web

2. Verificatie configureren in Program.cs

Registreer de verificatie- en autorisatieservices in de opstartpijplijn van uw app. Met de volgende code configureert u JWT Bearer-verificatie met Microsoft Entra validatie:

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. Configuratie toevoegen aan appsettings.json

Voeg de sectie Microsoft Entra configuratie toe met uw tenant- en toepassingsgegevens. Stel het logboekregistratieniveau voor Microsoft.Identity.Web in op Information om problemen met tokenvalidatie op te lossen:

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

4. Uw API-eindpunten beveiligen

Pas het [Authorize] kenmerk toe op controllers of acties waarvoor een geldig toegangstoken is vereist.

Verificatie vereisen voor alle eindpunten:

De volgende controller vereist een geldig toegangstoken voor alle acties en laat zien hoe u toegang hebt tot gebruikersclaims:

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"
        });
    }
}

Specifieke bereiken vereisen:

Gebruik het [RequiredScope] kenmerk om gedetailleerde machtigingen af te dwingen voor afzonderlijke acties:

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. Uitvoeren en testen

Start de toepassing en controleer of niet-geverifieerde aanvragen worden geweigerd:

dotnet run

Test met een hulpprogramma zoals Postman of curl. Een niet-geverifieerde aanvraag retourneert 401 Unauthorized:

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

Gelukt! Uw API valideert nu bearer-tokens.

Instellen van app-registratie

Voordat uw API tokens kan valideren, hebt u een Microsoft Entra app-registratie nodig. Volg deze stappen in de Azure-portal.

1. Registreer uw API

  1. Meld u aan bij de Azure-portal
  2. Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie
  3. Voer een naam in (bijvoorbeeld 'Mijn web-API')
  4. Eén tenant selecteren (meest voorkomende voor API's)
  5. Er is geen omleidings-URI nodig voor API's
  6. Klik op Registreren

2. Een API-bereik beschikbaar maken

Definieer de machtigingen (bereiken) die client-apps kunnen aanvragen bij het aanroepen van uw API.

  1. Ga in de registratie van uw API-app naar Een API beschikbaar maken
  2. Klik op Een bereik toevoegen
  3. Accepteer de standaard-URI van de toepassings-id of pas deze aan (bijvoorbeeld api://your-api-client-id)
  4. Een bereik toevoegen:
    • Bereiknaam:access_as_user
    • Wie kan toestemming geven: Beheerders en gebruikers
    • Weergavenaam van beheerderstoestemming: "Mijn web-API openen"
    • Beschrijving van beheerderstoestemming: "Hiermee kan de app namens de aangemelde gebruiker toegang krijgen tot de web-API"
  5. Klik op Bereik toevoegen

3. Noteer de toepassings-id

Kopieer de Applicatie-ID (client) van de overzichtspagina van de app-registratie. Deze waarde is uw ClientId in appsettings.json.

Een registratie van een client-app maken (voor testen)

Als u uw beveiligde API wilt testen, registreert u een afzonderlijke clienttoepassing die tokens verkrijgt en de API aanroept.

1. Een clienttoepassing registreren

  1. Maak in Microsoft Entra ID>App-registraties een andere registratie
  2. Geef deze een naam (bijvoorbeeld 'Mijn API-client')
  3. Accounttypen selecteren
  4. Omleidings-URI toevoegen: https://localhost:7000/signin-oidc (als het een web-app is)
  5. Klik op Registreren

2. API-machtigingen verlenen

Geef de clientapplicatie toestemming om uw API aan te roepen met de scopes die u hebt gedefinieerd.

  1. Ga in de registratie van de client-app naar API-machtigingen
  2. Klik op Een machtiging> toevoegenmijn API's
  3. Selecteer uw API-registratie
  4. Controleer de access_as_user scope
  5. Klik op Machtigingen toevoegen
  6. Klik op Beheerderstoestemming verlenen (indien nodig)

3. Maak een clientgeheim (voor vertrouwelijke clients)

Als uw client-app wordt uitgevoerd op een server (geen browser of mobiel apparaat), maakt u een clientgeheim voor verificatie.

  1. Ga naar Certificaten en geheimen
  2. Klik op Nieuw clientgeheim
  3. Een beschrijving en verlooptijd toevoegen
  4. Klik op Toevoegen
  5. Kopieer de geheime waarde onmiddellijk . U kunt deze niet meer zien

Uw beveiligde API testen

Controleer of uw API tokens correct valideert door geverifieerde aanvragen te verzenden.

Postman gebruiken

Stel OAuth 2.0-verificatie in Postman in om een token te verkrijgen en uw API aan te roepen.

  1. Een nieuwe aanvraag maken in Postman
  2. OAuth 2.0-verificatie instellen:
    • Toekenningstype: Autorisatiecode (voor gebruikerscontext) of clientreferenties (voor app-context)
    • Verificatie-URL:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • URL van toegangstoken:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • Client-id: De client-id van uw client-app
    • Clientgeheim: Het geheim van uw client-app
    • Reikwijdte:api://your-api-client-id/access_as_user
  3. Klik op Nieuw toegangstoken ophalen
  4. Het token gebruiken om uw API aan te roepen

Code gebruiken (C#-voorbeeld)

In het volgende voorbeeld wordt MSAL.NET gebruikt om een token te verkrijgen met de clientreferentiestroom en de beveiligde API aan te roepen:

// 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");

Algemene configuratieopties

Microsoft. Identity.Web ondersteunt verschillende configuratiepatronen voor verschillende scenario's.

Specifieke bereiken in configuratie vereisen

In plaats van het [RequiredScope] kenmerk te gebruiken, kunt u de vereiste toepassingsgebieden globaal configureren in appsettings.json:

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

Tokens van meerdere tenants accepteren

Als u tokens van een Microsoft Entra tenant wilt accepteren, stelt u TenantId in op common:

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

Tokenvalidatie configureren

Als uw API downstream-API's aanroept (zoals Microsoft Graph), schakelt u het verkrijgen van tokens in en configureert u een tokencache:

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

Volgende stappen 

Nu u een beveiligde API hebt, bekijkt u deze onderwerpen:

Troubleshooting

401 Niet geautoriseerd

Probleem: API retourneert 401 zelfs met een token.

Mogelijke oorzaken:

  • Token-gebruiker (aud claim) komt niet overeen met uw API ClientId
  • De token is verlopen
  • Token is voor de verkeerde tenant
  • Vereist bereik ontbreekt

Oplossing: Decoder het token op jwt.ms en controleer de claims. Zie Logboekregistratie en diagnostische gegevens voor gedetailleerde probleemoplossing.

AADSTS50013: Ongeldige handtekening

Probleem: Validatie van tokenhandtekening mislukt.

Oplossing: Zorg ervoor dat uw TenantId en ClientId juist zijn. Het token moet worden uitgegeven door de verwachte instantie. Schakel gedetailleerde logboekregistratie in om validatiefouten te bekijken.

Scopes niet gevonden in de token

Probleem:[RequiredScope] kenmerk mislukt.

Solution:

  1. Controleer of de client-app toestemming heeft voor het toepassingsbereik
  2. Controleren of beheerderstoestemming is verleend (indien nodig)
  3. Zie Autorisatiehandleiding voor volledige scope-validatiepatronen.
  4. Controleer of het bereik wordt aangevraagd bij het verkrijgen van het token (bijvoorbeeld api://your-api/.default of specifieke bereiken)

Zie meer:Handleiding voor het oplossen van problemen met web-API's

Verwante inhoud

  • Last updated on