Delen via

Zelfstudie: Een ASP.NET Core-web-API bouwen en beveiligen met het Microsoft Identity Platform

  • Artikel

Van toepassing op: Groene cirkel met een wit vinkje. Personeelsgebruikers Groene cirkel met een wit vinkje. Externe gebruikers (lees meer)

Deze reeks zelfstudies laat zien hoe u een ASP.NET Core-web-API beveiligt met het Microsoft Identity Platform om de toegang tot alleen geautoriseerde gebruikers en client-apps te beperken. De web-API die u bouwt, maakt gebruik van zowel gedelegeerde machtigingen (bereiken) als toepassingsmachtigingen (app-rollen).

In deze zelfstudie gaat u het volgende doen:

  • Een ASP.NET Core-web-API bouwen
  • De web-API configureren voor het gebruik van de microsoft Entra-app-registratiegegevens
  • Uw web-API-eindpunten beveiligen
  • Voer de web-API uit om ervoor te zorgen dat deze luistert naar HTTP-aanvragen

Voorwaarden

Een nieuw ASP.NET Core-web-API-project maken

Voer de volgende stappen uit om een minimaal ASP.NET Core-web-API-project te maken:

  1. Open uw terminal in Visual Studio Code of een andere code-editor en navigeer naar de map waar u uw project wilt maken.

  2. Voer de volgende opdrachten uit op de .NET CLI of een ander opdrachtregelprogramma.

    dotnet new webapi -n MyProtectedApi
cd MyProtectedApi

  3. Selecteer Ja wanneer u in een dialoogvenster wordt gevraagd of u de auteurs wilt vertrouwen.

  4. Selecteer Ja Wanneer u in een dialoogvenster wordt gevraagd of u de vereiste assets wilt toevoegen aan het project.

Vereiste pakketten installeren

Als u een ASP.NET Core-web-API wilt beveiligen, hebt u het Microsoft.Identity.Web-pakket nodig: een set ASP.NET Core-bibliotheken die het toevoegen van ondersteuning voor verificatie en autorisatie vereenvoudigen voor web-apps en web-API's die zijn geïntegreerd met het Microsoft Identity Platform.

Als u het pakket wilt installeren, gebruikt u:

dotnet add package Microsoft.Identity.Web

Details van app-registratie configureren

Open het appsettings.json-bestand in de app-map en voeg de app-registratiegegevens toe die u hebt vastgelegd nadat u de web-API hebt geregistreerd.

{
    "AzureAd": {
        "Instance": "Enter_the_Authority_URL_Here",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

Vervang de volgende tijdelijke aanduidingen zoals weergegeven:

  • Vervang Enter_the_Application_Id_Here door de id van uw toepassing (client).
  • Vervang Enter_the_Tenant_Id_Here door uw directory-ID (tenant-ID).
  • Vervang Enter_the_Authority_URL_Here door de URL van uw instantie, zoals wordt uitgelegd in de volgende sectie.

URL van de autoriteit voor uw app

De instantie-URL specificeert de directory waarvan Microsoft Authentication Library (MSAL) tokens kan aanvragen. Het is op een andere manier samengesteld, zowel qua werknemers als externe huurders, zoals wordt weergegeven:

//Instance for workforce tenant
Instance: "https://login.microsoftonline.com/"

Aangepast URL-domein gebruiken (optioneel)

Aangepaste URL-domeinen worden niet ondersteund in werkplekhuren.

App-rol en -bereik toevoegen

Alle API's moeten minimaal één scope, ook wel gedelegeerde machtiging genoemd, publiceren zodat de client-apps met succes een toegangstoken voor een gebruiker kunnen verkrijgen. API's moeten ook minimaal één app-rol, ook wel toepassingsmachtigingen genoemd, publiceren, zodat de client-apps zelf een toegangstoken kunnen verkrijgen, dat wil gezegd wanneer ze zich niet aanmelden bij een gebruiker.

We geven deze machtigingen op in het appsettings.json-bestand. In deze zelfstudie registreert u zowel gedelegeerde als toepassingsmachtigingen met de machtigingsgebieden 'Forecast.Read'. Dit betekent dat alleen gebruikers of clienttoepassingen die de API aanroepen met een toegangstoken met het bereik 'Forecast.Read' geautoriseerd worden voor toegang tot het beveiligde eindpunt.

{
  "AzureAd": {
    "Instance": "Enter_the_Authority_URL_Here",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": "Forecast.Read",
    },
    "AppPermissions": {
      "Read": ["Forecast.Read"],
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}

Verificatie en autorisatie implementeren in de API

Als u verificatie en autorisatie wilt configureren, opent u het program.cs-bestand en vervangt u de inhoud van de volgende codefragmenten:

Een verificatieschema toevoegen

In deze API gebruiken we het Bearer-schema JSON Web Token (JWT) als het standaardverificatiemechanisme. Gebruik de methode AddAuthentication om het JWT bearer-schema te registreren.

// Import the required packages

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

var builder = WebApplication.CreateBuilder(args);

// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.NameClaimType = "name";
    }, options => { builder.Configuration.Bind("AzureAd", options); });

Autorisatie configureren

Autorisatie bepaalt wat een geverifieerde gebruiker mag doen. nl-NL: We definiëren een beleid met de naam AuthZPolicy, waarvoor de client die de API aanroept de Forecast.Read-rol moet hebben voor client-apps of de Forecast.Read-scope voor een aangemelde gebruiker.

builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
    policy.RequireRole("Forecast.Read"));
});

De methode AddPolicy maakt een benoemd beleid (AuthZPolicy) dat controleert op de aanwezigheid van de Forecast.Read rol in de tokenclaims van de gebruiker. Als het token ontbreekt aan de roles claim, wordt de toegang tot eindpunten waarvoor dit beleid is vereist, geweigerd.

De HTTP-aanvraagpijplijn bouwen

In deze zelfstudie gebruiken we een minimale API zonder controllers, omdat de focus meer ligt op het beveiligen van de API. We configureren de API middleware-pijplijn door het volgende toe te voegen:

  • HTTPS-omleiding: veilige communicatie afdwingen door HTTP-aanvragen om te leiden naar HTTPS.
  • verificatie-middleware: hiermee worden binnenkomende tokens gevalideerd voordat aanvragen worden verwerkt.
  • autorisatie-middleware: past beleid toe na verificatie, zodat alleen geautoriseerde clients toegang hebben tot beveiligde eindpunten.
var app = builder.Build();

// Configure the HTTP request pipeline

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

Het eindpunt voor weersvoorspelling definiëren

Het /weatherforecast-eindpunt genereert een willekeurige prognose van vijf dagen, beveiligd door het autorisatiebeleid. RequireAuthorization("AuthZPolicy") zorgt ervoor dat alleen clients met de rol Forecast.Read toegang hebben tot deze rol.

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
    
        summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

De verificatie- en autorisatiestroom in de voorbeeldweb-API die we hebben gemaakt, werkt als volgt:

  • De client verzendt een GET-aanvraag naar /weatherforecast met een JWT in de Authorization-header.
  • UseAuthentication valideert het token met Microsoft Entra ID
  • UseAuthorization controleert de rol van Forecast.Read in de claims van het token.
  • Als dit lukt, retourneert het eindpunt de prognose; anders reageert het met 401 Unauthorized (ongeldig/geen token) of 403 Forbidden (ontbrekende rol).

Uw API uitvoeren

Voer uw API uit om ervoor te zorgen dat deze zonder fouten wordt uitgevoerd met behulp van de opdracht dotnet run. Als u van plan bent het HTTPS-protocol zelfs tijdens het testen te gebruiken, moet u het ontwikkelingscertificaat van .NET vertrouwen.

  1. Start de toepassing door het volgende in de terminal te typen:

    dotnet run

  2. Er moet een vergelijkbare uitvoer worden weergegeven in de terminal, die bevestigt dat de toepassing wordt uitgevoerd op http://localhost:{port} en luistert naar aanvragen.

    Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Op de webpagina http://localhost:{host} wordt een uitvoer weergegeven die vergelijkbaar is met de volgende afbeelding. Dit komt doordat de API zonder verificatie wordt aangeroepen. Als u een geautoriseerde aanroep wilt maken, raadpleegt u Volgende stappen voor hulp bij het openen van een beveiligde web-API.

Schermopname met de fout 401 wanneer de webpagina wordt gestart.

Zie het bestand voorbeeldenvoor een volledig voorbeeld van deze API-code.

Volgende stappen

deel 2: Uw beveiligde ASP.NET Core-web-API testen