Integrare Azure AD con le app di Windows StoreIntegrate Azure AD with Windows Store apps

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.

Nota

I progetti di Windows Store 8.1 e della versione precedente non sono supportati in Visual Studio 2017.Windows Store 8.1 and prior version projects are not supported in Visual Studio 2017. Per altre informazioni, vedere Selezione della piattaforma e compatibilità di Visual Studio 2017.For more information, see Visual Studio 2017 Platform Targeting and Compatibility.

Quando si sviluppano app per Windows Store, Azure Active Directory (Azure AD) semplifica e facilita l'autenticazione degli utenti con gli account Active Directory.If you're developing apps for the Windows Store, Azure Active Directory (Azure AD) makes it simple and straightforward to authenticate your users with their Active Directory accounts. Grazie all'integrazione con Azure AD, un'app può usare in modo sicuro qualsiasi API Web protetta da Azure AD, quali ad esempio le API di Office 365 o l'API di Azure.By integrating with Azure AD, an app can securely consume any web API that's protected by Azure AD, such as the Office 365 APIs or the Azure API.

Per le app desktop di Windows Store che devono accedere a risorse protette, Azure AD offre Active Directory Authentication Library (ADAL).For Windows Store desktop apps that need to access protected resources, Azure AD provides the Active Directory Authentication Library (ADAL). L'unica funzione di ADAL è di semplificare l'acquisizione dei token di accesso da parte delle app.The sole purpose of ADAL is to make it easy for the app to get access tokens. Per far capire quanto sia semplice, questo articolo illustra come compilare un'app di Windows Store denominata DirectorySearcher che:To demonstrate how easy it is, this article shows how to build a DirectorySearcher Windows Store app that:

  • Ottiene i token di accesso per chiamare l'API Graph di Azure AD con il protocollo di autenticazione OAuth 2.0.Gets access tokens for calling the Azure AD Graph API by using the OAuth 2.0 authentication protocol.
  • Cerca in una directory gli utenti con un determinato nome dell'entità utente (UPN).Searches a directory for users with a given user principal name (UPN).
  • Disconnette gli utenti.Signs users out.

Prima di iniziareBefore you get started

Quando si è pronti, attenersi alle procedure descritte nelle tre sezioni seguenti.When you are ready, follow the procedures in the next three sections.

Passaggio 1. Registrare l'app DirectorySearcherStep 1: Register the DirectorySearcher app

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

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Nella barra superiore fare clic sull'account.On the top bar, click your account. Nell'elenco Directory selezionare quindi il tenant di Active Directory in cui si vuole registrare l'app.Then, under the Directory list, select the Active Directory tenant where you want to register the app.
  3. Fare clic su Altri servizi nel riquadro a sinistra e scegliere Azure Active Directory.Click More Services in the left pane, and then select Azure Active Directory.
  4. Fare clic su Registrazioni per l'app e scegliere Aggiungi.Click App registrations, and then select Add.
  5. Seguire le istruzioni per creare un'Applicazione client nativa.Follow the prompts to create a Native Client Application.
    • Il nome descrive l'app agli utenti.Name describes the app to users.
    • L'URI di reindirizzamento è una combinazione dello schema e della stringa che Azure AD usa per restituire le risposte dei token.Redirect URI is a scheme and string combination that Azure AD uses to return token responses. Immettere per ora un valore segnaposto, ad esempio http://DirectorySearcher.Enter a placeholder value for now (for example, http://DirectorySearcher). Si sostituirà il valore in un secondo momento.You'll replace the value later.
  6. Dopo aver completato la registrazione, Azure AD assegna automaticamente all'app un ID applicazione univoco.After you’ve completed the registration, Azure AD assigns the app a unique application ID. Copiare il valore nella scheda Applicazione, poiché sarà necessario in un secondo momento.Copy the value on the Application tab, because you'll need it later.
  7. Nella pagina Impostazioni selezionare Autorizzazioni necessarie e selezionare Aggiungi.On the Settings page, select Required Permissions, and then select Add.
  8. Per l'app di Azure Active Directory, selezionare Microsoft Graph come API.For the Azure Active Directory app, select Microsoft Graph as the API.
  9. In Autorizzazioni delegate aggiungere l'autorizzazione Accesso alla directory come utente connesso.Under Delegated Permissions, add the Access the directory as the signed-in user permission. Ciò consente all'app di eseguire query nell'API Graph per gli utenti.Doing so enables the app to query the Graph API for users.

Passaggio 2. Installare e configurare ADALStep 2: Install and configure ADAL

Ora che si dispone di un'app in Azure AD, è possibile installare ADAL e scrivere il codice relativo all'identità.Now that you have an app in Azure AD, you can install ADAL and write your identity-related code. Per abilitare ADAL alla comunicazione con Azure AD, fornire alcune informazioni sulla registrazione dell'app.To enable ADAL to communicate with Azure AD, give it some information about the app registration.

  1. Aggiungere ADAL al progetto DirectorySearcher usando la Console di Gestione pacchetti.Add ADAL to the DirectorySearcher project by using the Package Manager Console.

    PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory
    
  2. Nel progetto DirectorySearcher aprire MainPage.xaml.cs.In the DirectorySearcher project, open MainPage.xaml.cs.

  3. Sostituire i valori nell'area Config Values con i valori immessi nel portale di Azure.Replace the values in the Config Values region with the values that you entered in the Azure portal. Il codice fa riferimento a questi valori ogni volta che usa ADAL.Your code refers to these values whenever it uses ADAL.
    • Il tenant è il dominio del tenant di Azure AD, ad esempio contoso.onmicrosoft.com.The tenant is the domain of your Azure AD tenant (for example, contoso.onmicrosoft.com).
    • Il clientId è l'ID client dell'app. Lo si copia dal portale.The clientId is the client ID of the app, which you copied from the portal.
  4. A questo punto è necessario individuare l'URI di callback per l'app di Windows Store.You now need to discover the callback URI for your Windows Store app. Impostare un punto di interruzione in questa riga del metodo MainPage :Set a breakpoint on this line in the MainPage method: redirectURI = Windows.Security.Authentication.Web.WebAuthenticationBroker.GetCurrentApplicationCallbackUri();
  5. Compilare la soluzione assicurandosi che vengano ripristinati tutti i riferimenti del pacchetto.Build the solution, making sure that all package references are restored. Se mancano pacchetti, aprire Gestione pacchetti NuGet e ripristinarli.If any packages are missing, open the NuGet Package Manager and restore them.
  6. Eseguire l'app e prendere nota del valore di redirectUri quando viene raggiunto il punto di interruzione.Run the app, and copy the value of redirectUri when the breakpoint is hit. Il valore dovrebbe essere simile al seguente:The value should look something like the following:

    ms-app://s-1-15-2-1352796503-54529114-405753024-3540103335-3203256200-511895534-1429095407/
    
  7. Tornare nella scheda Impostazioni dell'app nel portale di Azure e sostituire il valore di RedirectUri con questo valore.Back on the Settings tab of the app in the Azure portal, add a RedirectUri with the preceding value.

Passaggio 3. Usare ADAL per ottenere i token da Azure ADStep 3: Use ADAL to get tokens from Azure AD

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

  1. Inizializzare la classe AuthenticationContext dell'app, che è la classe principale di ADAL.Initialize the app’s AuthenticationContext, which is the primary class of ADAL. Questa azione passa ad ADAL le coordinate necessarie per comunicare con Azure AD e gli indica come memorizzare i token nella cache.This action passes ADAL the coordinates it needs to communicate with Azure AD and tell it how to cache tokens.

    public MainPage()
    {
        ...
    
        authContext = new AuthenticationContext(authority);
    }
    
  2. Individuare il metodo Search(...), che viene richiamato quando l'utente sceglie il pulsante Cerca nell'interfaccia utente dell'app.Locate the Search(...) method, which is invoked when users click the Search button on 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, includere un token di accesso nell'intestazione Authorization della richiesta.To query the Graph API, include an access token in the request's Authorization header. È qui che entra in gioco ADAL.This is where ADAL comes in.

    private async void Search(object sender, RoutedEventArgs e)
    {
        ...
        AuthenticationResult result = null;
        try
        {
            result = await authContext.AcquireTokenAsync(graphResourceId, clientId, redirectURI, new PlatformParameters(PromptBehavior.Auto, false));
        }
        catch (AdalException ex)
        {
            if (ex.ErrorCode != "authentication_canceled")
            {
                ShowAuthError(string.Format("If the error continues, please contact your administrator.\n\nError: {0}\n\nError Description:\n\n{1}", ex.ErrorCode, ex.Message));
            }
            return;
        }
        ...
    }
    

    Quando l'app richiede un token mediante la chiamata a AcquireTokenAsync(...), ADAL tenta di restituire un token senza chiedere le credenziali all'utente.When the app requests a token by calling AcquireTokenAsync(...), ADAL attempts to return a token without asking the user for credentials. Se ADAL determina che l'utente deve eseguire l'accesso per ottenere un token, visualizza una finestra di dialogo di accesso, raccoglie le credenziali dell'utente e restituisce un token al termine dell'autenticazione.If ADAL determines that the user needs to sign in to get a token, it displays a sign-in dialog box, collects the user's credentials, and returns a token after authentication succeeds. Se per qualsiasi motivo ADAL non può restituire un token, lo stato di AuthenticationResult sarà un errore.If ADAL is unable to return a token for any reason, the AuthenticationResult status is an error.

  3. È ora di usare il token di accesso appena acquisito.Now it's time to use the access token you just acquired. Nel metodo Search(...) associare il token alla richiesta get dell'API Graph nell'intestazione Authorization:Also in the Search(...) method, attach the token to the Graph API get request in the Authorization header:

    // Add the access token to the Authorization header of the call to the Graph API, and call the Graph API.
    httpClient.DefaultRequestHeaders.Authorization = new HttpCredentialsHeaderValue("Bearer", result.AccessToken);
    
  4. È possibile usare l'oggetto AuthenticationResult anche per visualizzare informazioni sull'utente nell'app, ad esempio l'ID dell'utente:You can use the AuthenticationResult object to display information about the user in the app, such as the user's ID:

    // Update the page UI to represent the signed-in user
    ActiveUser.Text = result.UserInfo.DisplayableId;
    
  5. È inoltre possibile usare ADAL per disconnettere gli utenti dall'app.You can also use ADAL to sign users out of the app. Quando l'utente fa clic sul pulsante Sign Out (Disconnetti), è opportuno assicurarsi che la chiamata successiva a AcquireTokenAsync(...) mostri una vista di accesso.When the user clicks the Sign Out button, ensure that the next call to AcquireTokenAsync(...) shows a sign-in view. Con ADAL, questa azione è facile quanto cancellare la cache dei token:With ADAL, this action is as easy as clearing the token cache:

    private void SignOut()
    {
        // Clear session state from the token cache.
        authContext.TokenCache.Clear();
    
        ...
    }
    

Passaggi successiviWhat's next

È stata compilata un'app di Windows Store in grado di autenticare gli utenti, di chiamare in modo sicuro le API Web usando OAuth 2.0 e di ottenere le informazioni di base sull'utente.You now have a working Windows Store app that can authenticate users, securely call web APIs using OAuth 2.0, and get basic information about the user.

Se non è stato ancora popolato il tenant con degli utenti, ora è possibile farlo.If you haven’t already populated your tenant with users, now is the time to do so.

  1. Eseguire l'app DirectorySearcher e accedere usando le credenziali di uno di questi utenti.Run your DirectorySearcher app, and then sign in with one of the users.
  2. Cercare altri utenti in base al relativo UPN.Search for other users based on their UPN.
  3. Chiudere l'app e rieseguirla.Close the app, and rerun it. Si noti che la sessione dell'utente non è stata modificata.Notice how the user’s session remains intact.
  4. Disconnettersi facendo clic con il pulsante destro del mouse per visualizzare la barra in basso e quindi accedere nuovamente con le credenziali di un altro utente.Sign out by right-clicking to display the bottom bar, and then sign back in as another user.

ADAL consente di incorporare facilmente nell'app tutte queste funzionalità comuni relative alle identità.ADAL makes it easy to incorporate all these common identity features into the app. Esegue automaticamente le attività più complesse: gestione della cache, supporto del protocollo OAuth, visualizzazione all'utente di un'interfaccia utente di accesso, aggiornamento dei token scaduti.It takes care of all the dirty work for you, such as cache management, OAuth protocol support, presenting the user with a login UI, and refreshing expired tokens. È necessario conoscere una sola chiamata API, authContext.AcquireToken*(…).You need to know only a single API call, authContext.AcquireToken*(…).

Per riferimento, scaricare l'esempio completato, che non contiene i valori di configurazione immessi durante la procedura sopra indicata.For reference, download the completed sample (without your configuration values).

Ora è possibile passare ad altri scenari relativi alle identità.You can now move on to additional identity scenarios. Provare ad esempio Proteggere un'API Web .NET con Azure AD.For example, try 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.