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

Articolo
10/24/2023

In questa guida di avvio rapido si scarica e si esegue un esempio di codice di un'applicazione iOS o macOS nativa che consente agli utenti di accedere e ottenere un token di accesso per chiamare l'API Microsoft Graph.

Questa guida di avvio rapido si applica sia alle app iOS che alle app macOS. Alcuni passaggi sono necessari solo per le app iOS e verranno indicati come tali.

Prerequisiti

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

Funzionamento dell'esempio

Diagramma che illustra il funzionamento dell'app di esempio generata da questa guida introduttiva.

Registrare l'app di avvio rapido

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

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

Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno uno sviluppatore di applicazioni.
Se si ha accesso a più tenant, usare l'icona Impostazioni nel menu in alto per passare al tenant in cui si vuole registrare l'applicazione dal menu Directory e sottoscrizioni.
Passare a Applicazioni> di identità>Registrazioni app.
Seleziona Nuova registrazione.
Immettere un nome per l'applicazione. Tale nome, che potrebbe essere visualizzato dagli utenti dell'app, può essere modificato in un secondo momento.
Selezionare Registra.
In Gestisci selezionare Autenticazione>Aggiungi una piattaforma>iOS.
Immettere il valore di Identificatore del 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.
Selezionare Configura e salvare i dettagli di Configurazione MSAL per usarli in seguito in questa guida di avvio rapido.
Selezionare Fatto.

Passaggio 2: Scaricare il progetto di esempio

Passaggio 3: Installare le dipendenze

Estrai il file zip.
In una finestra del terminale passare alla cartella con il codice di esempio scaricato ed eseguire pod install per installare la libreria MSAL più recente.

Passaggio 4: Configurare il progetto

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

Aprire il progetto in XCode.
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"
```
Se si sta creando un'app per i 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"
```
Gli altri endpoint sono documentati qui. Ad esempio, per eseguire la guida introduttiva con Microsoft Entra Germania, usare quanto segue:
```
let kGraphEndpoint = "https://graph.microsoft.de/"
let kAuthority = "https://login.microsoftonline.de/common"
```
Aprire le impostazioni del progetto. Nella sezione Identità immettere l'identificatore del bundle.
Fare clic con il pulsante destro del mouse su Info.plist e scegliere Apri come>Codice sorgente.

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

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

Compilare ed eseguire l'app.

Ulteriori informazioni

Leggere queste sezioni per altre informazioni su questa guida introduttiva.

Ottenere MSAL

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

$ vi Podfile

Aggiungere il codice seguente al podfile (con la destinazione del progetto):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Eseguire il comando di installazione CocoaPods:

pod install

Inizializzare MSAL

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

import MSAL

Inizializzare quindi la libreria 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`	Microsoft Identity Platform. Nella maggior parte dei casi sarà `https://login.microsoftonline.com/common`
`redirectUri`	URI di reindirizzamento dell'applicazione. È possibile passare nil per usare il valore predefinito oppure specificare un URI di reindirizzamento personalizzato.

Solo per iOS, requisiti aggiuntivi per l'app

L'app deve inoltre includere quanto segue nel relativo AppDelegate. In questo modo, quando si esegue l'autenticazione, MSAL SDK gestisce la risposta del token restituita dall'app broker di 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 si adotta UISceneDelegate invece di UIApplicationDelegate inserire questo codice nel callback scene:openURLContexts: (vedere la documentazione di Apple). Se si supportano sia UISceneDelegate che UIApplicationDelegate per la compatibilità con le versioni precedenti di iOS, il callback MSAL deve essere inserito 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)
}

Per l'app deve infine essere definita una voce LSApplicationQueriesSchemes in Info.plist insieme a CFBundleURLTypes. Nell'esempio queste informazioni sono incluse.

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

La libreria MSAL dispone di due metodi per acquisire i token: acquireToken e acquireTokenSilent

acquireToken: ottenere un token in modo interattivo

In alcune situazioni gli utenti devono interagire con Microsoft Identity Platform. È ad esempio possibile che l'utente finale debba selezionare il proprio account, immettere le credenziali o fornire il consenso alla richiesta di autorizzazioni dell'app. ad esempio:

La prima volta che gli utenti accedono all'applicazione
Se un utente reimposta la password, dovrà immettere le credenziali
Quando l'applicazione richiede l'accesso a una risorsa per la prima volta
Quando è necessario eseguire l'autenticazione a più fattori o soddisfare 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( `[ "user.read" ]` ovvero 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 automaticamente

Le app non dovrebbero 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( `[ "user.read" ]` ovvero per Microsoft Graph o `[ "<Application ID URL>/scope" ]` per le API Web personalizzate (`api://<Application ID>/access_as_user`))
`account`	Indica l'account per il quale viene richiesto un token. Questo argomento di avvio rapido riguarda un'applicazione con 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 passando il valore corretto di `accountIdentifier`

Assistenza e supporto

Se è necessaria assistenza, si vuole segnalare un problema o si vogliono ottenere informazioni sulle opzioni di supporto, vedere Assistenza e supporto per gli sviluppatori.

Passaggi successivi

Procedere con l'esercitazione dettagliata in cui viene creata un'app iOS o macOS che ottiene un token di accesso da Microsoft Identity Platform e lo usa per chiamare l'API Microsoft Graph.

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