Guida introduttiva: Accedere agli utenti e chiamare Microsoft Graph da un'app iOS o macOS

In questa guida introduttiva si scarica ed esegue un esempio di codice che illustra come un'applicazione iOS o macOS nativa può accedere agli utenti e ottenere un token di accesso per chiamare l'API Microsoft Graph.

La guida introduttiva si applica sia alle app iOS che per macOS. Alcuni passaggi sono necessari solo per le app iOS e verranno indicati come tali.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Crea un account gratuitamente.
• XCode 10+
• iOS 10+
• macOS 10.12+

Funzionamento dell'esempio

Registrare l'app di avvio rapido

Per registrare l'applicazione e aggiungere manualmente le informazioni di registrazione dell'app alla soluzione, seguire questa procedura:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno un Application Developer.
2. Se hai accesso a più tenant, usa l'icona impostazioni nel menu in alto per passare al tenant in cui vuoi registrare l'applicazione dal menu Directory + sottoscrizioni.
3. Passare a Identità>Applicazioni>Registrazione app.
4. Selezionare Nuova registrazione.
5. Immettere un Nome per la sua applicazione. Gli utenti dell'app potrebbero visualizzare questo nome ed è possibile modificarlo in un secondo momento.
6. Selezionare Registra.
7. In Gestisciselezionare Authentication>Add Platform>iOS.
8. Immettere il identificatore bundle per l'applicazione. L'identificatore del bundle è una stringa univoca che identifica in modo univoco l'applicazione, ad esempio com.<yourname>.identitysample.MSALMacOS. Prendere nota del valore usato. Si noti che la configurazione di iOS è applicabile anche alle applicazioni macOS.
9. Selezionare Configura e salvare i dettagli della configurazione MSAL per utilizzarli successivamente in questa guida introduttiva.
10. Selezionare Fine.

Passaggio 2: Scaricare il progetto di esempio

• Scaricare l'esempio di codice per iOS
• Scaricare l'esempio di codice per macOS

Passaggio 3: Installare le dipendenze

1. Estrarre il file ZIP.
2. In una finestra del terminale passare alla cartella con l'esempio di codice scaricato ed eseguire pod install per installare la libreria MSAL più recente.

Passaggio 4: Configurare il progetto

Se è stata selezionata l'opzione 1 precedente, è possibile ignorare questi passaggi.

1. Aprire il progetto in XCode.

2. Modificare ViewController.swift e sostituire la riga che inizia con "let kClientID" con il frammento di codice seguente. Ricordarsi di aggiornare il valore per kClientID con l'ID client salvato durante la registrazione dell'app in precedenza in questa guida introduttiva:

   let kClientID = "Enter_the_Application_Id_Here"
   

3. Se si sta creando un'app per cloud nazionali di Microsoft Entra, sostituire la riga che inizia con "let kGraphEndpoint" e "let kAuthority" con endpoint corretti. Per l'accesso globale, usare i valori predefiniti:

   let kGraphEndpoint = "https://graph.microsoft.com/"
   let kAuthority = "https://login.microsoftonline.com/common"
   

4. Altri endpoint sono documentati qui. Ad esempio, per eseguire il quickstart con Microsoft Entra Germania, usare quanto segue:

   let kGraphEndpoint = "https://graph.microsoft.de/"
   let kAuthority = "https://login.microsoftonline.de/common"
   

5. Aprire le impostazioni del progetto. Nella sezione Identity inserire il Bundle Identifier.

6. Clic destro su Info.plist e seleziona Apri come>codice sorgente.

7. Nel nodo radice dict sostituire Enter_the_bundle_Id_Here con l'ID bundle usato nel portale. Si noti il prefisso msauth. nella stringa.

   <key>CFBundleURLTypes</key>
   <array>
      <dict>
         <key>CFBundleURLSchemes</key>
         <array>
            <string>msauth.Enter_the_Bundle_Id_Here</string>
         </array>
      </dict>
   </array>
   

8. Compilare ed eseguire l'app.

Altre informazioni

Leggete queste sezioni per saperne di più su questa guida introduttiva.

Ottieni MSAL

MSAL (MSAL.framework) è la libreria usata per accedere agli utenti e richiedere token usati per accedere a un'API protetta da Microsoft Identity Platform. È possibile aggiungere MSAL all'applicazione usando il processo seguente:

$ vi Podfile

Aggiungere quanto segue a questo podfile (con la destinazione del progetto):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Eseguire il comando di installazione di CocoaPods:

pod install

Inizializzare MSAL

È possibile aggiungere il riferimento per MSAL aggiungendo il codice seguente:

import MSAL

Inizializzare quindi MSAL usando il codice seguente:

let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)

Dove:	Descrizione
clientId	ID dell'applicazione registrata in portal.azure.com
authority	La piattaforma di identità Microsoft. Nella maggior parte dei casi questo sarà https://login.microsoftonline.com/common
redirectUri	URI di reindirizzamento dell'applicazione. È possibile passare 'nil' per usare il valore predefinito o l'URI di reindirizzamento personalizzato.

Solo per iOS, requisiti aggiuntivi per le app

La tua app deve inoltre includere quanto segue nel AppDelegate. Ciò consente a MSAL SDK di gestire la risposta del token dall'app broker di autenticazione quando si esegue l'autenticazione.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Nota

In iOS 13+, se adotti UISceneDelegate invece di UIApplicationDelegate, inserisci questo codice nel callback scene:openURLContexts: (vedi la documentazione di Apple ). Se si supportano sia UISceneDelegate che UIApplicationDelegate per la compatibilità con iOS meno recenti, è necessario inserire il callback MSAL in entrambe le posizioni.

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

   guard let urlContext = URLContexts.first else {
      return
   }

   let url = urlContext.url
   let sourceApp = urlContext.options.sourceApplication

   MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
}

Infine, la tua app deve includere una voce di LSApplicationQueriesSchemes nel Info.plist insieme al CFBundleURLTypes. L'esempio include questo elemento.

<key>LSApplicationQueriesSchemes</key>
<array>
   <string>msauthv2</string>
   <string>msauthv3</string>
</array>

Gli utenti effettuano l'accesso & richiedono token

MSAL include due metodi usati per acquisire i token: acquireToken e acquireTokenSilent.

acquireToken: ottenere un token in modo interattivo

Alcune situazioni richiedono agli utenti di interagire con Microsoft Identity Platform. In questi casi, l'utente finale potrebbe dover selezionare il proprio account, inserire le credenziali o fornire il consenso alle autorizzazioni dell'app. Per esempio

• La prima volta che gli utenti accedono all'applicazione
• Se un utente reimposta la password, dovrà immettere le proprie credenziali
• Quando l'applicazione richiede l'accesso a una risorsa per la prima volta
• Quando è necessaria l'autenticazione a più fattori o altri criteri di accesso condizionale

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}

Dove:	Descrizione
scopes	Contiene gli ambiti richiesti ( ovvero [ "user.read" ] per Microsoft Graph o [ "<Application ID URL>/scope" ] per le API Web personalizzate (api://<Application ID>/access_as_user))

acquireTokenSilent: Ottenere un token di accesso silenziosamente

Le app non devono richiedere agli utenti di accedere ogni volta che richiedono un token. Se l'utente ha già eseguito l'accesso, questo metodo consente alle app di richiedere i token in modo invisibile all'utente.

self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

   guard let account = currentAccount else {
      return
   }

   let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
   self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}

Dove:	Descrizione
scopes	Contiene gli ambiti richiesti ( ovvero [ "user.read" ] per Microsoft Graph o [ "<Application ID URL>/scope" ] per le API Web personalizzate (api://<Application ID>/access_as_user))
account	L'account per cui viene richiesto un token. Questa guida introduttiva riguarda un'applicazione con un singolo account. Se si vuole creare un'app con più account, è necessario definire la logica per identificare l'account da usare per le richieste di token usando accountsFromDeviceForParameters:completionBlock: e il passaggio di accountIdentifier corretti

Guida e supporto tecnico

Per assistenza, per segnalare un problema o per informazioni sulle opzioni di supporto, vedere Guida e supporto per gli sviluppatori.

Passaggi successivi

Passare all'esercitazione dettagliata in cui si compila un'app iOS o macOS che ottiene un token di accesso da Microsoft Identity Platform e la usa per chiamare l'API Microsoft Graph.

Esercitazione: Effettuare l'accesso degli utenti e chiamare Microsoft Graph da un'app iOS o macOS