Introduzione a iOS per Azure ADAzure AD iOS getting started

Azure Active Directory (Azure AD) include Active Directory Authentication Library, o ADAL, per i client iOS che devono accedere a risorse protette.Azure Active Directory (Azure AD) provides the Active Directory Authentication Library, or ADAL, for iOS clients that need to access protected resources. ADAL semplifica il processo usato dall'applicazione per ottenere i token di accesso.ADAL simplifies the process that your app uses to obtain access tokens. Per far capire quanto sia semplice, in questo articolo verrà compilata un'applicazione Objective C per eseguire alcuni operazioni che:To demonstrate how easy it is, in this article we build an Objective C To-Do List application that:

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

  1. Registrare l'applicazione con Azure AD.Register your application with Azure AD.
  2. Installare e configurare ADAL.Install and 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. È necessario anche un tenant di Azure AD in cui poter creare gli utenti e registrare un'applicazione.You 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.

Suggerimento

È consigliabile provare l'anteprima del nuovo portale per sviluppatori che consente di imparare a usare Azure AD in pochi minuti.Try the preview of our new developer portal that helps you get up and running with Azure AD in just a few minutes. Il portale per sviluppatori guida l'utente nel processo di registrazione di un'app e di integrazione di Azure AD nel codice.The developer portal guides you through the process of registering an app and integrating Azure AD into your code. Al termine si ottiene un'applicazione semplice in grado di autenticare gli utenti nel tenant e un back-end che può accettare i token ed eseguire la convalida.When you’re finished, you'll have a simple application that can authenticate users in your tenant, and a back end that can accept tokens and perform validation.

1. Determinare qual è l'URI di reindirizzamento per iOS1. Determine what your redirect URI is for iOS

Per avviare in modo sicuro le applicazioni in determinati scenari SSO, è necessario creare un URI di reindirizzamento in un formato particolare.To securely start your applications in certain SSO scenarios, you must create a redirect URI in a particular format. Un URI di reindirizzamento viene usato per assicurarsi che i token vengano restituiti all'applicazione corretta che li aveva richiesti.A redirect URI is used to ensure that the tokens return to the correct application that asked for them.

Il formato iOS per l'URI di reindirizzamento è il seguente:The iOS format for a redirect URI is:

<app-scheme>://<bundle-id>
  • app-scheme: è registrato nel progetto XCodeapp-scheme - This is registered in your XCode project. ed è il modo in cui altre applicazioni possono eseguire la chiamata.It is how other applications can call you. È possibile trovarlo in Info.plist -> URL types -> URL Identifier.You can find this under Info.plist -> URL types -> URL Identifier. È consigliabile crearne uno se non sono stati configurati uno o più URI.You should create one if you don't already have one or more configured.
  • bundle-id : è il Bundle Identifier presente in "identity" nelle impostazioni del progetto in XCode.bundle-id - This is the Bundle Identifier found under "identity" in your XCode project settings.

Per un esempio di questo codice di QuickStart: msquickstart://com.microsoft.azureactivedirectory.samples.graph.QuickStartAn example for this QuickStart code: msquickstart://com.microsoft.azureactivedirectory.samples.graph.QuickStart

2. Registrare l'applicazione DirectorySearcher2. Register the DirectorySearcher application

Per impostare l'app perché ottenga i token, è prima necessario registrarla nel tenant di Azure AD e concederle l'autorizzazione per accedere all'API Graph di Azure AD.To set up your 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:

  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 scegliere il tenant di Active Directory in cui si vuole registrare l'applicazione.Under the Directory list, choose the Active Directory tenant where you want to register your application.
  3. Fare clic su Tutti i servizi nel riquadro di spostamento a sinistra e quindi selezionare Azure Active Directory.Click All services in the leftmost navigation 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.Follow the prompts to create a new Native Client Application.
    • Il nome dell'applicazione descrive l'applicazione agli utenti finali.The Name of the application describes your application to end users.
    • L'URI di reindirizzamento è una combinazione dello schema e della stringa che Azure AD usa per restituire le risposte dei token.The Redirect Uri is a scheme and string combination that Azure AD uses to return token responses. Immettere un valore specifico per l'applicazione in base alle informazioni sull'URI di reindirizzamento sopra riportate.Enter a value that is specific to your application and is based on the previous redirect URI information.
  6. Dopo avere completato la registrazione, Azure AD assegna automaticamente all'app un ID applicazione univoco.After you've completed the registration, Azure AD assigns 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 selezionare Autorizzazioni necessarie e quindi selezionare Aggiungi.From the Settings page, select Required Permissions and then select Add. Selezionare Microsoft Graph come API e aggiungere l'autorizzazione Lettura dati directory in Autorizzazioni delegate.Select Microsoft Graph as the API, and then add the Read Directory Data permission under Delegated Permissions. In questo modo l'applicazione potrà eseguire una query sugli utenti nell'API Graph di Azure AD.This sets up your application to query the Azure AD Graph API for users.

3. Installare e configurare ADAL3. Install and 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é ADAL possa comunicare con Azure AD, è necessario fornirle alcune informazioni sulla registrazione dell'app.For ADAL to communicate with Azure AD, you need to provide it with some information about your app registration.

  1. Si può iniziare aggiungendo la libreria ADAL al progetto DirectorySearcher usando CocaPods.Begin by adding ADAL to the DirectorySearcher project by using CocoaPods.

    $ vi Podfile
    
  2. Aggiungere il codice seguente al podfile:Add the following to this podfile:

    source 'https://github.com/CocoaPods/Specs.git'
    link_with ['QuickStart']
    xcodeproj 'QuickStart'
    
    pod 'ADALiOS'
    
  3. Caricare ora il podfile usando CocoaPods.Now load the podfile by using CocoaPods. Verrà creata una nuova area di lavoro XCode che sarà caricata.This step creates a new XCode workspace that you load.

    $ pod install
    ...
    $ open QuickStart.xcworkspace
    
  4. Nel progetto QuickStart, aprire il file plist settings.plist.In the QuickStart project, open the plist file settings.plist. Sostituire i valori degli elementi nella sezione in modo che corrispondano ai valori immessi nel portale di Azure.Replace the values of the elements in the section to reflect the values that you entered in the Azure portal. Il codice fa riferimento a questi valori ogni volta che usa ADAL.Your code references 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, for example, contoso.onmicrosoft.com.
    • clientId è l'ID client dell'applicazione copiato dal portale.The clientId is the client ID of your application that you copied from the portal.
    • redirectUri è l'URL di reindirizzamento registrato nel portale.The redirectUri is the redirect URL that you registered in the portal.

4. Usare ADAL per ottenere i token da Azure AD4. Use ADAL to get tokens from Azure AD

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

  1. Nel progetto QuickStart aprire GraphAPICaller.m e trovare il commento // TODO: getToken for generic Web API flows. Returns a token with no additional parameters provided. nella parte superiore,In the QuickStart project, open GraphAPICaller.m and locate the // TODO: getToken for generic Web API flows. Returns a token with no additional parameters provided. comment near the top. dove si passano ad ADAL le coordinate attraverso un CompletionBlock per comunicare con Azure AD e gli si indica come memorizzare i token nella cache.This is where you pass ADAL the coordinates through a CompletionBlock, to communicate with Azure AD, and tell it how to cache tokens.

    +(void) getToken : (BOOL) clearCache
               parent:(UIViewController*) parent
    completionHandler:(void (^) (NSString*, NSError*))completionBlock;
    {
        AppData* data = [AppData getInstance];
        if(data.userItem){
            completionBlock(data.userItem.accessToken, nil);
            return;
        }
    
        ADAuthenticationError *error;
        authContext = [ADAuthenticationContext authenticationContextWithAuthority:data.authority error:&error];
        authContext.parentController = parent;
        NSURL *redirectUri = [[NSURL alloc]initWithString:data.redirectUriString];
    
        [ADAuthenticationSettings sharedInstance].enableFullScreen = YES;
        [authContext acquireTokenWithResource:data.resourceId
                                     clientId:data.clientId
                                  redirectUri:redirectUri
                               promptBehavior:AD_PROMPT_AUTO
                                       userId:data.userItem.userInformation.userId
                        extraQueryParameters: @"nux=1" // if this strikes you as strange it was legacy to display the correct mobile UX. You most likely won't need it in your code.
                             completionBlock:^(ADAuthenticationResult *result) {
    
                                  if (result.status != AD_SUCCEEDED)
                                  {
                                     completionBlock(nil, result.error);
                                  }
                                  else
                                  {
                                      data.userItem = result.tokenCacheStoreItem;
                                      completionBlock(result.tokenCacheStoreItem.accessToken, nil);
                                  }
                             }];
    }
    
  2. A questo punto è necessario usare questo token per cercare gli utenti nel grafico.Now we need to use this token to search for users in the graph. Trovare il commento // TODO: implement SearchUsersList.Find the // TODO: implement SearchUsersList comment. 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 di Azure AD, è necessario includere un oggetto access_token nell'intestazione Authorization della richiesta.To query the Azure AD Graph API, you need to include an access_token in the Authorization header of the request. È qui che entra in gioco ADAL.This is where ADAL comes in.

    +(void) searchUserList:(NSString*)searchString
                    parent:(UIViewController*) parent
          completionBlock:(void (^) (NSMutableArray* Users, NSError* error)) completionBlock
    {
        if (!loadedApplicationSettings)
       {
            [self readApplicationSettings];
        }
    
        AppData* data = [AppData getInstance];
    
        NSString *graphURL = [NSString stringWithFormat:@"%@%@/users?api-version=%@&$filter=startswith(userPrincipalName, '%@')", data.taskWebApiUrlString, data.tenant, data.apiversion, searchString];
    
        [self craftRequest:[self.class trimString:graphURL]
                    parent:parent
         completionHandler:^(NSMutableURLRequest *request, NSError *error) {
    
             if (error != nil)
             {
                 completionBlock(nil, error);
             }
             else
             {
    
                 NSOperationQueue *queue = [[NSOperationQueue alloc]init];
    
                 [NSURLConnection sendAsynchronousRequest:request queue:queue completionHandler:^(NSURLResponse *response, NSData *data, NSError *error) {
    
                     if (error == nil && data != nil){
    
                         NSDictionary *dataReturned = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
    
                         // We can grab the JSON node at the top to get our graph data.
                         NSArray *graphDataArray = [dataReturned objectForKey:@"value"];
    
                         // Don't be thrown off by the key name being "value". It really is the name of the
                         // first node. :-)
    
                         // Each object is a key value pair
                         NSDictionary *keyValuePairs;
                         NSMutableArray* Users = [[NSMutableArray alloc]init];
    
                         for(int i =0; i < graphDataArray.count; i++)
                         {
                             keyValuePairs = [graphDataArray objectAtIndex:i];
    
                             User *s = [[User alloc]init];
                             s.upn = [keyValuePairs valueForKey:@"userPrincipalName"];
                             s.name =[keyValuePairs valueForKey:@"givenName"];
    
                             [Users addObject:s];
                         }
    
                         completionBlock(Users, nil);
                     }
                     else
                     {
                         completionBlock(nil, error);
                     }
    
                }];
             }
         }];
    
    }
    
  3. Quando l'app richiede un token mediante la chiamata a getToken(...), ADAL tenta di restituire un token senza chiedere le credenziali all'utente.When your app requests a token by calling getToken(...), 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 will display a dialog box for sign-in, collect the user's credentials, and then return a token after successful authentication. Se ADAL non può restituire un token per qualsiasi motivo, genera una AdalException.If ADAL is not able to return a token for any reason, it throws an AdalException.

Nota

L'oggetto AuthenticationResult contiene un oggetto tokenCacheStoreItem che può essere usato per raccogliere informazioni che potrebbero essere richieste dall'app.The AuthenticationResult object contains a tokenCacheStoreItem object that can be used to collect the information that your app may need. Nel progetto QuickStart viene usato tokenCacheStoreItem per determinare se l'autenticazione è già stata eseguita.In the QuickStart, tokenCacheStoreItem is used to determine if authentication is already done.

5. Compilare ed eseguire l'applicazione5. Build and run the application

Congratulazioni!Congratulations! Si dispone ora di un'applicazione iOS funzionante in grado di autenticare gli utenti, chiamare in modo sicuro le API Web usando OAuth 2.0 e ottenere informazioni di base sull'utente.You now have a working iOS application that can authenticate users, securely call Web APIs by 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. Avviare l'applicazione QuickStart e accedere come uno di questi utenti.Start your QuickStart app, and then 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 avviarla nuovamente.Close the app, and then start it again. Si noti che la sessione dell'utente non è stata modificata.Notice that the user's session remains intact.

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, 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, like cache management, OAuth protocol support, presenting the user with a UI to sign in, and refreshing expired tokens. Tutto ciò che occorre conoscere è una sola chiamata all'API, getToken.All you really need to know is a single API call, getToken.

L'esempio completato (senza i valori di configurazione) è disponibile in GitHub per riferimento.For reference, the completed sample (without your configuration values) is provided on GitHub.

Passaggi successiviNext steps

Ora è possibile passare ad altri scenari.You can now move on to additional scenarios. È possibile:You may want to try:

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.