Guida introduttiva: Proteggere un'API Web ASP.NET Core

Questa guida illustra come proteggere un'API Web con Microsoft Entra ID (in precedenza Azure AD) usando Microsoft. Identity.Web.

Prerequisiti

• .NET 9 SDK
• Un tenant Microsoft Entra ID (creare un account gratuito)
• Registrazione dell'app per l'API

Opzione 1: Crea da un modello (più veloce)

1. Creare il progetto

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

2. Configurare la registrazione dell'app

Aggiorna appsettings.json con i dettagli di registrazione dell'applicazione:

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

3. Eseguire l'API

dotnet run

L'API è ora protetta in https://localhost:5001.

Fatto! Le richieste richiedono ora un token di accesso valido.

Opzione 2: Aggiungere all'API Web esistente

1. Installare il pacchetto NuGet

dotnet add package Microsoft.Identity.Web

2. Configurare l'autenticazione in Program.cs

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. Aggiungere la configurazione a appsettings.json

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

4. Proteggere gli endpoint API

Richiedere l'autenticazione per tutti gli endpoint:

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

Richiedi ambiti specifici:

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. Eseguire e testare

dotnet run

Eseguire test con strumenti come Postman o curl:

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

Successo! L'API convalida ora i token di connessione.

Configurazione della registrazione dell'app

1. Registrare l'API

1. Accedere al portale di Azure
2. Passare a Microsoft Entra ID>Registrazioni app>Nuova registrazione
3. Immettere un nome (ad esempio, "La mia API Web")
4. Selezionare Tenant singolo (più comune per le API)
5. Nessun URI di reindirizzamento necessario per le API
6. Fare clic su Registra

2. Esporre un ambito dell'API

1. Nella registrazione dell'app per le API passare a Esporre un'API
2. Fare clic su Aggiungi un ambito
3. Accettare l'URI id applicazione predefinito o personalizzarlo (ad esempio, api://your-api-client-id)
4. Aggiungere un ambito:
   • Nome ambito:access_as_user
   • Chi può fornire il consenso: Amministratori e utenti
   • Nome visualizzato del consenso amministratore: "Accedi alla mia API Web"
   • Descrizione del consenso amministratore: "Consente all'app di accedere all'API Web per conto dell'utente connesso"
5. Fare clic su Aggiungi ambito

3. Prendere nota dell'ID applicazione

Copiare l'ID applicazione (client) - questo è il tuo ClientId in appsettings.json.

Creare una registrazione dell'app client (per i test)

Per chiamare l'API, è necessaria un'app client:

1. Registrare un'applicazione client

1. In Microsoft Entra ID>Registrazioni app creare un'altra registrazione
2. Denominarlo (ad esempio, "Client API personale")
3. Selezionare i tipi di account
4. Aggiungere l'URI di reindirizzamento: https://localhost:7000/signin-oidc (se si tratta di un'app Web)
5. Fare clic su Registra

2. Concedere autorizzazioni API

1. Nella registrazione dell'app client passare a Autorizzazioni API
2. Fare clic su Aggiungi un'autorizzazione>Api personali
3. Selezionare la registrazione dell'API
4. Controllare l'ambito access_as_user
5. Fare clic su Aggiungi autorizzazioni
6. Fare clic su Concedi consenso amministratore (se necessario)

3. Creare un segreto client (per i client riservati)

1. Vai a Certificati e segreti
2. Clicca su Nuovo segreto del client
3. Aggiungere una descrizione e una scadenza
4. Fare clic su Aggiungi
5. Copiare immediatamente il valore del segreto : non sarà possibile visualizzarlo di nuovo

Testare l'API protetta

Utilizzo di Postman

1. Creare una nuova richiesta in Postman
2. Configurare l'autenticazione OAuth 2.0:
   • Tipo di concessione: Codice di autorizzazione (per il contesto utente) o Credenziali client (per il contesto dell'app)
   • URL di autenticazione:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
   • URL del token di accesso:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
   • ID client: ID cliente della tua app cliente
   • Segreto del client: Segreto dell'applicazione client
   • Ambito:api://your-api-client-id/access_as_user
3. Fare clic su Ottieni nuovo token di accesso
4. Usare il token per chiamare l'API

Uso del codice (esempio C#)

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

Opzioni di configurazione comuni

Richiedere ambiti specifici nella configurazione

Anziché usare l'attributo [RequiredScope] , configurare gli ambiti obbligatori a livello globale:

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

Accettare i token da più tenenti

Per le API multi-tenant:

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

Configurare la convalida dei token

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

Passaggi successivi

Ora che si dispone di un'API protetta, esaminare i passaggi successivi seguenti:

• Call api downstream - Chiamare Microsoft Graph o altre API per conto degli utenti.
• Configurare la cache dei token : strategie della cache di produzione per gli scenari OBO.
• Processi a esecuzione prolungata : gestire processi in background con token OBO.
• Deploy dietro un gateway API - Gestione API di Azure, Frontdoor di Azure, Application Gateway.

Risoluzione dei problemi

401 - Non autorizzato

Problema: L'API restituisce 401 anche con un token.

Possibili cause:

• Il pubblico del token (aud dichiarazione) non corrisponde a quello della tua API ClientId
• Il token è scaduto
• Il token è per il locatario errato
• Ambito obbligatorio mancante

Soluzione: Decodificare il token in jwt.ms e verificare le attestazioni. Per informazioni dettagliate sulla risoluzione dei problemi, vedere Registrazione e diagnostica .

AADSTS50013: firma non valida

Problema: La convalida della firma del token non riesce.

Soluzione: Assicurati che TenantId e ClientId siano corretti. Il token deve essere emesso dall'autorità prevista. Abilitare la registrazione dettagliata per visualizzare gli errori di convalida.

Ambiti non trovati nel token

Problema:[RequiredScope] l'attributo non funziona.

Soluzione:

1. Verificare che l'app client disponga dell'autorizzazione per l'ambito
2. Verificare che il consenso dell'amministratore sia stato concesso (se necessario)
3. Vedere Guida all'autorizzazione per i modelli di convalida completi dell'ambito
4. Verificare che l'ambito sia richiesto durante l'acquisizione del token (ad esempio api://your-api/.default, o ambiti specifici)

Vedere altre informazioni:Guida alla risoluzione dei problemi dell'API Web

Contenuti correlati

• Guida all'autorizzazione - Attributo RequiredScope, criteri di autorizzazione, filtro tenant
• Guida alla personalizzazione - Configurare le opzioni di connessione JWT e i parametri di convalida
• Registrazione e diagnostica - Risolvere i problemi di autenticazione con gli ID di correlazione
• Esercitazione per l'API Web protetta
• Esempi di API