Proteggere un ASP.NET Core Blazor Web App con Microsoft Entra ID

Articolo
2025-05-08

Questo articolo descrive come proteggere un Blazor Web App con Microsoft identity platform/Microsoft pacchetti Web Identity per Microsoft Entra ID usando un'app di esempio.

Questa versione dell'articolo illustra l'implementazione di Entra senza adottare il modello Back-end per front-end (BFF). Il modello BFF è utile per effettuare richieste autenticate a servizi esterni. Modificare il selettore della versione dell'articolo in modello BFF se la specifica dell'app richiede l'adozione del modello BFF.

La specifica seguente è coperta:

Blazor Web App usa la modalità di rendering automatico con interattività globale (InteractiveAuto).
Il progetto server chiama AddAuthenticationStateSerialization per aggiungere un provider di stato di autenticazione lato server che usa PersistentComponentState per trasferire lo stato di autenticazione al client. Il client chiama AddAuthenticationStateDeserialization per deserializzare e usare lo stato di autenticazione passato dal server. Lo stato di autenticazione è fisso per la durata dell'applicazione WebAssembly.
L'app utilizza Microsoft Entra ID, basato su package Web di Identity.
L'aggiornamento automatico dei token non interattivi viene gestito dal framework.
L'app usa astrazioni del servizio lato server e lato client per visualizzare i dati meteo generati:
- Quando si esegue il rendering del componente Weather sul server per visualizzare i dati meteo, il componente utilizza il ServerWeatherForecaster server per ottenere i dati meteo.
- Quando il componente Weather viene renderizzato sul client, utilizza l'implementazione del servizio ClientWeatherForecaster, che utilizza un HttpClient preconfigurato (nel file Program del progetto client) per effettuare una chiamata API Web all'API minima del progetto server (/weather-forecast) per ottenere i dati meteo. L'endpoint API minimo ottiene i dati meteo dalla ServerWeatherForecaster classe e lo restituisce al client per il rendering dal componente.

Soluzione di esempio

La soluzione di esempio è costituita dai progetti seguenti:

BlazorWebAppEntra: progetto lato server di Blazor Web App, contenente un esempio endpoint API minimo per i dati meteo.
BlazorWebAppEntra.Client: Progetto client-side di Blazor Web App.
MinimalApiJwt: API Web back-end contenente un esempio di endpoint API minimo per i dati meteo.

Accedere all'esempio tramite la cartella versione più recente nel Blazor repository degli esempi con il collegamento seguente. L'esempio si trova nella BlazorWebAppEntra cartella per .NET 9 o versione successiva.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Registrazioni dell'app Microsoft Entra ID

È consigliabile usare registrazioni separate per app e API Web, anche quando le app e le API Web si trovano nella stessa soluzione. Le indicazioni seguenti sono relative all'app BlazorWebAppEntra e MinimalApiJwt all'API Web della soluzione di esempio, ma le stesse linee guida si applicano in genere a tutte le registrazioni basate su Entra per le app e le API Web.

Registrare prima l'API Web (MinimalApiJwt) in modo da poter quindi concedere l'accesso all'API Web durante la registrazione dell'app. L'ID tenant e l'ID client dell'API Web vengono usati per configurare l'API Web nel file Program . Dopo aver registrato l'API Web, esporre l'API Web in Registrazioni delle app>Esporre un'API con un nome di ambito di Weather.Get. Registrare l'URI ID app da usare nella configurazione dell'app.

Registrare quindi l'app (BlazorWebAppEntra) con una configurazione della piattaforma Web e un URI di reindirizzamento di https://localhost/signin-oidc (una porta non è necessaria). L'ID tenant, il dominio tenant e l'ID client dell'app, insieme all'indirizzo di base dell'API Web, all'URI ID app e al nome dell'ambito meteo, vengono usati per configurare l'app nel file appsettings.json . Concedere l'autorizzazione all'API per accedere all'API web in Registrazioni app>Autorizzazioni API. Se la specifica di sicurezza dell'app lo richiede, è possibile concedere all'organizzazione il consenso amministratore per accedere all'API Web. Gli utenti e i gruppi autorizzati vengono assegnati alla registrazione dell'app in Registrazioni app>Applicazioni aziendali.

Nella configurazione della registrazione dell'applicazione per la Concessione implicita e i flussi ibridi del portale Entra o Azure, non selezionare nessuna delle opzioni per far sì che l'endpoint di autorizzazione restituisca token di accesso o token ID. Il gestore OpenID Connect richiede automaticamente i token appropriati usando il codice restituito dall'endpoint di autorizzazione.

Creare un segreto client nella registrazione dell'app nel portale entra o di Azure (Gestisci>certificati e segreti>Nuovo segreto client). Conserva il valore del segreto del client per utilizzarlo nella sezione successiva.

Altre indicazioni sulla configurazione di Entra per impostazioni specifiche sono disponibili più avanti in questo articolo.

Progetto server Blazor Web App lato (`BlazorWebAppEntra`)

Il progetto BlazorWebAppEntra è il progetto lato server di Blazor Web App.

Progetto lato utente Blazor Web App (`BlazorWebAppEntra.Client`)

Il progetto BlazorWebAppEntra.Client rappresenta la parte lato client di Blazor Web App.

Se l'utente deve accedere o disconnettersi durante il rendering lato client, viene avviato un ricaricamento di pagina completo.

Progetto API Web per il back-end (`MinimalApiJwt`)

Il MinimalApiJwt progetto è un'API Web back-end per più progetti front-end. Il progetto configura un endpoint API minimo per i dati meteo.

Il MinimalApiJwt.http file può essere usato per testare la richiesta di dati meteo. Si tenga presente che il progetto MinimalApiJwt deve essere in esecuzione per testare l'endpoint, e l'endpoint è incorporato nel codice del file. Per altre informazioni, vedere Usare file .http in Visual Studio 2022.

Il progetto include pacchetti e configurazione per produrre documenti OpenAPI e l'interfaccia utente di Swagger nell'ambiente di sviluppo. Per altre informazioni, vedere Usare i documenti OpenAPI generati.

Un endpoint sicuro dei dati di previsione meteo si trova nel file del Program progetto.

app.MapGet("/weather-forecast", () =>
{
    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;
}).RequireAuthorization();

Il RequireAuthorization metodo di estensione richiede l'autorizzazione per la definizione di route. Per tutti i controller aggiunti al progetto, aggiungere l'attributo [Authorize] al controller o all'azione.

Configurare il progetto API Web backend (`MinimalApiJwt`)

Configurare il progetto nella classe JwtBearerOptions della AddJwtBearer chiamata nel MinimalApiJwt file del Program progetto.

Per la registrazione dell'app per le API Web, l'ambito Weather.Get viene configurato nel portale entra o di Azure in Esporre un'API.

Authority imposta l'Autorità per effettuare chiamate OIDC.

jwtOptions.Authority = "{AUTHORITY}";

Gli esempi seguenti usano un ID tenant di aaaabbbb-0000-cccc-1111-dddd2222eeee.

Se l'app è registrata in un tenant ME-ID, l'autorità deve corrispondere all'issuer (iss) del token JWT restituito dal provider di identità.

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";

Se l'app è registrata in un tenant AAD B2C:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";

Audience imposta il gruppo di destinatari per qualsiasi token di accesso JWT ricevuto.

jwtOptions.Audience = "{AUDIENCE}";

Trova solo il valore corrispondente al percorso dell'URI ID applicazione configurato quando aggiungi l'ambito sotto Weather.Get nel portale Entra o Azure. Non includere il nome dell'ambito "Weather.Get" nel valore.

Negli esempi seguenti viene usato un ID applicazione (client) di 11112222-bbbb-3333-cccc-4444dddd5555. Il secondo esempio usa un dominio tenant di contoso.onmicrosoft.com.

esempio di tenant ME-ID:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Esempio di tenant per AAD B2C:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Configurare il progetto server (`BlazorWebAppEntra`)

AddMicrosoftIdentityWebApp da Microsoft Identity Web (Microsoft.Identity.Web pacchetto NuGet, documentazione dell'API) è configurato nel BlazorWebAppEntra file del Program progetto.

Accedere all'ID applicazione (client), al dominio tenant (publisher) e all'ID directory (tenant) dalla registrazione dell'app nel portale Entra o di Azure. L'URI ID app viene ottenuto per l'ambito Weather.Get dalla registrazione dell'API Web. Non includere il nome dell'ambito quando si preleva l'URI ID app dal portale.

Nel file Program del progetto BlazorWebAppEntra, specificare i valori per i seguenti segnaposto nella configurazione Web di MicrosoftIdentity.

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.Domain = "{DIRECTORY NAME}.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "{TENANT ID}";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = [ "{APP ID URI}/Weather.Get" ];
    })
    .AddInMemoryTokenCaches();

Segnaposto nella configurazione precedente:

{CLIENT ID (BLAZOR APP)}: ID dell'applicazione (client).
{DIRECTORY NAME}: nome della directory del dominio tenant (server di pubblicazione).
{TENANT ID}: ID del tenant della directory.
{BASE ADDRESS}: indirizzo di base dell'API Web.
{APP ID URI}: URI dell'ID app per gli ambiti dell'API web. Viene usato uno dei formati seguenti, dove il segnaposto {CLIENT ID (WEB API)} è il Client Id della registrazione Entra dell'API Web e il segnaposto {DIRECTORY NAME} è il nome della directory del dominio del tenant (ad esempio: contoso).
- ME-ID formato del tenant: api://{CLIENT ID (WEB API)}
- Formato tenant B2C: https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Esempio:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.Domain = "contoso.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = [ "api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get" ];
    })
    .AddInMemoryTokenCaches();

Questa versione dell'articolo illustra l'implementazione di Entra con il modello Back-end per front-end (BFF). Modificare il selettore della versione dell'articolo impostandolo su Modello non BFF se la specifica dell'app non richiede l'adozione del modello BFF.

La specifica seguente è coperta:

Blazor Web App usa la modalità di rendering automatico con interattività globale (InteractiveAuto).
Il progetto server chiama AddAuthenticationStateSerialization per aggiungere un provider di stato di autenticazione lato server che usa PersistentComponentState per trasferire lo stato di autenticazione al client. Il client chiama AddAuthenticationStateDeserialization per deserializzare e usare lo stato di autenticazione passato dal server. Lo stato di autenticazione è fisso per la durata dell'applicazione WebAssembly.
L'app utilizza Microsoft Entra ID, basato su package Web di Identity.
L'aggiornamento automatico dei token non interattivi viene gestito dal framework.
L'app usa astrazioni sul lato server e sul lato client per visualizzare i dati meteo generati.
Il modello Back-End per Front-End (BFF) viene adottato utilizzando .NET Aspire per la scoperta del servizio e YARP per il proxy delle richieste verso un endpoint di previsione meteo nell'app Back-End.
- Un'API Web di back-end utilizza l'autenticazione JWT-bearer per convalidare i token JWT salvati dal sistema durante il processo di accesso.
- Aspire migliora l'esperienza di creazione di app cloud-native .NET. Fornisce un set di strumenti e modelli coerente e con opinioni per la creazione e l'esecuzione di app distribuite.
- YARP (Yet Another Reverse Proxy) è una libreria usata per creare un server proxy inverso.

Per ulteriori informazioni su .NET Aspire, vedere Disponibilità generale di .NET Aspire: Semplificazione dello sviluppo nativo del cloud .NET (maggio 2024).

Prerequisiti

.NET Aspire richiede Visual Studio versione 17.10 o successiva.

Vedere anche la sezione Prerequisiti di Avvio rapido: Creare la prima .NET Aspire app.

Soluzione di esempio

La soluzione di esempio è costituita dai progetti seguenti:

.NET Aspire:
- Aspire.AppHost: usato per gestire le problematiche di orchestrazione generali dell'app.
- Aspire.ServiceDefaults: contiene configurazioni di app predefinite .NET Aspire che possono essere estese e personalizzate in base alle esigenze.
MinimalApiJwt: API Web back-end contenente un esempio di endpoint API minimo per i dati meteo.
BlazorWebAppEntra: progetto lato server di Blazor Web App.
BlazorWebAppEntra.Client: Progetto client-side di Blazor Web App.

Accedere all'esempio tramite la cartella versione più recente nel Blazor repository degli esempi con il collegamento seguente. L'esempio si trova nella BlazorWebAppEntraBff cartella per .NET 9 o versione successiva.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Registrazioni dell'app Microsoft Entra ID

Altre indicazioni sulla configurazione di Entra per impostazioni specifiche sono disponibili più avanti in questo articolo.

.NET Aspire progetti

Per ulteriori informazioni sull'utilizzo di .NET Aspire e sui dettagli relativi ai progetti .AppHost e .ServiceDefaults dell'app di esempio, consultare la documentazione di .NET Aspire.

Verificare di aver soddisfatto i prerequisiti per .NET Aspire. Per altre informazioni, vedere la sezione Prerequisiti di Avvio rapido: Creare la prima .NET Aspire app.

L'app di esempio configura solo un profilo di avvio HTTP non sicuro (http) da usare durante i test di sviluppo. Per ulteriori informazioni, incluso un esempio di profili di impostazioni di avvio sicure e non sicure, vedere Consenti il trasporto non sicuro in .NET Aspire (.NET Aspire documentazione).

Progetto server Blazor Web App lato (`BlazorWebAppEntra`)

Il progetto BlazorWebAppEntra è il progetto lato server di Blazor Web App.

Progetto lato utente Blazor Web App (`BlazorWebAppEntra.Client`)

Il progetto BlazorWebAppEntra.Client rappresenta la parte lato client di Blazor Web App.

Se l'utente deve accedere o disconnettersi durante il rendering lato client, viene avviato un ricaricamento di pagina completo.

Progetto API Web per il back-end (`MinimalApiJwt`)

Il MinimalApiJwt progetto è un'API Web back-end per più progetti front-end. Il progetto configura un endpoint API minimo per i dati meteo. Le richieste dal Blazor Web App progetto lato server (BlazorWebAppEntra) vengono inviate tramite proxy al MinimalApiJwt progetto.

Un endpoint sicuro dei dati di previsione meteo si trova nel file del Program progetto.

app.MapGet("/weather-forecast", () =>
{
    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;
}).RequireAuthorization();

Configurare il progetto API Web backend (`MinimalApiJwt`)

Configurare il MinimalApiJwt progetto nella classe JwtBearerOptions della AddJwtBearer chiamata nel file del Program progetto.

Per la registrazione dell'app per le API Web, l'ambito Weather.Get viene configurato nel portale entra o di Azure in Esporre un'API.

Authority imposta l'Autorità per effettuare chiamate OIDC.

jwtOptions.Authority = "{AUTHORITY}";

Gli esempi seguenti usano un ID tenant di aaaabbbb-0000-cccc-1111-dddd2222eeee.

Se l'app è registrata in un tenant ME-ID, l'autorità deve corrispondere all'issuer (iss) del token JWT restituito dal provider di identità.

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";

Se l'app è registrata in un tenant AAD B2C:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";

Audience imposta il gruppo di destinatari per qualsiasi token di accesso JWT ricevuto.

jwtOptions.Audience = "{AUDIENCE}";

Negli esempi seguenti viene usato un ID applicazione (client) di 11112222-bbbb-3333-cccc-4444dddd5555. Il secondo esempio usa un dominio tenant di contoso.onmicrosoft.com.

esempio di tenant ME-ID:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Esempio di tenant per AAD B2C:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Configurare il progetto server (`BlazorWebAppEntra`)

AddMicrosoftIdentityWebApp da Microsoft Identity Web (Microsoft.Identity.Web pacchetto NuGet, documentazione dell'API) è configurato nel BlazorWebAppEntra file del Program progetto.

BlazorWebAppEntra Nel file del Program progetto specificare i valori per i segnaposto seguenti nella configurazione Web MicrosoftIdentity:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.Domain = "{DIRECTORY NAME}.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "{TENANT ID}";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = [ "{APP ID URI}/Weather.Get" ];
    })
    .AddInMemoryTokenCaches();

Segnaposto della configurazione precedente:

{CLIENT ID (BLAZOR APP)}: ID dell'applicazione (client).
{DIRECTORY NAME}: nome della directory del dominio tenant (server di pubblicazione).
{TENANT ID}: ID del tenant della directory.
{BASE ADDRESS}: indirizzo di base dell'API Web.
{APP ID URI}: URI dell'ID app per gli ambiti dell'API web. Viene utilizzato uno dei seguenti formati, dove il {CLIENT ID (WEB API)} segnaposto è l'ID client della registrazione Entra dell'API Web e il {DIRECTORY NAME} segnaposto è il nome della directory del dominio tenant (gestori) (ad esempio: contoso).
- ME-ID formato tenant: api://{CLIENT ID (WEB API)}
- Formato tenant B2C: https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Esempio:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.Domain = "contoso.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = [ "api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get" ];
    })
    .AddInMemoryTokenCaches();

Il percorso di callback (CallbackPath) deve corrispondere all'URI di reindirizzamento (percorso di callback di accesso) configurato durante la registrazione dell'applicazione in Entra o portale di Azure. I percorsi vengono configurati nel pannello Autenticazione della registrazione dell'app. Il valore predefinito di CallbackPath è /signin-oidc per un URI di reindirizzamento registrato di https://localhost/signin-oidc (non è necessaria una porta).

SignedOutCallbackPath è il percorso della richiesta all'interno del percorso di base dell'app intercettato dal gestore OpenID Connect in cui l'agente utente viene restituito per la prima volta dopo la disconnessione da Entra. L'app di esempio non imposta un valore per il percorso perché viene usato il valore predefinito "/signout-callback-oidc". Dopo aver intercettato la richiesta, il gestore OpenID Connect reindirizza al SignedOutRedirectUri o RedirectUri, se specificato.

Configurare il percorso di callback per la disconnessione nella registrazione di Entra dell'app. Nel portale Entra o Azure, imposta il percorso nelle voci di configurazione della piattaforma Web: URI di reindirizzamento

https://localhost/signout-callback-oidc

Nota

Una porta non è necessaria per gli indirizzi localhost quando si usa Entra.

Se non si aggiunge l'URI del percorso di callback per la disconnessione alla registrazione dell'app in Entra, Entra si rifiuta di reindirizzare l'utente all'app e chiede semplicemente di chiudere la finestra del browser.

Nota

Entra non reindirizza un utente amministratore principale (account root) o un utente esterno all'applicazione Blazor. Entra invece registra l'utente dall'app e consiglia di chiudere tutte le finestre del browser. Per altre informazioni, vedere postLogoutRedirectUri non funzionante quando l'URL dell'autorità contiene un ID tenant (AzureAD/microsoft-authentication-library-for-js #5783).

Avviso

Non archiviare segreti dell'app, stringa di connessione, credenziali, password, numeri di identificazione personale (PIN), codice C#/.NET privato o chiavi/token privati nel codice lato client, che è sempre non sicuro. Negli ambienti di test/gestione temporanea e produzione, il codice lato Blazor server e le API Web devono usare flussi di autenticazione sicuri che evitano di mantenere le credenziali all'interno del codice del progetto o dei file di configurazione. Al di fuori dei test di sviluppo locali, è consigliabile evitare l'uso di variabili di ambiente per archiviare i dati sensibili, perché le variabili di ambiente non sono l'approccio più sicuro. Per i test di sviluppo locali, lo strumento Secret Manager è consigliato per proteggere i dati sensibili. Per altre informazioni, vedere Gestire in modo sicuro dati e credenziali sensibili.

Stabilire il segreto del client

Questa sezione si applica solo al progetto server dell'oggetto Blazor Web App.

Usare uno o entrambi gli approcci seguenti per fornire il segreto client all'app:

Strumento Secret Manager: lo strumento Secret Manager archivia i dati privati nel computer locale e viene usato solo durante lo sviluppo locale.
Azure Key Vault: è possibile archiviare il segreto del client in un Key Vault da usare in qualsiasi ambiente, incluso l'ambiente di sviluppo quando si lavora in locale. Alcuni sviluppatori preferiscono utilizzare gli archivi chiave per le distribuzioni di staging e di produzione e lo strumento Secret Manager per lo sviluppo locale.

È consigliabile evitare di archiviare segreti client nel codice del progetto o nei file di configurazione. Usare flussi di autenticazione sicuri, ad esempio uno o entrambi gli approcci descritti in questa sezione.

Strumento Gestore Segreti

Lo strumento Secret Manager può archiviare il segreto del client dell'app server sotto la chiave di configurazione .

L'app Blazor server non è stata inizializzata per lo strumento Secret Manager. Usare una shell dei comandi, ad esempio la shell dei comandi di Developer PowerShell in Visual Studio, per eseguire il comando seguente. Prima di eseguire il comando, utilizzare il comando cd per spostarsi alla directory del progetto server. Il comando stabilisce un identificatore di segreti utente (<UserSecretsId>) nel file di progetto dell'app server, che viene usato internamente dagli strumenti per tenere traccia dei segreti per l'app:

dotnet user-secrets init

Eseguire il comando seguente per impostare il segreto client. Il {SECRET} segnaposto è il segreto client ottenuto dalla registrazione Entra dell'app:

dotnet user-secrets set "AzureAd:ClientSecret" "{SECRET}"

Se si usa Visual Studio, è possibile verificare che il segreto sia impostato facendo clic con il pulsante destro del mouse sul progetto server in Esplora soluzioni e scegliendo Gestisci segreti utente.

Azure Key Vault (Archivio chiavi di Azure)

Azure Key Vault offre un approccio sicuro per fornire il segreto client dell'app all'app.

Per creare un Key Vault e impostare un segreto client, consulta Informazioni sui segreti di Azure Key Vault (documentazione di Azure), che collega le risorse per iniziare a usare Azure Key Vault. Per implementare il codice in questa sezione, registrare l'URI del Key Vault di Azure e il nome del segreto da Azure quando si crea il Key Vault e il segreto. Quando si impostano i criteri di accesso per il segreto nel pannello Criteri di accesso:

È necessaria solo l'autorizzazione per ottenere il segreto.
Selezionare l'applicazione come Principale per il segreto.

Importante

Viene creato un segreto del vault delle chiavi con una data di scadenza. Assicurarsi di monitorare quando un segreto del key vault sta per scadere e creare un nuovo segreto per l'app prima che quella data venga superata.

Aggiungere la classe AzureHelper seguente al progetto server. Il metodo GetKeyVaultSecret recupera un segreto da un vault delle chiavi. Modificare lo spazio dei nomi (BlazorSample.Helpers) in modo che corrisponda allo schema dello spazio dei nomi del progetto.

Helpers/AzureHelper.cs:

using Azure;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

namespace BlazorWebAppEntra.Helpers;

public static class AzureHelper
{
    public static string GetKeyVaultSecret(string tenantId, string vaultUri, string secretName)
    {
        DefaultAzureCredentialOptions options = new()
        {
            // Specify the tenant ID to use the dev credentials when running the app locally
            // in Visual Studio.
            VisualStudioTenantId = tenantId,
            SharedTokenCacheTenantId = tenantId
        };

        var client = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential(options));
        var secret = client.GetSecretAsync(secretName).Result;

        return secret.Value.Value;
    }
}

Dove i servizi vengono registrati nel file del progetto server Program, acquisisci e applica il client secret usando il codice seguente:

var tenantId = builder.Configuration.GetValue<string>("AzureAd:TenantId")!;
var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
var secretName = builder.Configuration.GetValue<string>("AzureAd:SecretName")!;

builder.Services.Configure<MicrosoftIdentityOptions>(
    OpenIdConnectDefaults.AuthenticationScheme,
    options =>
    {
        options.ClientSecret = 
            AzureHelper.GetKeyVaultSecret(tenantId, vaultUri, secretName);
    });

Se si vuole controllare l'ambiente in cui opera il codice precedente, ad esempio per evitare di eseguire il codice in locale perché si è scelto di usare lo strumento Secret Manager per lo sviluppo locale, è possibile eseguire il wrapping del codice precedente in un'istruzione condizionale che controlla l'ambiente:

if (!context.HostingEnvironment.IsDevelopment())
{
    ...
}

Nella sezione di AzureAdappsettings.json, aggiungere le seguenti chiavi e i valori di configurazione VaultUriSecretName.

"VaultUri": "{VAULT URI}",
"SecretName": "{SECRET NAME}"

Nell'esempio precedente:

Il {VAULT URI} segnaposto è l'URI del key vault. Includere la barra finale sull'URL.
Il segnaposto {SECRET NAME} è il nome segreto.

Esempio:

"VaultUri": "https://contoso.vault.azure.net/",
"SecretName": "BlazorWebAppEntra"

La configurazione viene utilizzata per facilitare la fornitura di archivi di chiavi dedicati e nomi segreti basati sui file di configurazione dell'ambiente dell'app. Ad esempio, è possibile specificare valori di configurazione diversi per appsettings.Development.json in fase di sviluppo, appsettings.Staging.json durante la gestione temporanea e appsettings.Production.json per la distribuzione di produzione. Per altre informazioni, vedere configurazione di ASP.NET CoreBlazor.

Serializzare solo il nome e le attestazioni del ruolo

Program Nel file tutte le attestazioni vengono serializzate impostando SerializeAllClaims su true. Se si desidera solo il nome e le attestazioni del ruolo serializzate per CSR, rimuovere l'opzione o impostarla su false.

Fornire la configurazione con il provider di configurazione JSON (impostazioni dell'app)

I progetti di soluzione di esempio configurano l'autenticazione di connessione Microsoft Web e JWT nei loro file Program per rendere individuabili le impostazioni di configurazione utilizzando il completamento automatico C#. Le app professionali usano in genere un provider di configurazione per configurare le opzioni OIDC, ad esempio il provider di configurazione JSON predefinito. Il provider di configurazione JSON carica la configurazione dai file appsettings.json/appsettings.{ENVIRONMENT}.json di impostazioni dell'applicazione, dove il {ENVIRONMENT} segnaposto è l'ambiente di runtime dell'applicazione. Seguire le indicazioni riportate in questa sezione per usare i file di impostazioni dell'app per la configurazione.

Nel file delle impostazioni dell'app (appsettings.json) del BlazorWebAppEntra progetto aggiungere la configurazione JSON seguente:

{
  "AzureAd": {
    "CallbackPath": "/signin-oidc",
    "ClientId": "{CLIENT ID (BLAZOR APP)}",
    "Domain": "{DIRECTORY NAME}.onmicrosoft.com",
    "Instance": "https://login.microsoftonline.com/",
    "ResponseType": "code",
    "TenantId": "{TENANT ID}"
  },
  "DownstreamApi": {
    "BaseUrl": "{BASE ADDRESS}",
    "Scopes": [ "{APP ID URI}/Weather.Get" ]
  }
}

Aggiornare i segnaposto nella configurazione precedente in modo che corrispondano ai valori usati dall'app nel Program file:

{CLIENT ID (BLAZOR APP)}: ID dell'applicazione (client).
{DIRECTORY NAME}: nome della directory del dominio tenant (server di pubblicazione).
{TENANT ID}: ID del tenant della directory.
{BASE ADDRESS}: indirizzo di base dell'API Web.
{APP ID URI}: URI dell'ID app per gli ambiti dell'API web. Viene utilizzato uno dei seguenti formati, dove il segnaposto {CLIENT ID (WEB API)} è l'ID client della registrazione Entra dell'API web e il segnaposto {DIRECTORY NAME} è il nome della directory del dominio del tenant (ad esempio: contoso).
- ME-ID formato del tenant: api://{CLIENT ID (WEB API)}
- Formato tenant B2C: https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Esempio:

"AzureAd": {
  "CallbackPath": "/signin-oidc",
  "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "Domain": "contoso.onmicrosoft.com",
  "Instance": "https://login.microsoftonline.com/",
  "ResponseType": "code",
  "TenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
},
...
"DownstreamApi": {
  "BaseUrl": "https://localhost:7277",
  "Scopes": [ "api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get" ]
}

Aggiornare tutti gli altri valori nella configurazione precedente in modo che corrispondano ai valori personalizzati/non predefiniti usati nel Program file.

La configurazione viene prelevata automaticamente dal generatore di autenticazione.

Apportare le modifiche seguenti nel Program file:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
-   .AddMicrosoftIdentityWebApp(msIdentityOptions =>
-   {
-       msIdentityOptions.CallbackPath = "...";
-       msIdentityOptions.ClientId = "...";
-       msIdentityOptions.Domain = "...";
-       msIdentityOptions.Instance = "...";
-       msIdentityOptions.ResponseType = "...";
-       msIdentityOptions.TenantId = "...";
-   })
+   .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
-   .AddDownstreamApi("DownstreamApi", configOptions =>
-   {
-       configOptions.BaseUrl = "...";
-       configOptions.Scopes = [ "..." ];
-   })
+   .AddDownstreamApi("DownstreamApi", builder.Configuration.GetSection("DownstreamApi"))
    .AddInMemoryTokenCaches();

Nel progetto MinimalApiJwt, aggiungi la seguente configurazione delle impostazioni dell'applicazione al file appsettings.json.

"Authentication": {
  "Schemes": {
    "Bearer": {
      "Authority": "https://sts.windows.net/{TENANT ID (WEB API)}/",
      "ValidAudiences": [ "{APP ID URI (WEB API)}" ]
    }
  }
},

Aggiornare i segnaposto nella configurazione precedente in modo che corrispondano ai valori usati dall'app nel Program file:

{TENANT ID (WEB API)}: Tenant ID dell'API web.
{APP ID URI (WEB API)}: URI ID app dell'API Web.

I formati di autorità adottano i seguenti schemi:

ME-ID tipo di locatario: https://sts.windows.net/{TENANT ID}/
Tipo di tenant B2C: https://login.microsoftonline.com/{TENANT ID}/v2.0/

I formati di destinatari adottano i modelli seguenti ({CLIENT ID} è l'ID client dell'API Web; {DIRECTORY NAME} è il nome della directory, ad esempio ): contoso

ME-ID tipo di tenant: api://{CLIENT ID}
Tipo di tenant B2C: https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}

La configurazione viene acquisita automaticamente dal builder di autenticazione JWT bearer.

Rimuovere le righe seguenti dal Program file:

- jwtOptions.Authority = "...";
- jwtOptions.Audience = "...";

Per altre informazioni sulla configurazione, vedere le risorse seguenti:

Reindirizzare alla pagina iniziale dopo la disconnessione

Il componente LogInOrOut (Layout/LogInOrOut.razor) imposta un campo nascosto per l'URL restituito (ReturnUrl) sull'URL corrente (currentURL). Quando l'utente si disconnette dall'app, il provider di identità restituisce l'utente alla pagina da cui si è disconnesso. Se l'utente si disconnette da una pagina sicura, viene restituito alla stessa pagina protetta e inviato tramite il processo di autenticazione. Questo flusso di autenticazione è ragionevole quando gli utenti devono modificare regolarmente gli account.

In alternativa, utilizzare il componente LogInOrOut seguente, che non fornisce un URL di ritorno durante la disconnessione.

Layout/LogInOrOut.razor:

<div class="nav-item px-3">
    <AuthorizeView>
        <Authorized>
            <form action="authentication/logout" method="post">
                <AntiforgeryToken />
                <button type="submit" class="nav-link">
                    <span class="bi bi-arrow-bar-left-nav-menu" aria-hidden="true">
                    </span> Logout
                </button>
            </form>
        </Authorized>
        <NotAuthorized>
            <a class="nav-link" href="authentication/login">
                <span class="bi bi-person-badge-nav-menu" aria-hidden="true"></span>
                Login
            </a>
        </NotAuthorized>
    </AuthorizeView>
</div>

Sicurezza dei dati meteo

Per ulteriori informazioni su come questa app assicura i dati meteorologici, vedere Protezione dei dati in Blazor Web Appcon rendering automatico interattivo.

Risoluzione dei problemi

Registrazione

L'app server è un'app standard ASP.NET Core. Consultare le linee guida di logging di ASP.NET Core per abilitare un livello di log più basso nell'app server.

Per abilitare il debug o la registrazione di tracce per Blazor WebAssembly l'autenticazione, consultare la sezione sulla registrazione dell'autenticazione lato client in ASP.NET Core Blazor, con il selettore della versione dell'articolo impostato su ASP.NET Core 7.0 o versione successiva.

Errori comuni

Il debugger si interrompe in caso di eccezione durante la disconnessione con Microsoft Entra External ID

L'eccezione seguente arresta il debugger di Visual Studio durante la disconnessione da Microsoft Entra External ID:

Uncaught TypeError TypeError: Failed to execute 'postMessage' on 'Window': The provided value cannot be converted to a sequence.

L'eccezione viene generata dal codice JavaScript Entra, quindi questo non è un problema con ASP.NET Core. L'eccezione non influisce sulle funzionalità dell'app nell'ambiente di produzione, quindi l'eccezione può essere ignorata durante i test di sviluppo locali.
Configurazione errata dell'app o Identity del provider (IP)

Gli errori più comuni sono causati da una configurazione errata. Di seguito sono riportati alcuni esempi:
- A seconda dei requisiti dello scenario, un'autorità mancante o non corretta, istanza, ID tenant, dominio tenant, ID client o URI di reindirizzamento impedisce a un'app di autenticare i client.
- Gli ambiti di richiesta non corretti impediscono ai client di accedere agli endpoint DELL'API Web del server.
- Autorizzazioni DELL'API server non corrette o mancanti impediscono ai client di accedere agli endpoint DELL'API Web del server.
- L'esecuzione dell'app su una porta diversa da quella configurata nell'URI di reindirizzamento della registrazione dell'app dell'IP. Si noti che non è richiesta la configurazione di una porta per Microsoft Entra ID e un'app in esecuzione a un indirizzo di test di sviluppo localhost, ma la configurazione della porta dell'app e la porta su cui l'app è in esecuzione devono corrispondere per gli indirizzi non localhost.
La copertura di configurazione in questo articolo mostra esempi di configurazione corretta. Controllare attentamente la configurazione alla ricerca di errori di configurazione di app e IP.

Se la configurazione è corretta:
- Analizzare i log delle applicazioni.
- Esaminare il traffico di rete tra l'app client e l'app IP o server con gli strumenti di sviluppo del browser. Spesso, un messaggio di errore esatto o un messaggio con un indizio sulla causa del problema viene restituito al client dall'app IP o server dopo aver effettuato una richiesta. La guida agli strumenti di sviluppo è disponibile nei seguenti articoli:
  - Google Chrome (documentazione di Google)
  - Microsoft Edge
  - Mozilla Firefox (documentazione di Mozilla)
Il team della documentazione risponde al feedback e ai bug dei documenti negli articoli (aprire un problema dalla sezione Commenti e suggerimenti della pagina ), ma non è in grado di fornire supporto tecnico. Sono disponibili diversi forum di supporto pubblico per facilitare la risoluzione dei problemi di un'app. Consigliamo quanto segue:
I forum precedenti non sono di proprietà o controllati da Microsoft.

Per i report sui bug del framework non sensibili e non riservati, segnalare un problema all'unità prodotto di ASP.NET Core. Non aprire un problema con l'unità di prodotto fino a quando non hai approfondito la causa di un problema e non puoi risolverlo autonomamente e con l'aiuto della community in un forum di supporto pubblico. L'unità prodotto non è in grado di risolvere i problemi relativi alle singole app interrotte a causa di semplici errori di configurazione o casi d'uso che coinvolgono servizi di terze parti. Se un report è sensibile o riservato in natura o descrive un potenziale difetto di sicurezza nel prodotto che potrebbero sfruttare i cyberattacker, vedere Segnalazione di problemi e bug di sicurezza (dotnet/aspnetcorerepository GitHub).
Client non autorizzato per ME-ID

info: Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] Autorizzazione non riuscita. Questi requisiti non sono stati soddisfatti: DenyAnonymousAuthorizationRequirement: richiede un utente autenticato.

Errore di callback durante l'accesso da ME-ID:
- Errore: unauthorized_client
- Description (Descrizione): AADB2C90058: The provided application is not configured to allow public clients.
Per risolvere l'errore:
1. Nella portale di Azure accedere al manifesto dell'app.
2. Impostare l'attributo allowPublicClient su null o .true

Cookie e dati del sito

I cookie e i dati del sito possono persistere tra gli aggiornamenti delle app e interferire con i test e la risoluzione dei problemi. Cancellare quanto segue quando si apportano modifiche al codice dell'app, modifiche all'account utente con il provider o modifiche alla configurazione dell'app del provider:

Cookie di accesso utente
Cookie dell'app
Dati del sito memorizzati nella cache e archiviati

Un approccio per evitare che i cookie e i dati del sito persistenti interferiscano con i test e la risoluzione dei problemi consiste nel:

Configurare un browser
- Utilizzare un browser configurabile per i test in grado di eliminare tutti i cookie dati del sito ogni volta che il browser viene chiuso.
- Assicurarsi che il browser venga chiuso manualmente o dall'IDE per qualsiasi modifica apportata alla configurazione dell'app, dell'utente di test o del provider.
Usare un comando personalizzato per aprire un browser in modalità InPrivate o In incognito in Visual Studio:
- Apri la finestra di dialogo Sfoglia con dal pulsante Esegui di Visual Studio.
- Seleziona il pulsante Aggiungi.
- Specificare il percorso del browser nel campo Programma . I percorsi eseguibili seguenti sono percorsi di installazione tipici per Windows 10. Se il browser è installato in un percorso diverso o non si usa Windows 10, specificare il percorso dell'eseguibile del browser.
  - Microsoft Edge: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
  - Google Chrome: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
  - Mozilla Firefox: C:\Program Files\Mozilla Firefox\firefox.exe
- Nel campo Argomenti specificare l'opzione della riga di comando usata dal browser per aprire in modalità InPrivate o Incognito. Alcuni browser richiedono l'URL dell'app.
  - Microsoft Edge: usare -inprivate.
  - Google Chrome: usare --incognito --new-window {URL}, dove il {URL} segnaposto è l'URL da aprire (ad esempio, https://localhost:5001).
  - Mozilla Firefox: usare -private -url {URL}, dove il {URL} segnaposto è l'URL da aprire (ad esempio, https://localhost:5001).
- Fornire un nome nel campo Nome descrittivo. Ad esempio: Firefox Auth Testing.
- Selezionare il pulsante OK.
- Per evitare di dover selezionare il profilo del browser per ogni iterazione di test con un'app, impostare il profilo come predefinito con il pulsante Imposta come predefinito .
- Assicurarsi che il browser sia chiuso dall'IDE per qualsiasi modifica apportata all'app, all'utente di test o alla configurazione del provider.

Aggiornamenti di app

Un'app funzionante potrebbe smettere di funzionare subito dopo l'aggiornamento dell'SDK .NET Core sul computer di sviluppo o la modifica delle versioni dei pacchetti nell'app stessa. In alcuni casi i pacchetti incoerenti possono interrompere un'app quando si eseguono aggiornamenti principali. La maggior parte di questi problemi può essere risolta attenendosi alle istruzioni seguenti:

Cancellare le cache dei pacchetti NuGet del sistema locale eseguendo dotnet nuget locals all --clear da una shell dei comandi.
Eliminare le cartelle bin e obj del progetto.
Ripristina e ricostruisci il progetto.
Eliminare tutti i file nella cartella di distribuzione nel server prima di ridistribuire l'app.

Nota

L'uso di versioni del pacchetto incompatibili con il framework di destinazione dell'app non è supportato. Per informazioni su un pacchetto, utilizzare la NuGet Gallery.

Eseguire l'app server

Durante i test e la risoluzione dei problemi Blazor Web App, assicurarsi di eseguire l'app dal progetto server.

Esaminare l'utente

Il componente seguente UserClaims può essere usato direttamente nelle app o funge da base per un'ulteriore personalizzazione.

UserClaims.razor:

@page "/user-claims"
@using System.Security.Claims
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize]

<PageTitle>User Claims</PageTitle>

<h1>User Claims</h1>

@if (claims.Any())
{
    <ul>
        @foreach (var claim in claims)
        {
            <li><b>@claim.Type:</b> @claim.Value</li>
        }
    </ul>
}

@code {
    private IEnumerable<Claim> claims = Enumerable.Empty<Claim>();

    [CascadingParameter]
    private Task<AuthenticationState>? AuthState { get; set; }

    protected override async Task OnInitializedAsync()
    {
        if (AuthState == null)
        {
            return;
        }

        var authState = await AuthState;
        claims = authState.User.Claims;
    }
}

Risorse aggiuntive

documentazione di Microsoft Identity Platform
AzureAD/microsoft-identity-web Repository GitHub: indicazioni utili sull'implementazione di Microsoft Web per Microsoft Identity Entra ID e Azure Active Directory B2C per le app ASP.NET Core, inclusi collegamenti ad app di esempio e documentazione di Azure correlata. Attualmente, la documentazione di Azure non affronta esplicitamente il caso di Blazor Web App, ma l'installazione e la configurazione di un Blazor Web App per l'ID ME e l'hosting su Azure sono analoghe a quelle di qualsiasi applicazione web ASP.NET Core.
AuthenticationStateProvider servizio
Gestire lo stato di autenticazione in Blazor Web Apps
Astrazioni di servizio in Blazor Web Apps

Condividi tramite

Proteggere un ASP.NET Core Blazor Web App con Microsoft Entra ID

Soluzione di esempio

Registrazioni dell'app Microsoft Entra ID

Progetto server Blazor Web App lato (BlazorWebAppEntra)

Progetto lato utente Blazor Web App (BlazorWebAppEntra.Client)

Progetto API Web per il back-end (MinimalApiJwt)

Configurare il progetto API Web backend (MinimalApiJwt)

Configurare il progetto server (BlazorWebAppEntra)

Prerequisiti

Soluzione di esempio

Registrazioni dell'app Microsoft Entra ID

.NET Aspire progetti

Progetto server Blazor Web App lato (BlazorWebAppEntra)

Progetto lato utente Blazor Web App (BlazorWebAppEntra.Client)

Progetto API Web per il back-end (MinimalApiJwt)

Configurare il progetto API Web backend (MinimalApiJwt)

Configurare il progetto server (BlazorWebAppEntra)

Stabilire il segreto del client

Strumento Gestore Segreti

Azure Key Vault (Archivio chiavi di Azure)

Serializzare solo il nome e le attestazioni del ruolo

Fornire la configurazione con il provider di configurazione JSON (impostazioni dell'app)

Reindirizzare alla pagina iniziale dopo la disconnessione

Sicurezza dei dati meteo

Risoluzione dei problemi

Registrazione

Errori comuni

Cookie e dati del sito

Aggiornamenti di app

Eseguire l'app server

Esaminare l'utente

Risorse aggiuntive

Risorse aggiuntive

Progetto server Blazor Web App lato (`BlazorWebAppEntra`)

Progetto lato utente Blazor Web App (`BlazorWebAppEntra.Client`)

Progetto API Web per il back-end (`MinimalApiJwt`)

Configurare il progetto API Web backend (`MinimalApiJwt`)

Configurare il progetto server (`BlazorWebAppEntra`)

Progetto server Blazor Web App lato (`BlazorWebAppEntra`)

Progetto lato utente Blazor Web App (`BlazorWebAppEntra.Client`)

Progetto API Web per il back-end (`MinimalApiJwt`)

Configurare il progetto API Web backend (`MinimalApiJwt`)

Configurare il progetto server (`BlazorWebAppEntra`)