Integrare Azure AD in app XamarinIntegrate Azure AD with Xamarin 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.

Xamarin consente di scrivere app per dispositivi mobili in C# che possono essere eseguite in iOS, Android e Windows, in dispositivi mobili e PC.With Xamarin, you can write mobile apps in C# that can run on iOS, Android, and Windows (mobile devices and PCs). Per la compilazione di un'app con Xamarin, Azure Active Directory (Azure AD) semplifica l'autenticazione degli utenti con i relativi account Azure AD.If you're building an app using Xamarin, Azure Active Directory (Azure AD) makes it simple to authenticate users with their Azure AD accounts. L'app può utilizzare in modo sicuro qualsiasi API Web protetta da Azure AD, come le API di Office 365 o l'API di Azure.The app can also securely consume any web API that's protected by Azure AD, such as the Office 365 APIs or the Azure API.

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

  • Viene eseguita in iOS, Android, Windows Desktop, Windows Phone e Windows Store.Run on iOS, Android, Windows Desktop, Windows Phone, and Windows Store.
  • Usa una sola libreria di classi portabile per autenticare gli utenti e ottenere i token per l'API Graph di Azure AD.Use a single portable class library (PCL) to authenticate users and get tokens for the Azure AD Graph API.
  • Cerca in una directory gli utenti con un determinato UPN.Search a directory for users with a given UPN.

Prima di iniziareBefore you get started

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

Passaggio 1: Configurare l'ambiente di sviluppo XamarinStep 1: Set up your Xamarin development environment

Dal momento che questa esercitazione include progetti per iOS, Android e Windows, sono necessari sia Visual Studio che Xamarin.Because this tutorial includes projects for iOS, Android, and Windows, you need both Visual Studio and Xamarin. Per creare l'ambiente necessario, seguire la procedura riportata in Configurazione e installazione di Visual Studio e Xamarin in MSDN.To create the necessary environment, complete the process in Set up and install Visual Studio and Xamarin on MSDN. Le istruzioni includono informazioni relative a Xamarin che è possibile leggere in attesa del completamento delle installazioni.The instructions include material that you can review to learn more about Xamarin while you're waiting for the installations to be completed.

Al termine della configurazione, aprire la soluzione in Visual Studio.After you've completed the setup, open the solution in Visual Studio. Sono presenti sei progetti: cinque progetti specifici delle piattaforme e una libreria di classi portabile, DirectorySearcher.cs, che verrà condivisa tra tutte le piattaforme.There, you will find six projects: five platform-specific projects and one PCL, DirectorySearcher.cs, which will be shared across all platforms.

Passaggio 2: Registrare l'app DirectorySearcherStep 2: 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 e creare una nuova Applicazione client nativa.To create a new Native Client Application, follow the prompts.
    • 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 un valore, ad esempio http://DirectorySearcher.Enter a value (for example, http://DirectorySearcher).
  6. Dopo aver completato la registrazione, Azure AD assegna all'app un ID applicazione univoco.After you’ve completed registration, Azure AD assigns the app a unique application ID. Copiare il valore dalla scheda Applicazione, perché sarà necessario in un secondo momento.Copy the value from 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. Selezionare l'API Microsoft Graph.Select Microsoft Graph as the API. In Autorizzazioni delegate aggiungere l'autorizzazione Lettura dati directory.Under Delegated Permissions, add the Read Directory Data permission.
    Ciò consente all'app di eseguire query nell'API Graph per gli utenti.This action enables the app to query the Graph API for users.

Passaggio 3: Installare e configurare ADALStep 3: Install and configure ADAL

Ora che è disponibile 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 -ProjectName DirectorySearcherLib

    PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -ProjectName DirSearchClient-Android

    PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -ProjectName DirSearchClient-Desktop

    PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -ProjectName DirSearchClient-iOS

    PM> Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -ProjectName DirSearchClient-Universal

    Si noti che a ogni progetto vengono aggiunti due riferimenti alla libreria, ovvero la parte relativa alla libreria di classi portabile di ADAL e una parte specifica della piattaforma.Note that two library references are added to each project: the PCL portion of ADAL and a platform-specific portion.

  2. Nel progetto DirectorySearcherLib aprire DirectorySearcher.cs.In the DirectorySearcherLib project, open DirectorySearcher.cs.
  3. Sostituire i valori dei membri della classe con i valori immessi nel portale di Azure.Replace the class member values 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 che è stato copiato dal portale.The clientId is the client ID of the app, which you copied from the portal.
    • Il returnUri è l'URI di reindirizzamento immesso nel portale, ad esempio http://DirectorySearcher.The returnUri is the redirect URI that you entered in the portal (for example, http://DirectorySearcher).

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

Quasi tutta la logica di autenticazione dell'app si basa su DirectorySearcher.SearchByAlias(...).Almost all of the app's authentication logic lies in DirectorySearcher.SearchByAlias(...). Nei progetti specifici delle piattaforme è sufficiente passare un parametro contestuale alla libreria di classi portabile di DirectorySearcher.All that's necessary in the platform-specific projects is to pass a contextual parameter to the DirectorySearcher PCL.

  1. Aprire DirectorySearcher.cs e quindi aggiungere un nuovo parametro per il metodo SearchByAlias(...).Open DirectorySearcher.cs, and then add a new parameter to the SearchByAlias(...) method. IPlatformParameters è il parametro contestuale che incapsula gli oggetti specifici delle piattaforme necessari ad ADAL per eseguire l'autenticazione.IPlatformParameters is the contextual parameter that encapsulates the platform-specific objects that ADAL needs to perform the authentication.

    public static async Task<List<User>> SearchByAlias(string alias, IPlatformParameters parent)
    {
    
  2. Inizializzare AuthenticationContext, ovvero la classe primaria di ADAL.Initialize AuthenticationContext, which is the primary class of ADAL.
    Questa azione permette di passare ad ADAL le coordinate necessarie per comunicare con Azure AD.This action passes ADAL the coordinates it needs to communicate with Azure AD.

  3. Chiamare AcquireTokenAsync(...), che accetta l'oggetto IPlatformParameters e richiama il flusso di autenticazione necessario per restituire un token all'app.Call AcquireTokenAsync(...), which accepts the IPlatformParameters object and invokes the authentication flow that's necessary to return a token to the app.

    ...
        AuthenticationResult authResult = null;
        try
        {
            AuthenticationContext authContext = new AuthenticationContext(authority);
            authResult = await authContext.AcquireTokenAsync(graphResourceUri, clientId, returnUri, parent);
        }
        catch (Exception ee)
        {
            results.Add(new User { error = ee.Message });
            return results;
        }
    ...
    

    AcquireTokenAsync(...) tenta prima di restituire un token per la risorsa necessaria, in questo caso, l'API Graph, senza chiedere all'utente di immettere le credenziali. A questo scopo vengono usati i token memorizzati nella cache o vengono aggiornati i token precedenti.AcquireTokenAsync(...) first attempts to return a token for the requested resource (the Graph API in this case) without prompting users to enter their credentials (via caching or refreshing old tokens). Se necessario, viene visualizzata la pagina di accesso di Azure AD prima di acquisire il token richiesto.As necessary, it shows users the Azure AD sign-in page before acquiring the requested token.

  4. Associare il token di accesso alla richiesta dell'API Graph nell'intestazione Authorization:Attach the access token to the Graph API request in the Authorization header:

    ...
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
    ...
    

Non sono necessarie altre operazioni per la libreria di classi portabile di DirectorySearcher e il codice relativo all'identità dell'app.That's all for the DirectorySearcher PCL and the app's identity-related code. Non resta che chiamare il metodo SearchByAlias(...) nelle visualizzazioni di ciascuna piattaforma e, se necessario, aggiungere il codice per la corretta gestione del ciclo di vita dell'interfaccia utente.All that remains is to call the SearchByAlias(...) method in each platform's views and, where necessary, to add code for correctly handling the UI lifecycle.

AndroidAndroid

  1. In MainActivity.cs aggiungere una chiamata a SearchByAlias(...) nel gestore di clic del pulsante:In MainActivity.cs, add a call to SearchByAlias(...) in the button click handler:

    List<User> results = await DirectorySearcher.SearchByAlias(searchTermText.Text, new PlatformParameters(this));
    
  2. Eseguire l'override del metodo del ciclo di vita OnActivityResult per inoltrare i reindirizzamenti dell'autenticazione al metodo appropriato.Override the OnActivityResult lifecycle method to forward any authentication redirects back to the appropriate method. ADAL fornisce un apposito metodo helper in Android:ADAL provides a helper method for this in Android:

    ...
    protected override void OnActivityResult(int requestCode, Result resultCode, Intent data)
    {
        base.OnActivityResult(requestCode, resultCode, data);
        AuthenticationAgentContinuationHelper.SetAuthenticationAgentContinuationEventArgs(requestCode, resultCode, data);
    }
    ...
    

Desktop di WindowsWindows Desktop

In MainWindow.xaml.cs effettuare una chiamata a SearchByAlias(...) passando WindowInteropHelper nell'oggetto PlatformParameters del desktop:In MainWindow.xaml.cs, make a call to SearchByAlias(...) by passing a WindowInteropHelper in the desktop's PlatformParameters object:

List<User> results = await DirectorySearcher.SearchByAlias(
  SearchTermText.Text,
  new PlatformParameters(PromptBehavior.Auto, this.Handle));

iOSiOS

In DirSearchClient_iOSViewController.cs l'oggetto iOS PlatformParameters accetta un riferimento al controller di visualizzazione:In DirSearchClient_iOSViewController.cs, the iOS PlatformParameters object takes a reference to the View Controller:

List<User> results = await DirectorySearcher.SearchByAlias(
  SearchTermText.Text,
  new PlatformParameters(PromptBehavior.Auto, this.Handle));

Windows UniversalWindows Universal

In Windows universale, aprire MainPage.xaml.cs e quindi implementare il metodo Search.In Windows Universal, open MainPage.xaml.cs, and then implement the Search method. Quest'ultimo si serve di un metodo helper in un progetto condiviso per aggiornare l'interfaccia utente in base alle esigenze.This method uses a helper method in a shared project to update UI as necessary.

...
List<User> results = await DirectorySearcherLib.DirectorySearcher.SearchByAlias(SearchTermText.Text, new PlatformParameters(PromptBehavior.Auto, false));
...

Passaggi successiviWhat's next

È stata compilata un'app Xamarin funzionante che può autenticare gli utenti e chiamare in modo sicuro le API Web usando OAuth 2.0 in cinque diverse piattaforme.You now have a working Xamarin app that can authenticate users and securely call web APIs by using OAuth 2.0 across five different platforms.

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.

ADAL consente di incorporare facilmente nell'app funzionalità comuni relative alle identità.ADAL makes it easy to incorporate common identity features into the app. Esegue automaticamente le attività più complesse, ovvero gestione della cache, supporto del protocollo OAuth, visualizzazione all'utente di un'interfaccia utente di accesso e 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.