Integrare Azure AD in un'app WPF desktop di WindowsIntegrate Azure AD into a Windows Desktop WPF App

Nota

Questo articolo fa parte della Guida per gli sviluppatori di Azure Active Directory.This article is part of the Azure Active Directory developer's guide.

Se si sta sviluppando un'applicazione desktop, Azure AD semplifica e facilita l'autenticazione degli utenti con gli account Active Directory.If you're developing a desktop application, Azure AD makes it simple and straightforward for you to authenticate your users with their Active Directory accounts. Consente inoltre all'applicazione di usare in modo sicuro qualsiasi API Web protetta da Azure AD, ad esempio le API di Office 365 o l'API di Azure.It also enables your application to securely consume any web API protected by Azure AD, such as the Office 365 APIs or the Azure API.

Per i client nativi .NET che devono accedere a risorse protette, Azure AD fornisce Active Directory Authentication Library (ADAL).For .NET native clients that need to access protected resources, Azure AD provides the Active Directory Authentication Library, or ADAL. La funzione di ADAL è di permettere all'app di ottenere facilmente i token di accesso.ADAL's sole purpose in life is to make it easy for your app to get access tokens. Per far capire quanto è semplice, verrà compilata un'applicazione WPF .NET To-Do List che:To demonstrate just how easy it is, here we'll build a .NET WPF To-Do List application that:

  • Ottiene i token di accesso per la chiamata all'API Graph di Azure AD con il protocollo di autenticazione OAuth 2.0.Gets access tokens for calling the Azure AD Graph API using the OAuth 2.0 authentication protocol.
  • Cerca in una directory gli utenti con un determinato alias.Searches a directory for users with a given alias.
  • Disconnette gli utenti.Signs users out.

Per compilare l'applicazione funzionante completa, sarà necessario:To build the complete working application, you'll need to:

  1. Registrare l'applicazione con Azure AD.Register your application with Azure AD.
  2. Installare e configurare ADAL.Install & Configure ADAL.
  3. Usare ADAL per ottenere i token da Azure AD.Use ADAL to get tokens from Azure AD.

Per iniziare, scaricare la struttura dell'app o scaricare l'esempio completato.To get started, download the app skeleton or download the completed sample. Sarà necessario anche un tenant di Azure AD in cui poter creare gli utenti e registrare un'applicazione.You'll also need an Azure AD tenant in which you can create users and register an application. Se non si ha già un tenant, vedere le informazioni su come ottenerne uno.If you don't already have a tenant, learn how to get one.

1. Registrare l'applicazione DirectorySearcher1. Register the DirectorySearcher Application

Per consentire all'applicazione di ottenere i token, sarà innanzitutto necessario registrarla nel tenant di Azure AD e concederle l'autorizzazione per accedere all'API Graph di Azure AD:To enable your app to get tokens, you'll first need to register it in your Azure AD tenant and grant it permission to access the Azure AD Graph API:

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Nella barra in alto fare clic sull'account e nell'elenco Directory scegliere il tenant di Active Directory in cui si vuole registrare l'applicazione.On the top bar, click on your account and under the Directory list, choose the Active Directory tenant where you wish to register your application.
  3. Fare clic su Altri servizi nella barra di spostamento a sinistra e scegliere Azure Active Directory.Click on More Services in the left hand nav, and choose Azure Active Directory.
  4. Fare clic su App registrations (Registrazioni app) e scegliere Aggiungi.Click on App registrations and choose Add.
  5. Seguire le istruzioni e creare una nuova Applicazione client nativa.Follow the prompts and create a new Native Client Application.
    • Il Nome dell'applicazione deve essere una descrizione per gli utenti finali.The Name of the application will describe your application to end-users
    • L' URI di reindirizzamento è una combinazione dello schema e della stringa che Azure AD userà per restituire le risposte dei token.The Redirect Uri is a scheme and string combination that Azure AD will use to return token responses. Immettere un valore specifico per l'applicazione, ad esempio http://DirectorySearcher.Enter a value specific to your application, e.g. http://DirectorySearcher.
  6. Dopo avere completato la registrazione, AAD assegnerà all'app un'ID app univoca.Once you've completed registration, AAD will assign your app a unique Application ID. Poiché questo valore sarà necessario nelle sezioni successive, copiarlo dalla pagina dell'applicazione.You'll need this value in the next sections, so copy it from the application page.
  7. Nella pagina Impostazioni scegliere Autorizzazioni necessarie e quindi scegliere Aggiungi.From the Settings page, choose Required Permissions and choose Add. Selezionare Microsoft Graph come API e aggiungere l'autorizzazione Lettura dati directory in Autorizzazioni delegate.Select the Microsoft Graph as the API and add the Read Directory Data permission under Delegated Permissions. In questo modo l'applicazione potrà cercare gli utenti nell'API Graph.This will enable your application to query the Graph API for users.

2. Installare e configurare ADAL2. Install & Configure ADAL

Ora che si dispone di un'applicazione in Azure AD, è possibile installare ADAL e scrivere il codice relativo all'identità.Now that you have an application in Azure AD, you can install ADAL and write your identity-related code. Affinché la libreria ADAL possa comunicare con Azure AD, è necessario fornire alcune informazioni relative alla registrazione dell'app.In order for ADAL to be able to communicate with Azure AD, you need to provide it with some information about your app registration.

  • Per prima cosa aggiungere ADAL al progetto DirectorySearcher usando la console di Gestione pacchetti.Begin by adding ADAL to the DirectorySearcher project using the Package Manager Console.
PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory
  • Nel progetto DirectorySearcher aprire app.config.In the DirectorySearcher project, open app.config. Sostituire i valori degli elementi nella sezione <appSettings> in modo che corrispondano ai valori inseriti nel portale di Azure.Replace the values of the elements in the <appSettings> section to reflect the values you input into the Azure Portal. Il codice farà riferimento a questi valori ogni volta che userà ADAL.Your code will reference these values whenever it uses ADAL.
    • ida:Tenant è il dominio del tenant di Azure AD, ad esempio, contoso.onmicrosoft.com.The ida:Tenant is the domain of your Azure AD tenant, e.g. contoso.onmicrosoft.com
    • ida:ClientId è l'ID client dell'applicazione copiato dal portale.The ida:ClientId is the clientId of your application you copied from the portal.
    • ida:RedirectUri è l'URL di reindirizzamento registrato nel portale.The ida:RedirectUri is the redirect url you registered in the portal.

3. Usare ADAL per ottenere i token da AAD3. Use ADAL to Get Tokens from AAD

Il principio alla base di ADAL è che l'app, ogni volta che ha bisogno di un token di accesso, deve solo chiamare authContext.AcquireTokenAsync(...) e ADAL fa il resto.The basic principle behind ADAL is that whenever your app needs an access token, it simply calls authContext.AcquireTokenAsync(...), and ADAL does the rest.

  • Nel progetto DirectorySearcher aprire MainWindow.xaml.cs e individuare il metodo MainWindow().In the DirectorySearcher project, open MainWindow.xaml.cs and locate the MainWindow() method. Il primo passaggio consiste nell'inizializzare l'oggetto AuthenticationContext dell'app, ovvero la classe primaria di ADAL,The first step is to initialize your app's AuthenticationContext - ADAL's primary class. dove si passano ad ADAL le coordinate di cui ha bisogno per comunicare con Azure AD e gli si indica come memorizzare i token nella cache.This is where you pass ADAL the coordinates it needs to communicate with Azure AD and tell it how to cache tokens.
public MainWindow()
{
    InitializeComponent();

    authContext = new AuthenticationContext(authority, new FileCache());

    CheckForCachedToken();
}
  • Individuare ora il metodo Search(...), che verrà richiamato quando l'utente fa clic sul pulsante "Search" nell'interfaccia utente dell'app.Now locate the Search(...) method, which will be invoked when the user cliks the "Search" button in the app's UI. Questo metodo invia una richiesta GET all'API Graph di Azure AD per eseguire una query sugli utenti il cui UPN inizia con il termine di ricerca specificato.This method makes a GET request to the Azure AD Graph API to query for users whose UPN begins with the given search term. Per eseguire una query nell'API Graph, è però necessario includere un oggetto access_token nell'intestazione Authorization della richiesta, dove entra in gioco ADAL.But in order to query the Graph API, you need to include an access_token in the Authorization header of the request - this is where ADAL comes in.
private async void Search(object sender, RoutedEventArgs e)
{
    // Validate the Input String
    if (string.IsNullOrEmpty(SearchText.Text))
    {
        MessageBox.Show("Please enter a value for the To Do item name");
        return;
    }

    // Get an Access Token for the Graph API
    AuthenticationResult result = null;
    try
    {
        result = await authContext.AcquireTokenAsync(graphResourceId, clientId, redirectUri, new PlatformParameters(PromptBehavior.Auto));
        UserNameLabel.Content = result.UserInfo.DisplayableId;
        SignOutButton.Visibility = Visibility.Visible;
    }
    catch (AdalException ex)
    {
        // An unexpected error occurred, or user canceled the sign in.
        if (ex.ErrorCode != "access_denied")
            MessageBox.Show(ex.Message);

        return;
    }

    ...
}
  • Quando l'app richiede un token chiamando AcquireTokenAsync(...), ADAL tenterà di restituire un token senza chiedere le credenziali all'utente.When your app requests a token by calling AcquireTokenAsync(...), ADAL will attempt to return a token without asking the user for credentials. Se ADAL determina che l'utente deve effettuare l'accesso per ottenere un token, visualizzerà una finestra di dialogo di accesso, raccoglierà le credenziali dell'utente e restituirà un token al termine dell'autenticazione.If ADAL determines that the user needs to sign in to get a token, it will display a login dialog, collect the user's credentials, and return a token upon successful authentication. Se ADAL non può restituire un token per qualsiasi motivo, genera una AdalException.If ADAL is unable to return a token for any reason, it will throw an AdalException.
  • Si noti che l'oggetto AuthenticationResult contiene un oggetto UserInfo che può essere usato per raccogliere informazioni che potrebbero essere richieste dall'app.Notice that the AuthenticationResult object contains a UserInfo object that can be used to collect information your app may need. In DirectorySearcher UserInfo viene usato per personalizzare l'interfaccia utente dell'app con l'ID dell'utente.In the DirectorySearcher, UserInfo is used to customize the app's UI with the user's id.
  • È opportuno assicurarsi che, quando l'utente fa clic sul pulsante "Sign Out", la chiamata successiva a AcquireTokenAsync(...) chiederà all'utente di accedere.When the user clicks the "Sign Out" button, we want to ensure that the next call to AcquireTokenAsync(...) will ask the user to sign in. Con ADAL, basta cancellare la cache dei token:With ADAL, this is as easy as clearing the token cache:
private void SignOut(object sender = null, RoutedEventArgs args = null)
{
    // Clear the token cache
    authContext.TokenCache.Clear();

    ...
}
  • Se tuttavia l'utente non fa clic sul pulsante di "disconnessione", è consigliabile mantenere la sessione dell'utente per la prossima esecuzione di DirectorySearcher.However, if the user does not click the "Sign Out" button, you will want to maintain the user's session for the next time they run the DirectorySearcher. Quando viene avviata l'app, è possibile cercare nella cache dei token di ADAL se esiste un token e aggiornare di conseguenza l'interfaccia utente.When the app launches, you can check ADAL's token cache for an existing token and update the UI accordingly. Nel metodo CheckForCachedToken(), eseguire un'altra chiamata a AcquireTokenAsync(...), questa volta superando il parametro PromptBehavior.Never.In the CheckForCachedToken() method, make another call to AcquireTokenAsync(...), this time passing in the PromptBehavior.Never parameter. PromptBehavior.Never comunicherà ad ADAL che non dovrà richiedere all'utente di accedere e dovrà invece generare un'eccezione se non è in grado di restituire un token.PromptBehavior.Never will tell ADAL that the user should not be prompted for sign in, and ADAL should instead throw an exception if it is unable to return a token.
public async void CheckForCachedToken() 
{
    // As the application starts, try to get an access token without prompting the user.  If one exists, show the user as signed in.
    AuthenticationResult result = null;
    try
    {
        result = await authContext.AcquireTokenAsync(graphResourceId, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never));
    }
    catch (AdalException ex)
    {
        if (ex.ErrorCode != "user_interaction_required")
        {
            // An unexpected error occurred.
            MessageBox.Show(ex.Message);
        }

        // If user interaction is required, proceed to main page without singing the user in.
        return;
    }

    // A valid token is in the cache
    SignOutButton.Visibility = Visibility.Visible;
    UserNameLabel.Content = result.UserInfo.DisplayableId;
}

Congratulazioni.Congratulations! È stata compilata un'applicazione WPF .NET in grado di autenticare gli utenti, di chiamare in modo sicuro le API Web usando OAuth 2.0 e di ottenere informazioni di base sull'utente.You now have a working .NET WPF application that has the ability to authenticate users, securely call Web APIs using OAuth 2.0, and get basic information about the user. Se non si è ancora popolato il tenant con alcuni utenti, ora è possibile farlo.If you haven't already, now is the time to populate your tenant with some users. Eseguire l'app DirectorySearcher e accedere con uno di tali utenti.Run your DirectorySearcher app, and sign in with one of those users. Cercare altri utenti in base al relativo UPN.Search for other users based on their UPN. Chiudere l'app e rieseguirla.Close the app, and re-run it. Si noti che la sessione dell'utente non è stata modificata.Notice how the user's session remains intact. Disconnettersi e accedere nuovamente come un altro utente.Sign out, and sign back in as another user.

ADAL consente di incorporare facilmente nell'applicazione tutte queste funzionalità comuni relative alle identità.ADAL makes it easy to incorporate all of these common identity features into your application. Esegue automaticamente le attività più complesse: gestione della cache, supporto del protocollo OAuth, presentazione all'utente di un'interfaccia utente di accesso, aggiornamento dei token scaduti e altro.It takes care of all the dirty work for you - cache management, OAuth protocol support, presenting the user with a login UI, refreshing expired tokens, and more. Tutto ciò che occorre conoscere è una sola chiamata all'API, authContext.AcquireTokenAsync(...).All you really need to know is a single API call, authContext.AcquireTokenAsync(...).

Come riferimento, viene fornito l'esempio completato (senza i valori di configurazione) qui.For reference, the completed sample (without your configuration values) is provided here. Ora è possibile passare ad altri scenari.You can now move on to additional scenarios. È possibile:You may want to try:

Proteggere un'API Web .NET con Azure AD >>Secure a .NET Web API with Azure AD >>

Risorse aggiuntiveAdditional resources

Ottenere aggiornamenti della sicurezza per i prodottiGet security updates for our products

È consigliabile ricevere notifiche in caso di problemi di sicurezza. A tale scopo, visitare la pagina del TechCenter per le notifiche sulla sicurezza tecnica per Microsoft e sottoscrivere gli avvisi di sicurezza.We encourage you to get notifications of when security incidents occur by visiting the TechCenter page for Microsoft technical security notifications and subscribing to security advisory alerts.