Avvio rapido: Proteggere un'API Web ASP.NET Core con Microsoft Identity Platform

La guida introduttiva seguente usa un esempio di codice dell'API Web core di ASP.NET per illustrare come limitare l'accesso alle risorse agli account autorizzati. L'esempio supporta l'autorizzazione di account Microsoft personali e di account presenti in qualsiasi organizzazione Microsoft Entra.

Prerequisiti

• Account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Microsoft Entra tenant
• Requisito minimo di .NET 6.0 SDK
• Visual Studio 2022 o Visual Studio Code

Passaggio 1: Registrare l'applicazione

Registrare prima di tutto l'API Web nel tenant di Microsoft Entra e aggiungere un ambito seguendo questa procedura:

1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.
2. Passare a Identità>Applicazioni>Registrazioni app.
3. Seleziona Nuova registrazione.
4. In Nome immettere un nome per l'applicazione. Ad esempio, immettere AspNetCoreWebApi-Quickstart. Gli utenti dell'app vedranno questo nome, che potrà essere modificato in un secondo momento.
5. Selezionare Registra.
6. In Gestisci selezionare Esporre un'API>Aggiungi un ambito. Per URI ID applicazione accettare l'impostazione predefinita selezionando Salva e continua, quindi immettere i dettagli seguenti:

• Nome ambito: access_as_user
• Chi può fornire il consenso: Amministratori e utenti
• Nome visualizzato per il consenso amministratore: Access AspNetCoreWebApi-Quickstart
• Descrizione del consenso amministratore: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
• Nome visualizzato per il consenso utente: Access AspNetCoreWebApi-Quickstart
• Descrizione del consenso utente: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
• Stato: Abilitato

1. Selezionare Aggiungi ambito per completare l'aggiunta dell'ambito.

Passaggio 2: Scaricare il progetto ASP.NET Core

Scaricare la soluzione ASP.NET Core da GitHub.

L'esempio di codice è attualmente destinato ASP.NET Core 3.1. L'esempio può essere aggiornato per usare .NET Core 6.0 ed è illustrato nei passaggi seguenti: Aggiornare il codice di esempio a ASP.NET Core 6.0. Questa guida introduttiva verrà deprecata nel prossimo futuro e verrà aggiornata per usare .NET 6.0.

Passaggio 3: Configurare il progetto ASP.NET Core

In questo passaggio, il codice di esempio verrà configurato per funzionare con la registrazione dell'app creata in precedenza.

1. Estrarre il file ZIP in una cartella locale vicina alla radice del disco per evitare eventuali errori causati dalle limitazioni della lunghezza del percorso in Windows. Ad esempio, eseguire l'estrazione in C:\Azure-Samples.

2. Aprire la soluzione nella cartella webapi nell'editor del codice.

3. In appsettings.json sostituire i valori di ClientIde TenantId.

   "ClientId": "Enter_the_Application_Id_here",
   "TenantId": "Enter_the_Tenant_Info_Here"
   

   • Enter_the_Application_Id_Here è l'ID applicazione (client) per l'applicazione registrata.
   • Sostituire Enter_the_Tenant_Info_Here con uno dei seguenti elementi:
     • Se l'applicazione supporta solo Account in questa directory organizzativa, sostituire questo valore con l'ID della directory (un GUID) o il nome del tenant (ad esempio). contoso.onmicrosoft.com L'ID directory (tenant) è reperibile nella pagina Panoramica dell'app.
     • Se l'applicazione supporta Accounts in qualsiasi directory organizzativa, sostituire questo valore con organizations.
     • Se l'applicazione supporta tutti gli utenti dell'account Microsoft, lasciare questo valore come common.

Per questa guida di avvio rapido, non modificare altri valori nel file appsettings.json.

Passaggio 4: Aggiornare il codice di esempio in ASP.NET Core 6.0

Per aggiornare questo esempio di codice alla destinazione ASP.NET Core 6.0, seguire questa procedura:

1. Aprire webapi.csproj
2. Rimuovere la riga seguente:

<TargetFramework>netcoreapp3.1</TargetFramework>

1. Aggiungere la riga seguente al suo posto:

<TargetFramework>netcoreapp6.0</TargetFramework>

Questo passaggio garantisce che l'esempio sia destinato al framework .NET Core 6.0.

Passaggio 5: Eseguire l'esempio

1. Aprire un terminale e passare alla cartella del progetto.

   cd webapi
   

2. Eseguire il comando seguente per compilare la soluzione:

dotnet run

Se la compilazione ha avuto esito positivo, viene visualizzato l'output seguente:

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

Funzionamento dell'esempio

Classe di avvio

Il middleware Microsoft.AspNetCore.Authentication usa una classe Startup che viene eseguita quando viene avviato il processo di hosting. Nel metodo ConfigureServices viene chiamato il metodo di estensione AddMicrosoftIdentityWebApi fornito da Microsoft.Identity.Web.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

Il metodo AddAuthentication() configura il servizio per l'aggiunta dell'autenticazione basata su JwtBearer.

La riga che contiene .AddMicrosoftIdentityWebApi aggiunge l'autorizzazione di Microsoft Identity Platform all'API Web. Viene quindi configurato per convalidare i token di accesso rilasciati da Microsoft Identity Platform, in base alle informazioni contenute nella sezione AzureAD del file di configurazione appsettings.json:

Il metodo Configure() contiene due metodi importanti, app.UseAuthentication() e app.UseAuthorization(), che abilitano la funzionalità denominata:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Proteggere un controller, un metodo del controller o una pagina Razor

I metodi controller o controller possono essere protetti tramite l'attributo [Authorize] . Questo attributo limita l'accesso al controller o ai metodi ai soli utenti autenticati. Se l'utente non è già autenticato, è possibile avviare una richiesta di autenticazione per accedere al controller.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Convalida dell'ambito nel controller

Il codice nell'API verifica quindi che gli ambiti necessari siano presenti nel token usando HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Assistenza e supporto

Se è necessaria assistenza, si vuole segnalare un problema o si vogliono ottenere informazioni sulle opzioni di supporto, vedere Assistenza e supporto per gli sviluppatori.

Passaggi successivi

Il repository GitHub seguente contiene le istruzioni di esempio di codice dell'API Web di ASP.NET Core e altri esempi che illustrano come ottenere quanto segue:

• Aggiungere l'autenticazione a una nuova API Web ASP.NET Core.
• Chiamare l'API Web da un'applicazione desktop.
• Chiamare API downstream come Microsoft Graph e altre API Microsoft.