Usare l'API Graph con ASP.NET Core Blazor WebAssembly

Le indicazioni seguenti si applicano a Microsoft Graph v5.

Microsoft Graph SDK per l'uso nelle Blazor app è denominato libreria client .NET di Microsoft Graph.

• Microsoft.AspNetCore.Components.WebAssembly.Authentication
• Microsoft.Authentication.WebAssembly.Msal
• Microsoft.Extensions.Http
• Microsoft.Graph

Nella portale di Azure concedere autorizzazioni delegate (ambiti)† per i dati di Microsoft Graph a cui l'app deve poter accedere per conto di un utente. Per l'esempio in questo articolo, la registrazione dell'app deve includere l'autorizzazione delegata per leggere i dati utente (Microsoft.Graph>User.Read ambito nelle autorizzazioni API, Tipo: Delegato). L'ambito User.Read consente agli utenti di accedere all'app e consente all'app di leggere il profilo e le informazioni aziendali degli utenti connessi. Per altre informazioni, vedere Panoramica delle autorizzazioni e del consenso nella piattaforma Microsoft identity e Panoramica delle autorizzazioni di Microsoft Graph.

†Permissions e ambiti indicano la stessa cosa e vengono usati in modo intercambiabile nella documentazione di sicurezza e nella portale di Azure. A meno che il testo non faccia riferimento alla portale di Azure, questo articolo usa ambiti di ambito/ quando si fa riferimento alle autorizzazioni graph.

Gli ambiti non fanno distinzione tra maiuscole e minuscole, quindi User.Read equivale a user.read. È possibile usare entrambi i formati, ma è consigliabile scegliere in modo coerente il codice dell'applicazione.

Dopo aver aggiunto gli ambiti dell'API Microsoft Graph alla registrazione dell'app nella portale di Azure, aggiungere la configurazione delle impostazioni dell'app seguente al wwwroot/appsettings.json file nell'app, che include l'URL di base graph con la versione e gli ambiti di Microsoft Graph. Nell'esempio seguente viene specificato l'ambito User.Read per gli esempi nelle sezioni successive di questo articolo. Gli ambiti non fanno distinzione tra maiuscole e minuscole.

"MicrosoftGraph": {
  "BaseUrl": "https://graph.microsoft.com",
  "Version": "{VERSION}",
  "Scopes": [
    "user.read"
  ]
}

Nell'esempio precedente il {VERSION} segnaposto è la versione dell'API Microsoft Graph (ad esempio: v1.0).

Di seguito è riportato un esempio di file di configurazione completo wwwroot/appsettings.json per un'app che usa ME-ID come identity provider, in cui viene specificata la lettura dei dati utente (user.read ambito) per Microsoft Graph:

{
  "AzureAd": {
    "Authority": "https://login.microsoftonline.com/{TENANT ID}",
    "ClientId": "{CLIENT ID}",
    "ValidateAuthority": true
  },
  "MicrosoftGraph": {
    "BaseUrl": "https://graph.microsoft.com",
    "Version": "v1.0",
    "Scopes": [
      "user.read"
    ]
  }
}

Nell'esempio precedente il {TENANT ID} segnaposto è l'ID directory (tenant) e il {CLIENT ID} segnaposto è l'ID applicazione (client). Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Quando non viene ottenuto un token di accesso, il codice seguente non imposta un'intestazione di autorizzazione Bearer per le richieste Graph.

GraphClientExtensions.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using Microsoft.Authentication.WebAssembly.Msal.Models;
using Microsoft.Graph;
using Microsoft.Kiota.Abstractions;
using Microsoft.Kiota.Abstractions.Authentication;
using IAccessTokenProvider = 
    Microsoft.AspNetCore.Components.WebAssembly.Authentication.IAccessTokenProvider;

namespace BlazorSample;

internal static class GraphClientExtensions
{
    public static IServiceCollection AddGraphClient(
            this IServiceCollection services, string? baseUrl, List<string>? scopes)
    {
        if (string.IsNullOrEmpty(baseUrl) || scopes?.Count == 0)
        {
            return services;
        }

        services.Configure<RemoteAuthenticationOptions<MsalProviderOptions>>(
            options =>
            {
                scopes?.ForEach((scope) =>
                {
                    options.ProviderOptions.DefaultAccessTokenScopes.Add(scope);
                });
            });

        services.AddScoped<IAuthenticationProvider, GraphAuthenticationProvider>();

        services.AddScoped(sp =>
        {
            return new GraphServiceClient(
                new HttpClient(),
                sp.GetRequiredService<IAuthenticationProvider>(),
                baseUrl);
        });

        return services;
    }

    private class GraphAuthenticationProvider(IAccessTokenProvider tokenProvider, 
        IConfiguration config) : IAuthenticationProvider
    {
        private readonly IConfiguration config = config;

        public IAccessTokenProvider TokenProvider { get; } = tokenProvider;

        public async Task AuthenticateRequestAsync(RequestInformation request, 
            Dictionary<string, object>? additionalAuthenticationContext = null, 
            CancellationToken cancellationToken = default)
        {
            var result = await TokenProvider.RequestAccessToken(
                new AccessTokenRequestOptions()
                {
                    Scopes = 
                        config.GetSection("MicrosoftGraph:Scopes").Get<string[]>() ??
                        [ "user.read" ]
                });

            if (result.TryGetToken(out var token))
            {
                request.Headers.Add("Authorization", 
                    $"{CoreConstants.Headers.Bearer} {token.Value}");
            }
        }
    }
}

Program Nel file aggiungere i servizi client Graph e la configurazione con il AddGraphClient metodo di estensione. Per impostazione predefinita, il codice seguente è l'indirizzo di base e User.Read gli ambiti di Microsoft Graph versione 1.0 se queste impostazioni non vengono trovate nel file delle impostazioni dell'app:

var baseUrl = string.Join("/",
    builder.Configuration.GetSection("MicrosoftGraph")["BaseUrl"] ??
        "https://graph.microsoft.com",
    builder.Configuration.GetSection("MicrosoftGraph")["Version"] ??
        "v1.0");
var scopes = builder.Configuration.GetSection("MicrosoftGraph:Scopes")
    .Get<List<string>>() ?? [ "user.read" ];

builder.Services.AddGraphClient(baseUrl, scopes);

Chiamare l'API Graph da un componente usando Graph SDK

Il componente seguente UserData usa un oggetto inserito GraphServiceClient per ottenere i dati del profilo ME-ID dell'utente e visualizzare il numero di telefono cellulare.

Per qualsiasi utente di test creato in ME-ID, assicurarsi di assegnare al profilo ME-ID dell'utente un numero di telefono cellulare nel portale di Azure.

UserData.razor:

@page "/user-data"
@using Microsoft.AspNetCore.Authorization
@using Microsoft.Graph
@attribute [Authorize]
@inject GraphServiceClient Client

<PageTitle>User Data</PageTitle>

<h1>Microsoft Graph User Data</h1>

@if (!string.IsNullOrEmpty(user?.MobilePhone))
{
    <p>Mobile Phone: @user.MobilePhone</p>
}

@code {
    private Microsoft.Graph.Models.User? user;

    protected override async Task OnInitializedAsync()
    {
        user = await Client.Me.GetAsync();
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-data">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Data
    </NavLink>
</div>

Quando si esegue il test con Graph SDK in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Personalizzare le attestazioni utente con Graph SDK

Nell'esempio seguente l'app crea le attestazioni relative al numero di telefono cellulare e alla posizione dell'ufficio per un utente dai dati del profilo utente ME-ID. L'app deve avere l'ambito dell'API User.Read Graph configurato in ME-ID. Tutti gli utenti di test per questo scenario devono avere un numero di telefono cellulare e la posizione dell'ufficio nel profilo ME-ID, che può essere aggiunto tramite il portale di Azure.

Nella factory dell'account utente personalizzata seguente:

• Un ILogger oggetto (logger) è incluso per praticità nel caso in cui si desideri registrare informazioni o errori nel CreateUserAsync metodo .
• Nel caso in cui venga generata un'eccezione AccessTokenNotAvailableException , l'utente viene reindirizzato al identity provider per accedere al proprio account. È possibile eseguire azioni aggiuntive o diverse quando la richiesta di un token di accesso non riesce. Ad esempio, l'app può registrare AccessTokenNotAvailableException e creare un ticket di supporto per ulteriori indagini.
• Il framework rappresenta l'account RemoteUserAccount dell'utente. Se l'app richiede una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata per RemoteUserAccount nel codice seguente.

CustomAccountFactory.cs:

using System.Security.Claims;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication.Internal;
using Microsoft.Graph;
using Microsoft.Kiota.Abstractions.Authentication;

public class CustomAccountFactory(IAccessTokenProviderAccessor accessor,
        IServiceProvider serviceProvider, ILogger<CustomAccountFactory> logger,
        IConfiguration config) 
    : AccountClaimsPrincipalFactory<RemoteUserAccount>(accessor)
{
    private readonly ILogger<CustomAccountFactory> logger = logger;
    private readonly IServiceProvider serviceProvider = serviceProvider;
    private readonly string? baseUrl = string.Join("/",
        config.GetSection("MicrosoftGraph")["BaseUrl"] ?? 
            "https://graph.microsoft.com",
        config.GetSection("MicrosoftGraph")["Version"] ??
            "v1.0");

    public override async ValueTask<ClaimsPrincipal> CreateUserAsync(
        RemoteUserAccount account,
        RemoteAuthenticationUserOptions options)
    {
        var initialUser = await base.CreateUserAsync(account, options);

        if (initialUser.Identity is not null &&
            initialUser.Identity.IsAuthenticated)
        {
            var userIdentity = initialUser.Identity as ClaimsIdentity;

            if (userIdentity is not null && !string.IsNullOrEmpty(baseUrl))
            {
                try
                {
                    var client = new GraphServiceClient(
                        new HttpClient(),
                        serviceProvider
                            .GetRequiredService<IAuthenticationProvider>(),
                        baseUrl);

                    var user = await client.Me.GetAsync();

                    if (user is not null)
                    {
                        userIdentity.AddClaim(new Claim("mobilephone",
                            user.MobilePhone ?? "(000) 000-0000"));
                        userIdentity.AddClaim(new Claim("officelocation",
                            user.OfficeLocation ?? "Not set"));
                    }
                }
                catch (AccessTokenNotAvailableException exception)
                {
                    exception.Redirect();
                }
            }
        }

        return initialUser;
    }
}

Configurare l'autenticazione MSAL per l'uso della factory dell'account utente personalizzata.

Verificare che il Program file usi lo Microsoft.AspNetCore.Components.WebAssembly.Authentication spazio dei nomi :

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;

L'esempio in questa sezione si basa sull'approccio di lettura dell'URL di base con la versione e gli ambiti dalla configurazione dell'app tramite la MicrosoftGraph sezione nel wwwroot/appsettings.json file. Le righe seguenti dovrebbero essere già presenti nel Program file seguendo le indicazioni riportate in precedenza in questo articolo:

var baseUrl = string.Join("/",
    builder.Configuration.GetSection("MicrosoftGraph")["BaseUrl"] ??
        "https://graph.microsoft.com",
    builder.Configuration.GetSection("MicrosoftGraph")["Version"] ??
        "v1.0");
var scopes = builder.Configuration.GetSection("MicrosoftGraph:Scopes")
    .Get<List<string>>() ?? [ "user.read" ];

builder.Services.AddGraphClient(baseUrl, scopes);

Program Nel file trovare la chiamata al AddMsalAuthentication metodo di estensione. Aggiornare il codice al codice seguente, che include una chiamata a AddAccountClaimsPrincipalFactory che aggiunge una factory dell'entità attestazioni dell'account con .CustomAccountFactory

Se l'app usa una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata per RemoteUserAccount nel codice seguente.

builder.Services.AddMsalAuthentication<RemoteAuthenticationState,
    RemoteUserAccount>(options =>
    {
        builder.Configuration.Bind("AzureAd", 
            options.ProviderOptions.Authentication);
    })
    .AddAccountClaimsPrincipalFactory<RemoteAuthenticationState, RemoteUserAccount,
        CustomAccountFactory>();

È possibile usare il componente seguente UserClaims per studiare le attestazioni dell'utente dopo l'autenticazione dell'utente con ME-ID:

UserClaims.razor:

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

<h1>User Claims</h1>

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

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

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthenticationStateProvider
            .GetAuthenticationStateAsync();
        var user = authState.User;

        claims = user.Claims;
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-claims">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Claims
    </NavLink>
</div>

Quando si esegue il test con Graph SDK in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Le indicazioni seguenti si applicano a Microsoft Graph v4. Se si sta aggiornando un'app dall'SDK v4 alla versione 5, vedere la guida al log delle modifiche e all'aggiornamento di Microsoft Graph .NET SDK v5.

Microsoft Graph SDK per l'uso nelle Blazor app è denominato libreria client .NET di Microsoft Graph.

• Microsoft.AspNetCore.Components.WebAssembly.Authentication
• Microsoft.Authentication.WebAssembly.Msal
• Microsoft.Extensions.Http
• Microsoft.Graph

Nella portale di Azure concedere autorizzazioni delegate (ambiti)† per i dati di Microsoft Graph a cui l'app deve poter accedere per conto di un utente. Per l'esempio in questo articolo, la registrazione dell'app deve includere l'autorizzazione delegata per leggere i dati utente (Microsoft.Graph>User.Read ambito nelle autorizzazioni API, Tipo: Delegato). L'ambito User.Read consente agli utenti di accedere all'app e consente all'app di leggere il profilo e le informazioni aziendali degli utenti connessi. Per altre informazioni, vedere Panoramica delle autorizzazioni e del consenso nella piattaforma Microsoft identity e Panoramica delle autorizzazioni di Microsoft Graph.

†Permissions e ambiti indicano la stessa cosa e vengono usati in modo intercambiabile nella documentazione di sicurezza e nella portale di Azure. A meno che il testo non faccia riferimento alla portale di Azure, questo articolo usa ambiti di ambito/ quando si fa riferimento alle autorizzazioni graph.

Gli ambiti non fanno distinzione tra maiuscole e minuscole, quindi User.Read equivale a user.read. È possibile usare entrambi i formati, ma è consigliabile scegliere in modo coerente il codice dell'applicazione.

Dopo aver aggiunto gli ambiti dell'API Microsoft Graph alla registrazione dell'app nella portale di Azure, aggiungere la configurazione delle impostazioni dell'app seguente al wwwroot/appsettings.json file nell'app, che include l'URL di base graph con la versione e gli ambiti di Microsoft Graph. Nell'esempio seguente viene specificato l'ambito User.Read per gli esempi nelle sezioni successive di questo articolo. Gli ambiti non fanno distinzione tra maiuscole e minuscole.

"MicrosoftGraph": {
  "BaseUrl": "https://graph.microsoft.com",
  "Version": "{VERSION}",
  "Scopes": [
    "user.read"
  ]
}

Nell'esempio precedente il {VERSION} segnaposto è la versione dell'API Microsoft Graph (ad esempio: v1.0).

Di seguito è riportato un esempio di file di configurazione completo wwwroot/appsettings.json per un'app che usa ME-ID come identity provider, in cui viene specificata la lettura dei dati utente (user.read ambito) per Microsoft Graph:

{
  "AzureAd": {
    "Authority": "https://login.microsoftonline.com/{TENANT ID}",
    "ClientId": "{CLIENT ID}",
    "ValidateAuthority": true
  },
  "MicrosoftGraph": {
    "BaseUrl": "https://graph.microsoft.com",
    "Version": "v1.0",
    "Scopes": [
      "user.read"
    ]
  }
}

Nell'esempio precedente il {TENANT ID} segnaposto è l'ID directory (tenant) e il {CLIENT ID} segnaposto è l'ID applicazione (client). Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Quando non viene ottenuto un token di accesso, il codice seguente non imposta un'intestazione di autorizzazione Bearer per le richieste Graph.

GraphClientExtensions.cs:

using System.Net.Http.Headers;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using Microsoft.Authentication.WebAssembly.Msal.Models;
using Microsoft.Graph;

namespace BlazorSample;

internal static class GraphClientExtensions
{
    public static IServiceCollection AddGraphClient(
        this IServiceCollection services, string? baseUrl, List<string>? scopes)
    {
        if (string.IsNullOrEmpty(baseUrl) || scopes?.Count == 0)
        {
            return services;
        }

        services.Configure<RemoteAuthenticationOptions<MsalProviderOptions>>(
            options =>
            {
                scopes?.ForEach((scope) =>
                {
                    options.ProviderOptions.DefaultAccessTokenScopes.Add(scope);
                });
            });

        services.AddScoped<IAuthenticationProvider, GraphAuthenticationProvider>();

        services.AddScoped<IHttpProvider, HttpClientHttpProvider>(sp =>
            new HttpClientHttpProvider(new HttpClient()));

        services.AddScoped(sp =>
        {
            return new GraphServiceClient(
                baseUrl,
                sp.GetRequiredService<IAuthenticationProvider>(),
                sp.GetRequiredService<IHttpProvider>());
        });

        return services;
    }

    private class GraphAuthenticationProvider(IAccessTokenProvider tokenProvider, 
        IConfiguration config) : IAuthenticationProvider
    {
        private readonly IConfiguration config = config;

        public IAccessTokenProvider TokenProvider { get; } = tokenProvider;

        public async Task AuthenticateRequestAsync(HttpRequestMessage request)
        {
            var result = await TokenProvider.RequestAccessToken(
                new AccessTokenRequestOptions()
                { 
                    Scopes = config.GetSection("MicrosoftGraph:Scopes").Get<string[]>()
                });

            if (result.TryGetToken(out var token))
            {
                request.Headers.Authorization ??= new AuthenticationHeaderValue(
                    "Bearer", token.Value);
            }
        }
    }

    private class HttpClientHttpProvider(HttpClient client) : IHttpProvider
    {
        private readonly HttpClient client = client;

        public ISerializer Serializer { get; } = new Serializer();

        public TimeSpan OverallTimeout { get; set; } = TimeSpan.FromSeconds(300);

        public Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
        {
            return client.SendAsync(request);
        }

        public Task<HttpResponseMessage> SendAsync(HttpRequestMessage request,
            HttpCompletionOption completionOption,
            CancellationToken cancellationToken)
        {
            return client.SendAsync(request, completionOption, cancellationToken);
        }

        public void Dispose()
        {
        }
    }
}

Program Nel file aggiungere i servizi client Graph e la configurazione con il metodo di AddGraphClient estensione:

var baseUrl = string.Join("/",
    builder.Configuration.GetSection("MicrosoftGraph")["BaseUrl"] ??
        "https://graph.microsoft.com",
    builder.Configuration.GetSection("MicrosoftGraph")["Version"] ??
        "v1.0");
var scopes = builder.Configuration.GetSection("MicrosoftGraph:Scopes")
    .Get<List<string>>() ?? [ "user.read" ];

builder.Services.AddGraphClient(baseUrl, scopes);

Chiamare l'API Graph da un componente usando Graph SDK

Il componente seguente UserData usa un oggetto inserito GraphServiceClient per ottenere i dati del profilo ME-ID dell'utente e visualizzare il numero di telefono cellulare. Per qualsiasi utente di test creato in ME-ID, assicurarsi di assegnare al profilo ME-ID dell'utente un numero di telefono cellulare nel portale di Azure.

UserData.razor:

@page "/user-data"
@using Microsoft.AspNetCore.Authorization
@using Microsoft.Graph
@attribute [Authorize]
@inject GraphServiceClient Client

<PageTitle>User Data</PageTitle>

<h1>Microsoft Graph User Data</h1>

@if (!string.IsNullOrEmpty(user?.MobilePhone))
{
    <p>Mobile Phone: @user.MobilePhone</p>
}

@code {
    private Microsoft.Graph.User? user;

    protected override async Task OnInitializedAsync()
    {
        var request = Client.Me.Request();
        user = await request.GetAsync();
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-data">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Data
    </NavLink>
</div>

Quando si esegue il test con Graph SDK in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Personalizzare le attestazioni utente con Graph SDK

Nell'esempio seguente l'app crea le attestazioni relative al numero di telefono cellulare e alla posizione dell'ufficio per un utente dai dati del profilo utente ME-ID. L'app deve avere l'ambito dell'API User.Read Graph configurato in ME-ID. Tutti gli utenti di test per questo scenario devono avere un numero di telefono cellulare e la posizione dell'ufficio nel profilo ME-ID, che può essere aggiunto tramite il portale di Azure.

Nella factory dell'account utente personalizzata seguente:

• Un ILogger oggetto (logger) è incluso per praticità nel caso in cui si desideri registrare informazioni o errori nel CreateUserAsync metodo .
• Nel caso in cui venga generata un'eccezione AccessTokenNotAvailableException , l'utente viene reindirizzato al identity provider per accedere al proprio account. È possibile eseguire azioni aggiuntive o diverse quando la richiesta di un token di accesso non riesce. Ad esempio, l'app può registrare AccessTokenNotAvailableException e creare un ticket di supporto per ulteriori indagini.
• Il framework rappresenta l'account RemoteUserAccount dell'utente. Se l'app richiede una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata per RemoteUserAccount nel codice seguente.

CustomAccountFactory.cs:

using System.Security.Claims;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication.Internal;
using Microsoft.Graph;

public class CustomAccountFactory(IAccessTokenProviderAccessor accessor, 
        IServiceProvider serviceProvider, ILogger<CustomAccountFactory> logger)
    : AccountClaimsPrincipalFactory<RemoteUserAccount>(accessor)
{
    private readonly ILogger<CustomAccountFactory> logger = logger;
    private readonly IServiceProvider serviceProvider = serviceProvider;

    public override async ValueTask<ClaimsPrincipal> CreateUserAsync(
        RemoteUserAccount account,
        RemoteAuthenticationUserOptions options)
    {
        var initialUser = await base.CreateUserAsync(account, options);

        if (initialUser.Identity is not null && 
            initialUser.Identity.IsAuthenticated)
        {
            var userIdentity = initialUser.Identity as ClaimsIdentity;

            if (userIdentity is not null)
            {
                try
                {
                    var client = ActivatorUtilities
                        .CreateInstance<GraphServiceClient>(serviceProvider);
                    var request = client.Me.Request();
                    var user = await request.GetAsync();

                    if (user is not null)
                    {
                        userIdentity.AddClaim(new Claim("mobilephone",
                            user.MobilePhone ?? "(000) 000-0000"));
                        userIdentity.AddClaim(new Claim("officelocation",
                            user.OfficeLocation ?? "Not set"));
                    }
                }
                catch (AccessTokenNotAvailableException exception)
                {
                    exception.Redirect();
                }
            }
        }

        return initialUser;
    }
}

Configurare l'autenticazione MSAL per l'uso della factory dell'account utente personalizzata.

Verificare che il Program file usi lo Microsoft.AspNetCore.Components.WebAssembly.Authentication spazio dei nomi :

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;

L'esempio in questa sezione si basa sull'approccio di lettura dell'URL di base con la versione e gli ambiti dalla configurazione dell'app tramite la MicrosoftGraph sezione nel wwwroot/appsettings.json file. Le righe seguenti dovrebbero essere già presenti nel Program file seguendo le indicazioni riportate in precedenza in questo articolo:

var baseUrl = string.Join("/",
    builder.Configuration.GetSection("MicrosoftGraph")["BaseUrl"] ??
        "https://graph.microsoft.com",
    builder.Configuration.GetSection("MicrosoftGraph")["Version"] ??
        "v1.0");
var scopes = builder.Configuration.GetSection("MicrosoftGraph:Scopes")
    .Get<List<string>>() ?? [ "user.read" ];

builder.Services.AddGraphClient(baseUrl, scopes);

Program Nel file trovare la chiamata al AddMsalAuthentication metodo di estensione. Aggiornare il codice al codice seguente, che include una chiamata a AddAccountClaimsPrincipalFactory che aggiunge una factory dell'entità attestazioni dell'account con .CustomAccountFactory

Se l'app usa una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata per RemoteUserAccount nel codice seguente.

builder.Services.AddMsalAuthentication<RemoteAuthenticationState,
    RemoteUserAccount>(options =>
    {
        builder.Configuration.Bind("AzureAd", 
            options.ProviderOptions.Authentication);
    })
    .AddAccountClaimsPrincipalFactory<RemoteAuthenticationState, RemoteUserAccount,
        CustomAccountFactory>();

È possibile usare il componente seguente UserClaims per studiare le attestazioni dell'utente dopo l'autenticazione dell'utente con ME-ID:

UserClaims.razor:

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

<h1>User Claims</h1>

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

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

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthenticationStateProvider
            .GetAuthenticationStateAsync();
        var user = authState.User;

        claims = user.Claims;
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-claims">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Claims
    </NavLink>
</div>

Quando si esegue il test con Graph SDK in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Gli esempi seguenti usano un denominato HttpClient per le chiamate API Graph per ottenere il numero di telefono cellulare di un utente per elaborare una chiamata o per personalizzare le attestazioni di un utente in modo da includere un'attestazione di numero di telefono cellulare e un'attestazione di posizione dell'ufficio.

Nella portale di Azure concedere autorizzazioni delegate (ambiti)† per i dati di Microsoft Graph a cui l'app deve poter accedere per conto di un utente. Per l'esempio in questo articolo, la registrazione dell'app deve includere l'autorizzazione delegata per leggere i dati utente (Microsoft.Graph>User.Read ambito nelle autorizzazioni API, Tipo: Delegato). L'ambito User.Read consente agli utenti di accedere all'app e consente all'app di leggere il profilo e le informazioni aziendali degli utenti connessi. Per altre informazioni, vedere Panoramica delle autorizzazioni e del consenso nella piattaforma Microsoft identity e Panoramica delle autorizzazioni di Microsoft Graph.

†Permissions e ambiti indicano la stessa cosa e vengono usati in modo intercambiabile nella documentazione di sicurezza e nella portale di Azure. A meno che il testo non faccia riferimento alla portale di Azure, questo articolo usa ambiti di ambito/ quando si fa riferimento alle autorizzazioni graph.

Gli ambiti non fanno distinzione tra maiuscole e minuscole, quindi User.Read equivale a user.read. È possibile usare entrambi i formati, ma è consigliabile scegliere in modo coerente il codice dell'applicazione.

Dopo aver aggiunto gli ambiti dell'API Microsoft Graph alla registrazione dell'app nella portale di Azure, aggiungere la configurazione delle impostazioni dell'app seguente al wwwroot/appsettings.json file nell'app, che include l'URL di base graph con la versione e gli ambiti di Microsoft Graph. Nell'esempio seguente viene specificato l'ambito User.Read per gli esempi nelle sezioni successive di questo articolo. Gli ambiti non fanno distinzione tra maiuscole e minuscole.

"MicrosoftGraph": {
  "BaseUrl": "https://graph.microsoft.com",
  "Version": "{VERSION}",
  "Scopes": [
    "user.read"
  ]
}

Nell'esempio precedente il {VERSION} segnaposto è la versione dell'API Microsoft Graph (ad esempio: v1.0).

Di seguito è riportato un esempio di file di configurazione completo wwwroot/appsettings.json per un'app che usa ME-ID come identity provider, in cui viene specificata la lettura dei dati utente (user.read ambito) per Microsoft Graph:

{
  "AzureAd": {
    "Authority": "https://login.microsoftonline.com/{TENANT ID}",
    "ClientId": "{CLIENT ID}",
    "ValidateAuthority": true
  },
  "MicrosoftGraph": {
    "BaseUrl": "https://graph.microsoft.com",
    "Version": "v1.0",
    "Scopes": [
      "user.read"
    ]
  }
}

Nell'esempio precedente il {TENANT ID} segnaposto è l'ID directory (tenant) e il {CLIENT ID} segnaposto è l'ID applicazione (client). Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Creare la classe e la configurazione del progetto seguenti GraphAuthorizationMessageHandler nel file per l'uso Program dell'API Graph. L'URL di base e gli ambiti vengono forniti al gestore dalla configurazione.

GraphAuthorizationMessageHandler.cs:

using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication;

namespace BlazorSample;

public class GraphAuthorizationMessageHandler : AuthorizationMessageHandler
{
    public GraphAuthorizationMessageHandler(IAccessTokenProvider provider,
        NavigationManager navigation, IConfiguration config)
        : base(provider, navigation)
    {
        ConfigureHandler(
            authorizedUrls: [ 
                string.Join("/",
                    config.GetSection("MicrosoftGraph")["BaseUrl"] ??
                        "https://graph.microsoft.com",
                    config.GetSection("MicrosoftGraph")["Version"] ??
                        "v1.0")
            ],
            scopes: config.GetSection("MicrosoftGraph:Scopes")
                        .Get<List<string>>() ?? [ "user.read" ]);
    }
}

È necessaria la barra finale (/) dell'URL autorizzato. Il codice precedente compila l'URL autorizzato seguente dalla configurazione delle impostazioni dell'app o usa l'URL autorizzato seguente se la configurazione delle impostazioni dell'app è mancante: https://graph.microsoft.com/v1.0/.

Program Nel file configurare l'API Graph denominataHttpClient:

builder.Services.AddTransient<GraphAuthorizationMessageHandler>();

builder.Services.AddHttpClient("GraphAPI",
        client => client.BaseAddress = new Uri(
            string.Join("/",
                builder.Configuration.GetSection("MicrosoftGraph")["BaseUrl"] ??
                    "https://graph.microsoft.com",
                builder.Configuration.GetSection("MicrosoftGraph")["Version"] ??
                    "v1.0",
                string.Empty)))
    .AddHttpMessageHandler<GraphAuthorizationMessageHandler>();

Nell'esempio precedente l'oggetto GraphAuthorizationMessageHandler DelegatingHandler viene registrato come servizio temporaneo per AddHttpMessageHandler. La registrazione temporanea è consigliata per IHttpClientFactory, che gestisce i propri ambiti di inserimento delle dipendenze. Per ulteriori informazioni, vedi le seguenti risorse:

• Classi di componenti di base dell'utilità per gestire un ambito di inserimento delle dipendenze
• Rilevare gli eliminabili temporanei sul lato client

È necessaria una barra finale (/) sull'indirizzo di base. Nel codice precedente, il terzo argomento di string.Join consiste string.Empty nel garantire che la barra finale sia presente: https://graph.microsoft.com/v1.0/.

Chiamare l'API Graph da un componente usando un denominato HttpClient

La UserInfo.cs classe designa le proprietà del profilo utente necessarie con l'attributo JsonPropertyNameAttribute e il nome JSON usato da ME-ID. Nell'esempio seguente vengono impostate le proprietà per il numero di telefono cellulare e la posizione dell'ufficio dell'utente.

UserInfo.cs:

using System.Text.Json.Serialization;

namespace BlazorSample;

public class UserInfo
{
    [JsonPropertyName("mobilePhone")]
    public string? MobilePhone { get; set; }

    [JsonPropertyName("officeLocation")]
    public string? OfficeLocation { get; set; }
}

Nel componente seguente UserData viene creato un oggetto HttpClient per l'API Graph per emettere una richiesta per i dati del profilo dell'utente. La me risorsa (me) viene aggiunta all'URL di base con la versione per la richiesta dell'API Graph. I dati JSON restituiti da Graph vengono deserializzati nelle proprietà della UserInfo classe. Nell'esempio seguente viene ottenuto il numero di telefono cellulare. È possibile aggiungere codice simile per includere la posizione dell'ufficio del profilo ME-ID dell'utente, se lo si desidera (userInfo.OfficeLocation). Se la richiesta di token di accesso non riesce, l'utente viene reindirizzato per accedere all'app per un nuovo token di accesso.

UserData.razor:

@page "/user-data"
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication
@attribute [Authorize]
@inject IConfiguration Config
@inject IHttpClientFactory ClientFactory

<PageTitle>User Data</PageTitle>

<h1>Microsoft Graph User Data</h1>

@if (!string.IsNullOrEmpty(userInfo?.MobilePhone))
{
    <p>Mobile Phone: @userInfo.MobilePhone</p>
}

@code {
    private UserInfo? userInfo;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            var client = ClientFactory.CreateClient("GraphAPI");

            userInfo = await client.GetFromJsonAsync<UserInfo>("me");
        }
        catch (AccessTokenNotAvailableException exception)
        {
            exception.Redirect();
        }
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-data">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Data
    </NavLink>
</div>

La sequenza seguente descrive il nuovo flusso utente per gli ambiti dell'API Graph:

1. Il nuovo utente accede all'app per la prima volta.
2. L'utente acconsente all'uso dell'app nell'interfaccia utente del consenso di Azure.
3. L'utente accede a una pagina del componente che richiede i dati dell'API Graph per la prima volta.
4. L'utente viene reindirizzato all'interfaccia utente di consenso di Azure per fornire il consenso agli ambiti dell'API Graph.
5. Vengono restituiti i dati utente dell'API Graph.

Se si preferisce che il provisioning dell'ambito (consenso per gli ambiti dell'API Graph) venga eseguito nell'accesso iniziale, fornire gli ambiti all'autenticazione MSAL come ambiti predefiniti del token di accesso nel Program file:

+ var scopes = builder.Configuration.GetSection("MicrosoftGraph:Scopes")
+     .Get<List<string>>() ?? [ "user.read" ];

builder.Services.AddMsalAuthentication(options =>
{
    builder.Configuration.Bind("AzureAd", options.ProviderOptions.Authentication);

+   foreach (var scope in scopes)
+   {
+       options.ProviderOptions.DefaultAccessTokenScopes.Add(scope);
+   }
});

Quando vengono apportate le modifiche precedenti all'app, il flusso utente adotta la sequenza seguente:

1. Il nuovo utente accede all'app per la prima volta.
2. L'utente acconsente all'uso dell'app e degli ambiti dell'API Graph nell'interfaccia utente del consenso di Azure.
3. L'utente accede a una pagina del componente che richiede i dati dell'API Graph per la prima volta.
4. Vengono restituiti i dati utente dell'API Graph.

Quando si esegue il test con l'API Graph in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.

Personalizzare le attestazioni utente usando un nome HttpClient

Nell'esempio seguente l'app crea le attestazioni relative al numero di telefono cellulare e alla posizione dell'ufficio per l'utente dai dati del profilo utente ME-ID. L'app deve avere l'ambito dell'API User.Read Graph configurato in ME-ID. Gli account utente di test in ME-ID richiedono una voce per il numero di telefono cellulare e la posizione dell'ufficio, che possono essere aggiunti tramite il portale di Azure ai propri profili utente.

Se non è già stata aggiunta la UserInfo classe all'app seguendo le indicazioni riportate in precedenza in questo articolo, aggiungere la classe seguente e designare le proprietà del profilo utente necessarie con l'attributo JsonPropertyNameAttribute e il nome JSON usato da ME-ID. Nell'esempio seguente vengono impostate le proprietà per il numero di telefono cellulare e la posizione dell'ufficio dell'utente.

UserInfo.cs:

using System.Text.Json.Serialization;

namespace BlazorSample;

public class UserInfo
{
    [JsonPropertyName("mobilePhone")]
    public string? MobilePhone { get; set; }

    [JsonPropertyName("officeLocation")]
    public string? OfficeLocation { get; set; }
}

Nella factory dell'account utente personalizzata seguente:

• Un ILogger oggetto (logger) è incluso per praticità nel caso in cui si desideri registrare informazioni o errori nel CreateUserAsync metodo .
• Nel caso in cui venga generata un'eccezione AccessTokenNotAvailableException , l'utente viene reindirizzato al identity provider per accedere al proprio account. È possibile eseguire azioni aggiuntive o diverse quando la richiesta di un token di accesso non riesce. Ad esempio, l'app può registrare AccessTokenNotAvailableException e creare un ticket di supporto per ulteriori indagini.
• Il framework rappresenta l'account RemoteUserAccount dell'utente. Se l'app richiede una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata per RemoteUserAccount nel codice seguente.

CustomAccountFactory.cs:

using System.Net.Http.Json;
using System.Security.Claims;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using Microsoft.AspNetCore.Components.WebAssembly.Authentication.Internal;

public class CustomAccountFactory(IAccessTokenProviderAccessor accessor,
        IHttpClientFactory clientFactory,
        ILogger<CustomAccountFactory> logger)
    : AccountClaimsPrincipalFactory<RemoteUserAccount>(accessor)
{
    private readonly ILogger<CustomAccountFactory> logger = logger;
    private readonly IHttpClientFactory clientFactory = clientFactory;

    public override async ValueTask<ClaimsPrincipal> CreateUserAsync(
        RemoteUserAccount account,
        RemoteAuthenticationUserOptions options)
    {
        var initialUser = await base.CreateUserAsync(account, options);

        if (initialUser.Identity is not null && 
            initialUser.Identity.IsAuthenticated)
        {
            var userIdentity = initialUser.Identity as ClaimsIdentity;

            if (userIdentity is not null)
            {
                try
                {
                    var client = clientFactory.CreateClient("GraphAPI");

                    var userInfo = await client.GetFromJsonAsync<UserInfo>("me");

                    if (userInfo is not null)
                    {
                        userIdentity.AddClaim(new Claim("mobilephone",
                            userInfo.MobilePhone ?? "(000) 000-0000"));
                        userIdentity.AddClaim(new Claim("officelocation",
                            userInfo.OfficeLocation ?? "Not set"));
                    }
                }
                catch (AccessTokenNotAvailableException exception)
                {
                    exception.Redirect();
                }
            }
        }

        return initialUser;
    }
}

L'autenticazione MSAL è configurata per l'uso della factory dell'account utente personalizzata. Per iniziare, verificare che il Program file usi lo Microsoft.AspNetCore.Components.WebAssembly.Authentication spazio dei nomi :

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;

Program Nel file trovare la chiamata al AddMsalAuthentication metodo di estensione. Aggiornare il codice al codice seguente, che include una chiamata a AddAccountClaimsPrincipalFactory che aggiunge una factory dell'entità attestazioni dell'account con .CustomAccountFactory

Se l'app usa una classe di account utente personalizzata che estende RemoteUserAccount, scambiare la classe di account utente personalizzata dell'app per RemoteUserAccount nel codice seguente.

builder.Services.AddMsalAuthentication<RemoteAuthenticationState, 
    RemoteUserAccount>(options =>
    {
        builder.Configuration.Bind("AzureAd", 
            options.ProviderOptions.Authentication);
    })
    .AddAccountClaimsPrincipalFactory<RemoteAuthenticationState, RemoteUserAccount, 
        CustomAccountFactory>();

L'esempio precedente è relativo a un'app che usa l'autenticazione ME-ID con MSAL. Esistono modelli simili per l'autenticazione OIDC e API. Per altre informazioni, vedere gli esempi nella sezione Personalizzare l'utente con un'attestazione di payload dell'articolo scenari di sicurezza aggiuntivi di ASP.NET CoreBlazor WebAssembly.

È possibile usare il componente seguente UserClaims per studiare le attestazioni dell'utente dopo l'autenticazione dell'utente con ME-ID:

UserClaims.razor:

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

<h1>User Claims</h1>

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

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

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthenticationStateProvider
            .GetAuthenticationStateAsync();
        var user = authState.User;

        claims = user.Claims;
    }
}

Aggiungere un collegamento alla pagina del componente nel NavMenu componente (Layout/NavMenu.razor):

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user-claims">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User Claims
    </NavLink>
</div>

Quando si esegue il test con l'API Graph in locale, è consigliabile usare una nuova sessione del browser InPrivate/incognito per ogni test per impedire che i cookie persistenti interferiscano con i test. Per altre informazioni, vedere Proteggere un'app autonoma di ASP.NET Core Blazor WebAssembly con Microsoft Entra ID.