Esercitazione: Far accedere gli utenti e chiamare Microsoft Graph nell'app desktop Windows Presentation Foundation (WPF)

In questa esercitazione verrà creata un'app Windows Desktop .NET (XAML) nativa che concede l'accesso agli utenti e ottiene un token di accesso per chiamare l'API Microsoft Graph.

Dopo aver completato la guida, l'applicazione sarà in grado di chiamare un'API protetta che usa account personali (inclusi outlook.com, live.com e altri). L'applicazione userà anche gli account aziendali e dell'istituto di istruzione da qualsiasi azienda o organizzazione che usa Microsoft Entra ID.

Contenuto dell'esercitazione:

Prerequisiti

• .NET Framework 4.8
• Visual Studio 2019

Funzionamento dell'app di esempio generata da questa guida

L'applicazione di esempio creata in questa guida consente l’accesso a un'applicazione desktop di Windows che esegue query sull'API Microsoft Graph o su un'API Web che accetta token da un endpoint di Microsoft Identity Platform. Per questo scenario, viene aggiunto un token a richieste HTTP tramite l'intestazione di autorizzazione. L'acquisizione e il rinnovo del token sono gestiti da Microsoft Authentication Library (MSAL).

Gestione dell'acquisizione di token per l'accesso ad API Web protette

Dopo l'autenticazione dell'utente, l'applicazione di esempio riceve un token che può essere usato per eseguire query sull'API Microsoft Graph o su un'API Web protetta da Microsoft Identity Platform.

Le API come Microsoft Graph richiedono un token per consentire l'accesso a specifiche risorse. Ad esempio, è necessario un token per leggere il profilo di un utente, accedere al calendario di un utente o inviare un messaggio di posta elettronica. L'applicazione può richiedere un token di accesso usando MSAL per accedere alle risorse tramite la specifica degli ambiti dell'API. Questo token di accesso viene quindi aggiunto all'intestazione di autorizzazione HTTP per ogni chiamata effettuata per la risorsa protetta.

La memorizzazione nella cache e l'aggiornamento dei token di accesso vengono gestiti da MSAL e non devono quindi essere eseguiti dall'applicazione.

Pacchetti NuGet

Questa guida usa i pacchetti NuGet seguenti:

Impostare il progetto

In questa sezione viene creato un nuovo progetto per illustrare come integrare un'applicazione .NET desktop di Windows (XAML) con l'accesso con Microsoft in modo che l'applicazione possa eseguire query sulle API Web che richiedono un token.

L'applicazione creata visualizza un pulsante che chiamerà l'API Microsoft Graph, un'area per visualizzare i risultati e un pulsante di disconnessione.

Creare l'applicazione seguendo i passaggi seguenti:

1. Aprire Visual Studio.
2. Nella finestra iniziale selezionare Crea un nuovo progetto.
3. Nell'elenco a discesa Tutte le lingue selezionare C#.
4. Ricercare e scegliere il modello App WPF (.NET Framework) e quindi selezionare Avanti.
5. Nella casella Nome progetto immettere un nome come Win-App-calling-MsGraph.
6. Scegliere un percorso per il progetto o accettare l'opzione predefinita.
7. In Framework selezionare .NET Framework 4.8.
8. Seleziona Crea.

Aggiungere MSAL al progetto

1. In Visual Studio, seleziona Strumenti>Gestione pacchetti NuGet>Console di gestione pacchetti.

2. Nella finestra Console di Gestione pacchetti incollare il seguente comando di Azure PowerShell:

   Install-Package Microsoft.Identity.Client -Pre
   

Registrare l'applicazione

Per registrare e configurare l'applicazione, seguire i passaggi seguenti:

1. Accedere all' Interfaccia di amministrazione di Microsoft Entra almeno come Sviluppatore di applicazioni.
2. Se si ha accesso a più tenant, usare l'icona Impostazioni nel menu in alto per passare al tenant in cui si vuole registrare l'applicazione dal menu Directory e sottoscrizioni.
3. Passare a Identità>Applicazioni>Registrazioni app.
4. Seleziona Nuova registrazione.
5. In Nome immettere un nome per l'applicazione, ad esempio Win-App-calling-MsGraph. Tale nome, che potrebbe essere visualizzato dagli utenti dell'app, può essere modificato in un secondo momento.
6. Nella sezione Tipi di account supportati selezionare Account in qualsiasi directory dell'organizzazione (qualsiasi directory di Microsoft Entra - Multi-tenant) e account Microsoft personali (ad esempio, Skype, Xbox).
7. Selezionare Registra.
8. In Gestisci selezionare Autenticazione>Aggiungi una piattaforma.
9. Selezionare Applicazioni per dispositivi mobili e desktop.
10. Nella sezione URI di reindirizzamento selezionare https://login.microsoftonline.com/common/oauth2/nativeclient.
11. Seleziona Configura.

Aggiungere il codice per inizializzare MSAL

Questo passaggio consente di creare una classe per gestire l'interazione con la libreria MSAL, ad esempio per la gestione dei token.

1. Aprire il file App.xaml.cs, quindi aggiungere alla classe il riferimento relativo alla libreria MSAL:

   using Microsoft.Identity.Client;
   

2. Aggiornare la classe App con il codice seguente:

   public partial class App : Application
   {
       static App()
       {
           _clientApp = PublicClientApplicationBuilder.Create(ClientId)
               .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
               .WithDefaultRedirectUri()
               .Build();
       }
   
       // Below are the clientId (Application Id) of your app registration and the tenant information.
       // You have to replace:
       // - the content of ClientID with the Application Id for your app registration
       // - the content of Tenant by the information about the accounts allowed to sign-in in your application:
       //   - For Work or School account in your org, use your tenant ID, or domain
       //   - for any Work or School accounts, use `organizations`
       //   - for any Work or School accounts, or Microsoft personal account, use `common`
       //   - for Microsoft Personal account, use consumers
       private static string ClientId = "Enter_the_Application_Id_here";
   
       private static string Tenant = "common";
   
       private static IPublicClientApplication _clientApp ;
   
       public static IPublicClientApplication PublicClientApp { get { return _clientApp; } }
   }
   

Creare l'interfaccia utente dell'applicazione

Questa sezione illustra come un'applicazione può eseguire una query su un server back-end protetto come Microsoft Graph.

Viene creato automaticamente un file MainWindow.xaml come parte del modello di progetto. Aprire il file e sostituire il nodo <Grid> dell'applicazione con il codice seguente:

<Grid>
    <StackPanel Background="Azure">
        <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">
            <Button x:Name="CallGraphButton" Content="Call Microsoft Graph API" HorizontalAlignment="Right" Padding="5" Click="CallGraphButton_Click" Margin="5" FontFamily="Segoe Ui"/>
            <Button x:Name="SignOutButton" Content="Sign-Out" HorizontalAlignment="Right" Padding="5" Click="SignOutButton_Click" Margin="5" Visibility="Collapsed" FontFamily="Segoe Ui"/>
        </StackPanel>
        <Label Content="API Call Results" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="ResultText" TextWrapping="Wrap" MinHeight="120" Margin="5" FontFamily="Segoe Ui"/>
        <Label Content="Token Info" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="TokenInfoText" TextWrapping="Wrap" MinHeight="70" Margin="5" FontFamily="Segoe Ui"/>
    </StackPanel>
</Grid>

Usare MSAL per ottenere un token per l'API Microsoft Graph

In questa sezione si usa MSAL per ottenere un token per l'API Microsoft Graph.

1. Nel file MainWindow.xaml.cs aggiungere alla classe il riferimento relativo a MSAL:

   using Microsoft.Identity.Client;
   

2. Sostituire il codice della classe MainWindow con il codice seguente:

   public partial class MainWindow : Window
   {
       //Set the API Endpoint to Graph 'me' endpoint
       string graphAPIEndpoint = "https://graph.microsoft.com/v1.0/me";
   
       //Set the scope for API call to user.read
       string[] scopes = new string[] { "user.read" };
   
   
       public MainWindow()
       {
           InitializeComponent();
       }
   
     /// <summary>
       /// Call AcquireToken - to acquire a token requiring user to sign-in
       /// </summary>
       private async void CallGraphButton_Click(object sender, RoutedEventArgs e)
       {
           AuthenticationResult authResult = null;
           var app = App.PublicClientApp;
           ResultText.Text = string.Empty;
           TokenInfoText.Text = string.Empty;
   
           var accounts = await app.GetAccountsAsync();
           var firstAccount = accounts.FirstOrDefault();
   
           try
           {
               authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                   .ExecuteAsync();
           }
           catch (MsalUiRequiredException ex)
           {
               // A MsalUiRequiredException happened on AcquireTokenSilent.
               // This indicates you need to call AcquireTokenInteractive to acquire a token
               System.Diagnostics.Debug.WriteLine($"MsalUiRequiredException: {ex.Message}");
   
               try
               {
                   authResult = await app.AcquireTokenInteractive(scopes)
                       .WithAccount(accounts.FirstOrDefault())
                       .WithPrompt(Prompt.SelectAccount)
                       .ExecuteAsync();
               }
               catch (MsalException msalex)
               {
                   ResultText.Text = $"Error Acquiring Token:{System.Environment.NewLine}{msalex}";
               }
           }
           catch (Exception ex)
           {
               ResultText.Text = $"Error Acquiring Token Silently:{System.Environment.NewLine}{ex}";
               return;
           }
   
           if (authResult != null)
           {
               ResultText.Text = await GetHttpContentWithToken(graphAPIEndpoint, authResult.AccessToken);
               DisplayBasicTokenInfo(authResult);
               this.SignOutButton.Visibility = Visibility.Visible;
           }
       }
       }
   

Ulteriori informazioni

Ottenere un token utente in modo interattivo

Se si chiama il metodo AcquireTokenInteractive, viene visualizzata una finestra in cui viene chiesto agli utenti di eseguire l'accesso. Le applicazioni in genere richiedono agli utenti di eseguire l'accesso in modo interattivo quando devono accedere per la prima volta a una risorsa protetta. Potrebbe essere necessario eseguire l'accesso anche quando un'operazione invisibile per l'acquisizione di un token ha esito negativo (ad esempio quando la password di un utente è scaduta).

Ottenere un token utente in modo automatico

Il metodo AcquireTokenSilent gestisce le acquisizioni e i rinnovi dei token senza alcuna interazione da parte dell'utente. Dopo la prima esecuzione di AcquireTokenInteractive, per le chiamate successive il metodo generalmente usato per ottenere i token per accedere alle risorse protette è AcquireTokenSilent, perché le chiamate per richiedere o rinnovare i token vengono effettuate in modo invisibile all'utente.

Alla fine il metodo AcquireTokenSilent può avere esito negativo. ad esempio perché l'utente ha effettuato la disconnessione o ha modificato la propria password su un altro dispositivo. Se MSAL rileva che il problema può essere risolto richiedendo un'azione interattiva, viene attivata un'eccezione MsalUiRequiredException. L'applicazione può gestire questa eccezione in due modi:

• Può eseguire immediatamente una chiamata a AcquireTokenInteractive e richiedere così all'utente di eseguire l'accesso. Questo modello viene usato nelle applicazioni online in cui non è disponibile contenuto offline per l'utente. L'esempio generato in questa configurazione segue questo modello e può essere visto in azione la prima volta che si esegue l'esempio.

• Dato che nessun utente ha usato l'applicazione, PublicClientApp.Users.FirstOrDefault() contiene un valore Null e viene generata un'eccezione MsalUiRequiredException.

• Il codice dell'esempio gestisce quindi l'eccezione chiamando AcquireTokenInteractive e richiedendo così all'utente di eseguire l'eccesso.

• Può presentare un'indicazione visiva per informare gli utenti che è necessario un accesso interattivo e consentire così di scegliere il momento opportuno per accedere. In alternativa, l'applicazione può riprovare a eseguire AcquireTokenSilent in un secondo momento. Questo modello viene spesso usato quando gli utenti possono usare altre funzionalità dell'applicazione senza interruzioni. Ad esempio quando il contenuto offline è disponibile nell'applicazione. In questo caso, gli utenti possono decidere se vogliono eseguire l'accesso per accedere alla risorsa protetta oppure aggiornare le informazioni obsolete. In alternativa, l'applicazione può decidere di riprovare a eseguire AcquireTokenSilent quando la rete viene ripristinata dopo essere stata temporaneamente non disponibile.

Chiamare l'API Microsoft Graph usando il token appena ottenuto

Aggiungere il nuovo metodo seguente al file MainWindow.xaml.cs. Questo metodo consente di eseguire una richiesta GET all'API Graph usando un'intestazione Authorize:

/// <summary>
/// Perform an HTTP GET request to a URL using an HTTP Authorization header
/// </summary>
/// <param name="url">The URL</param>
/// <param name="token">The token</param>
/// <returns>String containing the results of the GET operation</returns>
public async Task<string> GetHttpContentWithToken(string url, string token)
{
    var httpClient = new System.Net.Http.HttpClient();
    System.Net.Http.HttpResponseMessage response;
    try
    {
        var request = new System.Net.Http.HttpRequestMessage(System.Net.Http.HttpMethod.Get, url);
        //Add the token in Authorization header
        request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        response = await httpClient.SendAsync(request);
        var content = await response.Content.ReadAsStringAsync();
        return content;
    }
    catch (Exception ex)
    {
        return ex.ToString();
    }
}

Altre informazioni sull'esecuzione di una chiamata REST a un'API protetta

In questa applicazione di esempio viene usato il metodo GetHttpContentWithToken per eseguire una richiesta HTTP GET a una risorsa protetta che richiede un token e restituire il contenuto al chiamante. Questo metodo aggiunge il token acquisito nell'intestazione di autorizzazione HTTP. Per questo esempio, la risorsa è l'endpoint me dell'API Microsoft Graph, che visualizza le informazioni del profilo dell'utente.

Aggiungere un metodo per disconnettere un utente

Per disconnettere un utente, aggiungere il metodo seguente al file MainWindow.xaml.cs:

/// <summary>
/// Sign out the current user
/// </summary>
private async void SignOutButton_Click(object sender, RoutedEventArgs e)
{
    var accounts = await App.PublicClientApp.GetAccountsAsync();

    if (accounts.Any())
    {
        try
        {
            await App.PublicClientApp.RemoveAsync(accounts.FirstOrDefault());
            this.ResultText.Text = "User has signed-out";
            this.CallGraphButton.Visibility = Visibility.Visible;
            this.SignOutButton.Visibility = Visibility.Collapsed;
        }
        catch (MsalException ex)
        {
            ResultText.Text = $"Error signing-out user: {ex.Message}";
        }
    }
}

Altre informazioni sulla disconnessione degli utenti

Il metodo SignOutButton_Click rimuove gli utenti dalla cache utente di MSAL. In questo modo MSAL dimentica l'utente corrente e una futura richiesta di acquisizione di un token potrà avere esito positivo solo se eseguita in modo interattivo.

Nonostante l'applicazione in questo esempio supporti singoli utenti, MSAL supporta anche scenari con accesso contemporaneo di più account, ad esempio un'applicazione di posta elettronica in cui un utente ha più account.

Visualizzare informazioni di base sui token

Per visualizzare informazioni di base sui token, aggiungere il metodo seguente al file MainWindow.xaml.cs:

/// <summary>
/// Display basic information contained in the token
/// </summary>
private void DisplayBasicTokenInfo(AuthenticationResult authResult)
{
    TokenInfoText.Text = "";
    if (authResult != null)
    {
        TokenInfoText.Text += $"Username: {authResult.Account.Username}" + Environment.NewLine;
        TokenInfoText.Text += $"Token Expires: {authResult.ExpiresOn.ToLocalTime()}" + Environment.NewLine;
    }
}

Ulteriori informazioni

Oltre al token di accesso che viene usato per chiamare l'API Microsoft Graph, dopo l'accesso dell'utente, MSAL ottiene anche un token ID. Questo token contiene un piccolo subset di informazioni relative agli utenti. Il metodo DisplayBasicTokenInfo visualizza le informazioni di base contenute nel token. Ad esempio, visualizza l'ID e il nome visualizzato dell'utente, la data di scadenza del token e la stringa che rappresenta il token di accesso. Premendo più volte il pulsante Call Microsoft Graph API (Chiama API Microsoft Graph), è possibile vedere che lo stesso token è stato usato per più richieste successive. Se MSAL decide che è il momento di rinnovare il token, è possibile anche vedere la data di scadenza estesa.

Eseguire test del codice

Per eseguire il progetto, in Visual Studio selezionare F5. Viene visualizzata l'applicazione MainWindow .

Alla prima esecuzione dell'applicazione, quando si seleziona il pulsante Call Microsoft Graph API (Chiama API Microsoft Graph), viene richiesto l'accesso. Usare un account Microsoft Entra (aziendale o dell'istituto di istruzione) o un account Microsoft (live.com, outlook.com) per eseguire il test.

Specificare il consenso per l'accesso all'applicazione

Al primo accesso all'applicazione viene richiesto anche di specificare il consenso per permettere all'applicazione di accedere al profilo e di completare l'accesso per l'utente, come mostrato di seguito:

Visualizzare i risultati dell'applicazione

Dopo l'accesso dovrebbero essere visualizzate le informazioni sul profilo utente restituite dalla chiamata all'API Microsoft Graph . I risultati vengono visualizzati nella casella API Call Results (Risultati della chiamata API). Le informazioni di base sul token acquisito tramite la chiamata a AcquireTokenInteractive o AcquireTokenSilent dovrebbero essere visibili nella casella Token Info (Info sul token). I risultati contengono le proprietà seguenti:

Altre informazioni sugli ambiti e sulle autorizzazioni delegate

L'API Microsoft Graph richiede l'ambito user.read per leggere il profilo dell'utente. Per impostazione predefinita, questo ambito viene aggiunto automaticamente in ogni applicazione registrata nel portale di registrazione dell'applicazione. Altre API per Microsoft Graph e le API personalizzate per il server back-end possono richiedere anche altri ambiti. L'API Microsoft Graph richiede l'ambito Calendars.Read per elencare i calendari dell'utente.

Per accedere ai calendari dell'utente nel contesto di un'applicazione, aggiungere l'autorizzazione delegata Calendars.Read alle informazioni di registrazione dell'applicazione. Aggiungere quindi l'ambito Calendars.Read alla chiamata acquireTokenSilent.

Assistenza e supporto

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

Passaggio successivo

Altre informazioni sulla creazione di app desktop che chiamano API Web protette nella serie di scenari in più parti: