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

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

Registrare l'app della guida introduttiva

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 come sviluppatore di applicazioni.
2. 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.
3. Passare a Identità>Applicazioni>Registrazioni app.
4. Seleziona Nuova registrazione.
5. Immettere un nome per l'applicazione. Tale nome, che potrebbe essere visualizzato dagli utenti dell'app, può essere modificato in un secondo momento.
6. Selezionare Registra.
7. In Gestisci selezionare Autenticazione>Aggiungi una piattaforma>iOS.
8. 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.
9. Selezionare Configura e salvare i dettagli di Configurazione MSAL per usarli in seguito in questa guida di avvio rapido.
10. Selezionare Fatto.

Passaggio 2: Scaricare il progetto di esempio

• Scaricare il codice di esempio per iOS
• Scaricare il codice di esempio per macOS

Passaggio 3: installare le dipendenze

1. Estrai il file zip.
2. 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.

1. In XCode aprire il progetto.

2. Modificare ViewController.swift e sostituire la riga che inizia con 'let kClientID' con il frammento di codice seguente. Aggiornare il valore per kClientID con l'ID client salvato al momento della registrazione dell'app in un passaggio precedente di questa guida introduttiva:

   let kClientID = "Enter_the_Application_Id_Here"
   

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

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

4. Gli altri endpoint sono documentati qui. Per eseguire ad esempio l'avvio rapido con Microsoft Entra Germany, seguire questa procedura:

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

5. Aprire le impostazioni del progetto. Nella sezione Identità, immettere l'Identificatore bundle.

6. Fare clic con il pulsante destro del mouse su Info.plist e scegliere Apri come>Codice sorgente.

7. Nel nodo radice dict sostituire Enter_the_bundle_Id_Here con il valore di 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!

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)

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)
}

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>

Concedere l'accesso agli utenti e richiedere token

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 */}

acquireTokenSilent: ottenere un token di accesso in modo automatico

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 */}
}

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.