Självstudie: Skapa och skydda ett ASP.NET Core-webb-API med Microsofts identitetsplattform

Gäller för: Användarorganisationer Externa hyresgäster (läs mer)

Den här självstudieserien visar hur du skyddar ett ASP.NET Core-webb-API med Microsofts identitetsplattform för att begränsa åtkomsten till endast auktoriserade användare och klientappar. Webb-API:et som du skapar använder både delegerade behörigheter (omfång) och programbehörigheter (approller).

I den här handledningen kommer du att:

• Skapa ett ASP.NET Core-webb-API
• Konfigurera webb-API:n för att använda sina Microsoft Entra-appregistreringsuppgifter
• Skydda dina webb-API-slutpunkter
• Kör webb-API:et för att säkerställa att det lyssnar på HTTP-begäranden

Förutsättningar

• Om du inte redan har gjort det slutför du stegen i snabbstart: Logga in användare i en exempelwebbapp. I snabbstarten behöver du inte klona och köra kodexemplet.
• .NET 8.0 SDK eller senare.
• Visual Studio Code eller någon annan kodredigerare.

Skapa ett nytt ASP.NET Core-webb-API-projekt

Följ dessa steg för att skapa ett minimalt ASP.NET Core-webb-API-projekt:

1. Öppna terminalen i Visual Studio Code eller någon annan kodredigerare och gå till katalogen där du vill skapa projektet.

2. Kör följande kommandon på .NET CLI eller något annat kommandoradsverktyg.

   dotnet new webapi -n MyProtectedApi
   cd MyProtectedApi
   

3. Välj Ja när en dialogruta frågar om du vill lita på författarna.

4. Välj Ja När en dialogruta frågar om du vill lägga till nödvändiga tillgångar i projektet.

Installera nödvändiga paket

För att skydda ett ASP.NET Core-webb-API behöver du Microsoft.Identity.Web-paketet – en uppsättning ASP.NET Core-bibliotek som förenklar tillägg av stöd för autentisering och auktorisering till webbappar och webb-API:er som integreras med Microsofts identitetsplattform.

Om du vill installera paketet använder du:

dotnet add package Microsoft.Identity.Web

Konfigurera information om appregistrering

Öppna appsettings.json-filen i din appmapp och lägg till den appregistreringsinformation som du registrerade efter registreringen av webb-API:et.

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

Ersätt följande platshållare enligt följande:

• Ersätt Enter_the_Application_Id_Here med ditt program-ID (klient-ID).
• Ersätt Enter_the_Tenant_Id_Here med ditt katalog-ID (klientorganisation).
• Ersätt Enter_the_Authority_URL_Here med din utfärdar-URL, enligt beskrivningen i nästa avsnitt.

Myndighets-URL för din app

Utfärdarens URL anger den katalog som Microsoft Authentication Library (MSAL) kan begära tokens från. Det är strukturerat på olika sätt för både arbetsstyrkan och externa hyresgäster, som visas:

Arbetsstyrka hyresgäst

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

extern hyresgäst

//Authority URL for external tenant
Instance: "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"

Använda anpassad URL-domän (valfritt)

Arbetsstyrka hyresgäst

Anpassade URL-domäner stöds inte i personalklienter.

extern hyresgäst

Använda anpassad URL-domän (valfritt)

Använd en anpassad domän för att helt märka autentiserings-URL:en. Från ett användarperspektiv finns användarna kvar på din domän under autentiseringsprocessen, i stället för att omdirigeras till ciamlogin.com domännamn.

Följ dessa steg för att använda en anpassad domän:

1. Använd stegen i Aktivera anpassade URL-domäner för appar i externa klienter för att aktivera anpassad URL-domän för din externa klientorganisation.

2. Öppna appsettings.json fil:

   1. Uppdatera värdet för egenskapen Instance till https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Ersätt Enter_the_Custom_Domain_Here med din anpassade URL-domän och Enter_the_Tenant_ID_Here med ditt klient-ID. Om du inte har ditt klient-ID lär du dig att läsa klientinformationen.
   2. Lägg till egenskapen knownAuthorities med värdet [Ange_ditt_anpassade_domän_här].

När du har gjort ändringarna i din appsettings.json-fil, om din anpassade URL-domän är login.contoso.comoch klientorganisations-ID:t är aaaabbbb-0000-cccc-1111-dddd222eeee, bör filen se ut ungefär som följande kodfragment:

{
    "AzureAd": {
        "Instance": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
        "KnownAuthorities": ["login.contoso.com"]
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

Lägg till en approll och omfång

Alla API:n måste publicera minst ett omfång, även kallat delegerad behörighet, för att klientapparna ska kunna få en åtkomsttoken för en användare. API:er bör också publicera minst en applikationsroll, även kallad applikationsbehörigheter, för att klientapparna ska kunna hämta en åtkomsttoken i sitt eget namn, det vill säga när de inte loggar in en användare.

Vi anger dessa behörigheter i filen appsettings.json. I den här handledningen registrerar du både delegerad och programbehörigheter med omfånget "Forecast.Read". Det innebär att endast användare eller klientprogram som anropar API:et med en åtkomsttoken som innehåller omfånget "Forecast.Read" får behörighet att komma åt den skyddade slutpunkten.

{
  "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": "*"
}

Implementera autentisering och auktorisering i API:et

Om du vill konfigurera autentisering och auktorisering öppnar du program.cs-filen och ersätter dess innehåll med följande kodfragment:

Lägga till ett autentiseringsschema

I det här API:et använder vi JSON Web Token (JWT) Bearer-schemat som standardautentiseringsmekanism. Använd metoden AddAuthentication för att registrera JWT-ägarschemat.

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

Konfigurera auktorisering

Auktorisering avgör vad en autentiserad användare får göra. Vi definierar en princip med namnet AuthZPolicy som kräver att klienten anropar API:et för att ha Forecast.Read roll för klientappar eller Forecast.Read omfång för en inloggad användare.

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

Metoden AddPolicy skapar en namngiven policy (AuthZPolicy) som kontrollerar om rollen Forecast.Read finns i användarens tokenanspråk. Om token saknar påståendet roles nekas åtkomst till slutpunkter som kräver denna policy.

Skapa pipelinen för HTTP-begäran

I den här självstudien använder vi ett minimalt API utan kontrollanter eftersom fokus ligger mer på att skydda API:et. Vi konfigurerar API-pipelinen för mellanprogram genom att lägga till följande:

• HTTPS-omdirigering: Framtvinga säker kommunikation genom att omdirigera HTTP-begäranden till HTTPS.
• Authentication middleware: Validerar inkommande token innan begäranden bearbetas.
• Authorization middleware: Tillämpar principer efter autentisering, vilket säkerställer att endast auktoriserade klienter kan komma åt skyddade slutpunkter.

var app = builder.Build();

// Configure the HTTP request pipeline

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

Definiera slutpunkten för väderprognosen

Den /weatherforecast slutpunkten genererar en slumpmässig femdagarsprognos som skyddas av auktoriseringsprincipen. RequireAuthorization("AuthZPolicy") ser till att endast klienter med den Forecast.Read rollen kan komma åt den.

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

Autentiserings- och auktoriseringsflödet i exempelwebb-API:et som vi skapade fungerar på följande sätt:

• Klienten skickar en GET-begäran till /weatherforecast med en JWT i Authorization-huvudet.
• UseAuthentication verifierar ett token mot Microsoft Entra ID
• UseAuthorization söker efter Forecast.Read roll i tokens anspråk.
• Om det lyckas returnerar slutpunkten prognosen. Annars svarar den med 401 Unauthorized (ogiltig/ingen token) eller 403 Forbidden (roll saknas).

Kör ditt API

Kör api:et för att säkerställa att det körs utan fel med hjälp av kommandot dotnet run. Om du tänker använda HTTPS-protokollet även under testningen måste du lita på .NET:s utvecklingscertifikat.

1. Starta programmet genom att skriva följande i terminalen:

   dotnet run
   

2. Ett liknande utdata som följande bör visas i terminalen, vilket bekräftar att programmet körs på http://localhost:{port} och lyssnar efter begäranden.

   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.
   ...
   

Webbsidan http://localhost:{host} visar utdata som liknar följande bild. Det beror på att API:et anropas utan autentisering. Om du vill göra ett auktoriserat anrop kan du läsa Nästa steg för vägledning om hur du får åtkomst till ett skyddat webb-API.

Ett fullständigt exempel på den här API-koden finns i -exempelfilen.

Nästa steg

del 2: Testa din skyddade ASP.NET Core-webb-API