Integrare Azure AD con un'app di Windows PhoneIntegrate Azure AD with a Windows Phone 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.

Nota

I progetti Windows Phone 8.1 e versioni precedenti non sono supportati in Visual Studio 2017.Windows Phone 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.

Se si sta sviluppando un'app di Windows Phone 8.1, Azure AD semplifica e facilita l'autenticazione degli utenti con gli account Active Directory.If you're developing a Windows Phone 8.1 app, 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.

Nota

Questo esempio di codice usa ADAL versione 2.0.This code sample uses ADAL v2.0. Per la tecnologia più recente, si consiglia di provare invece l' esercitazione di Windows universale con ADAL versione 3.0.For the latest technology, you may want to instead try our Windows Universal Tutorial using ADAL v3.0. Se si sta creando un'app per Windows Phone 8.1, questo è il posto giusto.If you are indeed building an app for Windows Phone 8.1, this is the right place. La versione 2.0 di ADAL è ancora completamente supportata ed è lo strumento consigliato per lo sviluppo di app per Windows Phone 8.1 con Azure AD.ADAL v2.0 is still fully supported, and is the recommended way of developing apps agianst Windows Phone 8.1 using Azure AD.

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'app di Windows Phone 8.1, "Directory Searcher", che:To demonstrate just how easy it is, here we’ll build a "Directory Searcher" Windows Phone 8.1 app 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 UPN.Searches a directory for users with a given UPN.
  • 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 un progetto struttura o scaricare l'esempio completato.To get started, download a skeleton project or download the completed sample. Ognuno è una soluzione di Visual Studio 2013.Each is a Visual Studio 2013 solution. 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 Directory Searcher1. Register the Directory Searcher 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. Per ora immettere un valore segnaposto, ad esempio http://DirectorySearcher.Enter a placeholder value for now, e.g. http://DirectorySearcher. Questo valore verrà sostituito in un secondo momento.We'll replace this value later.
  6. Dopo avere completato la registrazione, AAD assegnerà all'app un ID app univoco.Once you’ve completed registration, AAD will assign your app a unique Application ID. Poiché questo valore sarà necessario nelle sezioni successive, copiarlo dalla scheda dell'applicazione.You’ll need this value in the next sections, so copy it from the application tab.
  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 MainPage.xaml.cs.In the DirectorySearcher project, open MainPage.xaml.cs. Sostituire i valori dell'area Config Values in modo che corrispondano ai valori inseriti nel portale di Azure.Replace the values in the Config Values region 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.
    • tenant è il dominio del tenant di Azure AD, ad esempio, contoso.onmicrosoft.com.The tenant is the domain of your Azure AD tenant, e.g. contoso.onmicrosoft.com
    • clientId è l'ID client dell'applicazione copiato dal portale.The clientId is the clientId of your application you copied from the portal.
  • Ora è necessario individuare l'URI di callback per l'app di Windows Phone.You now need to discover the callback uri for your Windows Phone 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();
  • Eseguire l'app e prendere nota del valore di redirectUri quando viene raggiunto il punto di interruzione.Run the app, and copy aside the value of redirectUri when the breakpoint is hit. Dovrebbe essere simile aIt should look something like
ms-app://s-1-15-2-1352796503-54529114-405753024-3540103335-3203256200-511895534-1429095407/
  • Sempre nella scheda Configura dell'applicazione nel portale di gestione di Azure sostituire il valore di RedirectUri con questo valore.Back on the Configure tab of your application in the Azure Management Portal, replace the value of the RedirectUri with this value.

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.AcquireToken(…) e ADAL fa il resto.The basic principle behind ADAL is that whenever your app needs an access token, it simply calls authContext.AcquireToken(…), and ADAL does the rest.

  • 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 MainPage()
{
    ...

    // ADAL for Windows Phone 8.1 builds AuthenticationContext instances through a factory
    authContext = AuthenticationContext.CreateAsync(authority).GetResults();
}
  • 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)
{
    ...

    // Try to get a token without triggering any user prompt.
    // ADAL will check whether the requested token is in ADAL's token cache or can otherwise be obtained without user interaction.
    AuthenticationResult result = await authContext.AcquireTokenSilentAsync(graphResourceId, clientId);
    if (result != null && result.Status == AuthenticationStatus.Success)
    {
        // A token was successfully retrieved.
        QueryGraph(result);
    }
    else
    {
        // Acquiring a token without user interaction was not possible.
        // Trigger an authentication experience and specify that once a token has been obtained the QueryGraph method should be called
        authContext.AcquireTokenAndContinue(graphResourceId, clientId, redirectURI, QueryGraph);
    }
}
  • Se è necessaria l'autenticazione interattiva, ADAL userà WAB (Web Authentication Broker) e il modello di continuazione di Windows Phone per visualizzare la pagina di accesso di Azure AD.If interactive authentication is necessary, ADAL will use Windows Phone's Web Authentication Broker (WAB) and continuation model to display the Azure AD sign in page. Quando l'utente effettua l'accesso, l'app deve passare ad ADAL i risultati dell'interazione WAB.When the user signs in, your app needs to pass ADAL the results of the WAB interaction. È semplice come implementare l'interfaccia ContinueWebAuthentication :This is as simple as implementing the ContinueWebAuthentication interface:
// This method is automatically invoked when the application
// is reactivated after an authentication interaction through WebAuthenticationBroker.
public async void ContinueWebAuthentication(WebAuthenticationBrokerContinuationEventArgs args)
{
    // pass the authentication interaction results to ADAL, which will
    // conclude the token acquisition operation and invoke the callback specified in AcquireTokenAndContinue.
    await authContext.ContinueAcquireTokenAsync(args);
}
  • Ora è possibile usare l'oggetto AuthenticationResult restituito da ADAL all'app.Now it's time to use the AuthenticationResult that ADAL returned to your app. Nel callback QueryGraph(...) associare l'oggetto access_token acquisito alla richiesta GET nell'intestazione dell'autorizzazione:In the QueryGraph(...) callback, attach the access_token you acquired to the GET request in the Authorization header:
private async void QueryGraph(AuthenticationResult result)
{
    if (result.Status != AuthenticationStatus.Success)
    {
        MessageDialog dialog = new MessageDialog(string.Format("If the error continues, please contact your administrator.\n\nError: {0}\n\nError Description:\n\n{1}", result.Error, result.ErrorDescription), "Sorry, an error occurred while signing you in.");
        await dialog.ShowAsync();
    }

    // Add the access token to the Authorization Header of the call to the Graph API, and call the Graph API.
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

    ...
}
  • È possibile usare l'oggetto AuthenticationResult anche per visualizzare informazioni sull'utente nell'app.You can also use the AuthenticationResult object to display information about the user in your app. Nel metodo QueryGraph(...) usare il risultato per visualizzare l'ID dell'utente nella pagina:In the QueryGraph(...) method, use the result to show the user's id on the page:
// Update the Page UI to represent the signed in user
ActiveUser.Text = result.UserInfo.DisplayableId;
  • Infine è possibile usare ADAL anche per disconnettere l'utente dall'applicazione.Finally, you can use ADAL to sign the user out of hte application as well. È opportuno assicurarsi che, quando l'utente fa clic sul pulsante "Sign Out", la chiamata successiva a AcquireTokenSilentAsync(...) abbia esito negativo.When the user clicks the "Sign Out" button, we want to ensure that the next call to AcquireTokenSilentAsync(...) will fail. Con ADAL, basta cancellare la cache dei token:With ADAL, this is as easy as clearing the token cache:
private void SignOut()
{
    // Clear session state from the token cache.
    authContext.TokenCache.Clear();

    ...
}

Congratulazioni.Congratulations! È stata compilata un'app di Windows Phone 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 Windows Phone app 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.AcquireToken*(…).All you really need to know is a single API call, authContext.AcquireToken*(…).

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 relativi alle identità.You can now move on to additional identity 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.