Condividi tramite

Esercitazione: Creare e proteggere un'API Web ASP.NET Core con Microsoft Identity Platform

  • Articolo

si applica a: cerchio verde con segno di spunta bianco. tenant forza lavoro cerchio verde con segno di spunta bianco. tenant esterni (ulteriori informazioni)

Questa serie di esercitazioni illustra come proteggere un'API Web ASP.NET Core con Microsoft Identity Platform per limitare l'accesso solo agli utenti autorizzati e alle app client. L'API Web compilata usa autorizzazioni delegate (ambiti) e autorizzazioni dell'applicazione (ruoli dell'app).

In questa esercitazione si apprenderà come:

  • Creare un'API Web ASP.NET Core
  • Configurare l'API Web per utilizzare i dettagli di registrazione dell'app di Microsoft Entra
  • Proteggere gli endpoint dell'API Web
  • Eseguire l'API Web per assicurarsi che sia in ascolto delle richieste HTTP

Prerequisiti

Creare un nuovo progetto API Web di ASP.NET Core

Per creare un progetto API Web core ASP.NET minimo, seguire questa procedura:

  1. Aprire il terminale in Visual Studio Code o in qualsiasi altro editor di codice e passare alla directory in cui si vuole creare il progetto.

  2. Eseguire i comandi seguenti nell'interfaccia della riga di comando di .NET o in qualsiasi altro strumento da riga di comando.

    dotnet new webapi -n MyProtectedApi
cd MyProtectedApi

  3. Selezionare Sì quando una finestra di dialogo chiede se si vuole considerare attendibili gli autori.

  4. Selezionare Sì Quando una finestra di dialogo chiede se si desidera aggiungere gli asset necessari al progetto.

Installare i pacchetti necessari

Per proteggere un'API Web ASP.NET Core, è necessario il pacchetto Microsoft.Identity.Web, ovvero un set di librerie di base di ASP.NET che semplificano l'aggiunta del supporto dell'autenticazione e dell'autorizzazione alle app Web e alle API Web che si integrano con Microsoft Identity Platform.

Per installare il pacchetto, usare:

dotnet add package Microsoft.Identity.Web

Configurare i dettagli di registrazione dell'app

Aprire il file appsettings.json nella cartella dell'app e aggiungere i dettagli di registrazione dell'app registrati dopo la registrazione dell'API Web.

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

Sostituire i segnaposto seguenti come illustrato:

  • Sostituire Enter_the_Application_Id_Here con l'ID applicazione (client).
  • Sostituire Enter_the_Tenant_Id_Here con l'ID della directory (tenant).
  • Sostituire Enter_the_Authority_URL_Here con l'URL dell'autorità, come illustrato nella sezione successiva.

URL dell'autorità per l'app

L'URL dell'autorità specifica la directory da cui Microsoft Authentication Library (MSAL) può richiedere token. È costruito in modo diverso sia nella manodopera che negli inquilini esterni, come illustrato di seguito:

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

Usare un dominio URL personalizzato (facoltativo)

I domini URL personalizzati non sono supportati nelle utenze aziendali.

Aggiungere un ruolo e un ambito dell'app

Tutte le API devono pubblicare almeno un ambito, detto anche autorizzazione delegata, affinché le app client ottengano correttamente un token di accesso per un utente. Le API devono anche pubblicare almeno un ruolo dell'applicazione, detto anche autorizzazioni dell'applicazione, affinché le app client ottengano un token di accesso in qualità di sé stesse, ovvero quando non effettuano l'accesso come utente.

Queste autorizzazioni vengono specificate nel file appsettings.json. In questa esercitazione, registrerai sia i permessi delegati che i permessi dell'applicazione con gli scopi "Forecast.Read". Ciò significa che solo gli utenti o le applicazioni client che chiamano l'API con un token di accesso contenente l'ambito "Forecast.Read" ottengono l'autorizzazione per accedere all'endpoint protetto.

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

Implementare l'autenticazione e l'autorizzazione nell'API

Per configurare l'autenticazione e l'autorizzazione, aprire il file program.cs e sostituirne il contenuto nei frammenti di codice seguenti:

Aggiungere uno schema di autenticazione

In questa API viene usato lo schema di connessione JWT (JSON Web Token) come meccanismo di autenticazione predefinito. Usare il metodo AddAuthentication per registrare lo schema bearer JWT.

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

Configurare l'autorizzazione

L'autorizzazione determina le operazioni consentite a un utente autenticato. Definiamo un criterio denominato AuthZPolicy che richiede al client di chiamare l'API per avere il ruolo di Forecast.Read per le app client o l'ambito Forecast.Read per un utente connesso.

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

Il metodo AddPolicy crea un criterio denominato (AuthZPolicy) che verifica la presenza del ruolo Forecast.Read nelle attestazioni del token dell'utente. Se il token non dispone dell'attestazione roles, l'accesso agli endpoint che richiedono questo criterio viene negato.

Compilare la pipeline di richiesta HTTP

In questa esercitazione viene usata un'API minima senza controller perché l'attenzione è maggiore sulla protezione dell'API. Per configurare la pipeline middleware dell'API, aggiungere quanto segue:

  • reindirizzamento HTTPS: applicare la comunicazione sicura reindirizzando le richieste HTTP a HTTPS.
  • middleware di autenticazione: convalida i token in ingresso prima dell'elaborazione delle richieste.
  • middleware di autorizzazione: applica i criteri dopo l'autenticazione, assicurando che solo i client autorizzati possano accedere agli endpoint protetti.
var app = builder.Build();

// Configure the HTTP request pipeline

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

Definire l'endpoint delle previsioni meteo

L'endpoint /weatherforecast genera una previsione casuale di cinque giorni, protetta dai criteri di autorizzazione. RequireAuthorization("AuthZPolicy") garantisce che solo i client con il ruolo Forecast.Read possano accedervi.

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

Il flusso di autenticazione e autorizzazione nell'API Web di esempio creata funziona come segue:

  • Il client invia una richiesta GET a /weatherforecast con un token JWT nell'intestazione Authorization.
  • UseAuthentication convalida il token rispetto all'ID Microsoft Entra
  • UseAuthorization verifica la presenza del ruolo Forecast.Read nelle attestazioni del token.
  • In caso di esito positivo, l'endpoint restituisce la previsione; in caso contrario, risponde con 401 Unauthorized (token non valido/nessun token) o 403 Forbidden (ruolo mancante).

Esegui l'API

Eseguire l'API per assicurarsi che sia in esecuzione senza errori usando il comando dotnet run. Se si intende usare il protocollo HTTPS anche durante i test, è necessario considerare attendibile . Il certificato di sviluppo di NET.

  1. Avviare l'applicazione digitando quanto segue nel terminale:

    dotnet run

  2. Nel terminale dovrebbe essere visualizzato un output simile al seguente, che conferma che l'applicazione è in esecuzione in http://localhost:{port} e in ascolto delle richieste.

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

La pagina Web http://localhost:{host} visualizza un output simile all'immagine seguente. Ciò è dovuto al fatto che l'API viene chiamata senza autenticazione. Per effettuare una chiamata autorizzata, vedere Passaggi successivi per istruzioni su come accedere a un'API Web protetta.

Screenshot che mostra l'errore 401 all'avvio della pagina Web.

Per un esempio completo di questo codice API, vedere il file di esempi di.

Passaggi successivi

Parte 2: Testare l'API Web ASP.NET Core protetta