Guida introduttiva: Proteggere un'API Web di ASP.NET Core con Microsoft Identity Platform
Benvenuto/a. Questa probabilmente non è la pagina che ti aspettavi. Mentre si lavora su una correzione, questo collegamento dovrebbe portare all'articolo corretto:
Guida introduttiva: Chiamare un'API Web ASP.NET Core protetta da Microsoft Identity Platform
Ci scusiamo per l'inconveniente e apprezziamo la vostra pazienza mentre lavoriamo per risolvere questo problema.
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 e account Microsoft personali in qualsiasi organizzazione Microsoft Entra.
Prerequisiti
- Account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
- Tenant di Microsoft Entra
- Requisito minimo di .NET 6.0 SDK
- Visual Studio 2022 o Visual Studio Code
Passaggio 1: Registrare l'applicazione
Prima di tutto, registrare l'API Web nel tenant di Microsoft Entra e aggiungere un ambito seguendo questa procedura:
- Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione Amministrazione istrator.
- Passare a Applicazioni> di identità>Registrazioni app.
- Seleziona Nuova registrazione.
- In Nome immettere un nome per l'applicazione. Ad esempio, immettere AspNetCoreWebApi-Quickstart. Gli utenti dell'app vedranno questo nome e possono essere modificati in un secondo momento.
- Selezionare Registra.
- 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?: Amministrazione 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
- 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.
Nota
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.
Estrarre il file .zip in una cartella locale vicina alla radice del disco per evitare errori causati dalle limitazioni della lunghezza del percorso in Windows. Ad esempio, estrarre in C:\Azure-Samples.
Aprire la soluzione nella cartella webapi nell'editor del codice.
In appsettings.json sostituire i valori di
ClientId
eTenantId
."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:- 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
.
- 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).
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:
- Aprire webapi.csproj
- Rimuovere la riga seguente:
<TargetFramework>netcoreapp3.1</TargetFramework>
- 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
Aprire un terminale e passare alla cartella del progetto.
cd webapi
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 Startup
classe eseguita all'avvio del 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 AzureAD
sezione del file di configurazione appsettings.json:
Chiave appsettings.json | Descrizione |
---|---|
ClientId |
ID applicazione (client) dell'applicazione registrata. |
Instance |
Endpoint del servizio token di sicurezza (STS) per l'autenticazione dell'utente. Questo valore è in genere https://login.microsoftonline.com/ , che indica il cloud pubblico di Azure. |
TenantId |
Nome del tenant o del relativo ID tenant (GUID) o common per accedere agli utenti con account aziendali o dell'istituto di istruzione o account personali Microsoft. |
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
}
Protezione di un controller, del metodo di un controller o di 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 consentendo solo gli utenti autenticati. È possibile avviare una richiesta di autenticazione per accedere al controller se l'utente non è autenticato.
namespace webapi.Controllers
{
[Authorize]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
Convalida dell'ambito nel controller
Il codice nell'API verifica che gli ambiti obbligatori si trovino 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 di ASP.NET Core.
- Chiamare l'API Web da un'applicazione desktop.
- Chiamare API downstream come Microsoft Graph e altre API Microsoft.
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per