Guida introduttiva: Accedere agli utenti e chiamare Microsoft Graph in un'app desktop di Windows - Microsoft identity platform

Articolo
10/24/2023

In questa guida introduttiva si scarica ed esegue un esempio di codice che illustra come un'applicazione Windows Presentation Foundation (WPF) può accedere agli utenti e ottenere un token di accesso per chiamare l'API Microsoft Graph. L'app desktop compilata usa il flusso del codice di autorizzazione associato allo standard PKCE (Proof Key for Code Exchange).

Per un'illustrazione, vedere Funzionamento dell'esempio.

Prerequisiti

Visual Studio con il carico di lavoro di sviluppo piattaforma UWP (Universal Windows Platform) installato

Registrare e scaricare l'app della guida introduttiva

Per avviare l'applicazione della guida introduttiva sono disponibili due opzioni:

[Rapida] Opzione 1: Registrare e configurare automaticamente l'app e quindi scaricare l'esempio di codice
[Manuale] Opzione 2: Registrare e configurare manualmente l'applicazione e il codice di esempio

Opzione 1: Registrare e configurare automaticamente l'app e quindi scaricare l'esempio di codice

Passare all'interfaccia di amministrazione di Microsoft Entra - Registrazioni app quickstart.
Immettere un nome per l'applicazione e fare clic su Registra.
Seguire le istruzioni per scaricare e configurare automaticamente la nuova applicazione con un clic.

Opzione 2: Registrare e configurare manualmente l'applicazione e il codice di esempio

Passaggio 1: Registrare l'applicazione

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

Per registrare l'applicazione e aggiungere manualmente le informazioni di registrazione dell'app alla soluzione, seguire questa procedura:

Accedi all'Interfaccia di amministrazione di Microsoft Entra.
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.
Passare a Applicazioni> di identità>Registrazioni app, selezionare Nuova registrazione.
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.
Nella sezione Tipi di account supportati selezionare Account in qualsiasi directory organizzativa e account Microsoft personali (ad esempio Skype, Xbox, Outlook.com).
Selezionare Registra per creare l'applicazione.
In Gestisci selezionare Autenticazione.
Selezionare Aggiungi una piattaforma>Applicazioni per dispositivi mobili e desktop.
Nella sezione URI di reindirizzamento selezionare https://login.microsoftonline.com/common/oauth2/nativeclient e in URI di reindirizzamento personalizzati aggiungere ms-appx-web://microsoft.aad.brokerplugin/{client_id} dove {client_id} è l'ID applicazione (client) dell'applicazione (lo stesso GUID visualizzato nella msal{client_id}://auth casella di controllo).
Seleziona Configura.

Passaggio 2: Scaricare il progetto

Scaricare l'applicazione di esempio WPF

Suggerimento

Per evitare errori causati da limitazioni di lunghezza del percorso in Windows, è consigliabile estrarre l'archivio o clonare il repository in una directory vicina alla radice dell'unità.

Passaggio 3: Configurare il progetto

Estrarre il file ZIP in una cartella locale vicina alla radice del disco, ad esempio C:\Azure-Samples.
Aprire il progetto in Visual Studio.

Modificare App.Xaml.cs e sostituire i valori dei campi ClientId e Tenant con il codice seguente:

private static string ClientId = "Enter_the_Application_Id_here";
private static string Tenant = "Enter_the_Tenant_Info_Here";

Dove:

Enter_the_Application_Id_here è l'ID applicazione (client) per l'applicazione registrata.

Per trovare il valore dell'ID applicazione (client), passare alla pagina Panoramica dell'app nell'interfaccia di amministrazione di Microsoft Entra.
Enter_the_Tenant_Info_Here è impostato su una delle opzioni seguenti:
- Se l'applicazione supporta Account solo in questa directory organizzativa, sostituire questo valore con l'ID tenant o il nome del tenant (ad esempio, contoso.microsoft.com)
- Se l'applicazione supporta Account in qualsiasi directory organizzativa, sostituire questo valore con organizations
- Se l'applicazione supporta Account in qualsiasi directory organizzativa e account Microsoft personali, sostituire questo valore con common.
  
  Per trovare i valori di ID directory (tenant) e Tipi di account supportati, passare alla pagina Panoramica dell'app nell'interfaccia di amministrazione di Microsoft Entra.

Passaggio 4: Eseguire l'applicazione

Per compilare ed eseguire l'applicazione di esempio in Visual Studio, selezionare il menu>Debug Avvia debug oppure premere F5. Viene visualizzata la finestra MainWindow dell'applicazione.

Quando viene visualizzata la finestra principale dell'app, selezionare il pulsante Chiama API Microsoft Graph. Verrà richiesto di accedere usando l'account Microsoft Entra (account aziendale o dell'istituto di istruzione) o l'account Microsoft (live.com, outlook.com).

Se si esegue l'applicazione per la prima volta, verrà richiesto di fornire il consenso per consentire all'applicazione di accedere al profilo utente e accedere. Dopo aver fornito il consenso alle autorizzazioni richieste, l'applicazione visualizza che l'accesso è stato eseguito correttamente. Verranno visualizzate alcune informazioni di base sul token e i dati utente ottenuti dalla chiamata all'API Microsoft Graph.

Altre informazioni

Funzionamento dell'esempio

Diagram showing how the sample app generated by this quickstart works.

MSAL.NET

MSAL (Microsoft.Identity.Client) è la libreria usata per concedere l'accesso agli utenti e richiedere i token usati per accedere a un'API protetta da Microsoft Identity Platform. È possibile installare MSAL eseguendo questo comando in Console di Gestione pacchetti in Visual Studio:

Install-Package Microsoft.Identity.Client -IncludePrerelease

Inizializzazione della libreria MSAL

È possibile aggiungere il riferimento per la libreria MSAL aggiungendo il codice seguente:

using Microsoft.Identity.Client;

Inizializzare quindi la libreria MSAL usando il codice seguente:

IPublicClientApplication publicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();

Dove:	Descrizione
`ClientId`	ID applicazione (client) per l'applicazione registrata nell'interfaccia di amministrazione di Microsoft Entra. È possibile trovare questo valore nella pagina Panoramica dell'app nell'interfaccia di amministrazione di Microsoft Entra.

Richiesta di token

In MSAL sono disponibili due metodi per acquisire i token: AcquireTokenInteractive e AcquireTokenSilent.

Ottenere un token utente in modo interattivo

Alcune situazioni richiedono l'uso forzato dell'interazione degli utenti con Microsoft Identity Platform tramite una finestra popup per convalidare le proprie credenziali o per fornire il consenso. Alcuni esempi includono:

La prima volta che gli utenti accedono all'applicazione
Quando gli utenti devono immettere nuovamente le credenziali perché la password è scaduta
Quando l'applicazione richiede l'accesso a una risorsa per cui è necessario il consenso dell'utente
Quando è necessaria l'autenticazione a due fattori

authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();

Dove:	Descrizione
`_scopes`	Contiene gli ambiti richiesti, ad esempio `{ "user.read" }` per Microsoft Graph o `{ "api://<Application ID>/access_as_user" }` per le API Web personalizzate.

Ottenere un token utente in modo automatico

Non si desidera richiedere all'utente di convalidare le proprie credenziali ogni volta che deve accedere a una risorsa. La maggior parte delle volte si desidera che le acquisizioni e i rinnovi dei token avvengano senza alcuna interazione da parte dell'utente. È possibile usare il metodo AcquireTokenSilent per ottenere i token per accedere alle risorse protette dopo il metodo AcquireTokenInteractive iniziale:

var accounts = await app.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();

Dove:	Descrizione
`scopes`	Contiene gli ambiti richiesti, ad esempio `{ "user.read" }` per Microsoft Graph o `{ "api://<Application ID>/access_as_user" }` per le API Web personalizzate.
`firstAccount`	Specifica il primo utente nella cache (MSAL supporta più utenti in una singola app).

Assistenza e supporto

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

Passaggi successivi

Provare l'esercitazione di Windows Desktop per una guida dettagliata completa sulla creazione di applicazioni e di nuove funzionalità, tra cui una spiegazione completa di questa guida introduttiva.

Esercitazione sulla chiamata dell'API Graph

Condividi tramite