Démarrage rapide : Connecter des utilisateurs et appeler l’API Microsoft Graph à partir d’une application iOS ou macOS

Dans ce guide de démarrage rapide, vous téléchargez et exécutez un exemple de code qui montre comment une application iOS ou macOS native peut connecter des utilisateurs et obtenir un jeton d’accès pour appeler l’API Microsoft Graph.

Ce guide de démarrage rapide s’applique aux applications iOS et macOS. Certaines étapes sont nécessaires uniquement pour les applications iOS et seront indiquées comme telles.

Prérequis

Fonctionnement de l’exemple

Shows how the sample app generated by this quickstart works

Inscrire et télécharger votre application de démarrage rapide

Vous disposez de deux options pour démarrer votre application de démarrage rapide :

Option 1 : Inscrire et configurer automatiquement votre application, puis télécharger l’exemple de code

Étape 1 : Inscrivez votre application

Pour inscrire votre application :

  1. Accédez à l’expérience de démarrage rapide Portail Azure - Inscriptions d’applications.
  2. Entrez un nom pour votre application, puis sélectionnez Inscrire.
  3. Suivez les instructions pour télécharger et configurer automatiquement votre nouvelle application en un seul clic.

Option n°2 : Inscrire et configurer manuellement vos application et exemple de code

Étape 1 : Inscrivez votre application

Pour inscrire votre application et ajouter manuellement les informations d’inscription de l’application à votre solution, procédez comme suit :

  1. Connectez-vous au portail Azure.
  2. Si vous avez accès à plusieurs locataires, utilisez le filtre Répertoires + abonnements dans le menu du haut pour basculer vers le locataire dans lequel vous voulez inscrire l’application.
  3. Recherchez et sélectionnez Azure Active Directory.
  4. Sous Gérer, sélectionnez Inscriptions d’applicationsNouvelle inscription.
  5. Entrez un nom pour votre application. Les utilisateurs de votre application peuvent voir ce nom, et vous pouvez le changer ultérieurement.
  6. Sélectionnez Inscription.
  7. Sous Gérer, sélectionnez AuthentificationAjouter une plateformeiOS.
  8. Entrez l'identificateur d'offre groupée de votre application. L’identificateur de bundle est une chaîne unique qui identifie de façon unique votre application, par exemple com.<yourname>.identitysample.MSALMacOS. Prenez note de la valeur que vous utilisez. Notez que la configuration iOS s’applique également aux applications macOS.
  9. Sélectionnez Configurer et enregistrez les détails de la configuration MSAL pour une utilisation ultérieure dans ce guide de démarrage rapide.
  10. Sélectionnez Terminé.

Étape 1 : Configuration de votre application

Pour que l’exemple de code de ce guide de démarrage rapide fonctionne, ajoutez un URI de redirection compatible avec le répartiteur d’authentification.

Already configured Votre application est configurée avec ces attributs

Étape 2 : Téléchargement de l’exemple de projet

Étape 3 : Installer des dépendances

  1. Extrayez le fichier zip.
  2. Dans une fenêtre de terminal, accédez au dossier à l’aide de l’exemple de code téléchargé et exécutez pod install pour installer la bibliothèque MSAL la plus récente.

Étape 4 : Votre application est configurée et prête à être exécutée

Nous avons configuré votre projet avec les valeurs des propriétés de votre application et il est prêt à être exécuté.

Notes

Enter_the_Supported_Account_Info_Here

Étape 4 : Configurer votre projet

Si vous avez sélectionné l’option 1 ci-dessus, vous pouvez ignorer ces étapes.

  1. Ouvrez le projet dans Xcode.

  2. Modifiez ViewController.swift et remplacez la ligne commençant par « let kClientID » par l’extrait de code suivant. N’oubliez pas de mettre à jour la valeur de kClientID avec l’ID client que vous avez enregistré lors de l’inscription de votre application dans le portail, plus haut dans ce guide de démarrage rapide :

    let kClientID = "Enter_the_Application_Id_Here"
    
  1. Si vous créez une application pour les clouds nationaux Azure AD, remplacez la ligne commençant par « let kGraphEndpoint » et « let kAuthority » par des points de terminaison corrects. Pour un accès global, utilisez les valeurs par défaut :

    let kGraphEndpoint = "https://graph.microsoft.com/"
    let kAuthority = "https://login.microsoftonline.com/common"
    
  1. D’autres points de terminaison sont décrits ici. Par exemple, pour exécuter le guide de démarrage rapide avec Azure AD Allemagne, utilisez la commande suivante :

    let kGraphEndpoint = "https://graph.microsoft.de/"
    let kAuthority = "https://login.microsoftonline.de/common"
    
  1. Ouvrez les paramètres du projet. Dans la section Identité, entrez l’Identificateur de bundle que vous avez indiqué dans le portail.

  2. Cliquez avec le bouton droit sur Info.plist et sélectionnez Ouvrir en tant queCode source.

  3. Sous le nœud racine dict, remplacez Enter_the_bundle_Id_Here par l’Enter_the_bundle_Id_Here que vous avez utilisé dans le portail. Notez le préfixe msauth. dans la chaîne.

    <key>CFBundleURLTypes</key>
    <array>
       <dict>
          <key>CFBundleURLSchemes</key>
          <array>
             <string>msauth.Enter_the_Bundle_Id_Here</string>
          </array>
       </dict>
    </array>
    
  1. Générez et exécutez l’application !

Informations complémentaires

Parcourez ces sections pour en savoir plus sur ce démarrage rapide.

Obtenir MSAL

MSAL (MSAL.framework) est la bibliothèque utilisée pour connecter les utilisateurs et demander des jetons permettant d'accéder à une API protégée par la plateforme d'identités Microsoft. Vous pouvez ajouter MSAL à votre application en suivant le processus ci-après :

$ vi Podfile

Ajoutez ce qui suit à ce podfile (avec la cible de votre projet) :

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Exécutez la commande d’installation de CocoaPods :

pod install

Initialiser MSAL

Vous pouvez ajouter la référence de MSAL en ajoutant le code suivant :

import MSAL

Ensuite, initialisez MSAL à l’aide du code suivant :

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

let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
Où : Description
clientId L’ID d’application de l’application inscrite dans portal.azure.com
authority Plateforme d’identités Microsoft. Dans la plupart des cas, ce sera https://login.microsoftonline.com/common
redirectUri URI de redirection de l'application. Vous pouvez passer « nil » pour utiliser la valeur par défaut, ou votre URI de redirection personnalisé.

Pour iOS uniquement, conditions supplémentaires pour les applications

Votre application doit également comporter ce qui suit dans la propriété AppDelegate. Cela permet au kit SDK MSAL de gérer la réponse des jetons à partir de l’application du répartiteur d’authentification, au moment de l’authentification.

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

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

Notes

Sur iOS 13+, si vous adoptez UISceneDelegate au lieu de UIApplicationDelegate, placez ce code dans le rappel scene:openURLContexts: à la place (consultez la UISceneDelegate). Si vous prenez en charge à la fois UISceneDelegate et UIApplicationDelegate pour assurer la compatibilité avec une version plus ancienne d’iOS, le rappel MSAL doit être placé aux deux endroits.

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

Enfin, votre application doit comporter une entrée LSApplicationQueriesSchemes dans votre fichier LSApplicationQueriesSchemes en plus des . Ceci est inclus dans l'exemple fourni.

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

Connecter des utilisateurs et demander des jetons

MSAL utilise deux méthodes pour acquérir des jetons : acquireToken et acquireTokenSilent.

acquireToken : Obtenir un jeton de manière interactive

Certaines situations nécessitent l'interaction des utilisateurs avec la Plateforme d'identités Microsoft. Dans ce cas, l'utilisateur final peut être amené à sélectionner son compte, à saisir ses informations d'identification ou à accepter les autorisations relatives à votre application. Par exemple,

  • La première connexion des utilisateurs à l’application
  • Si un utilisateur réinitialise son mot de passe, il doit entrer ses informations d’identification
  • Lorsque votre application demande l'accès à une ressource pour la première fois
  • Lorsque l'authentification multifacteur ou d'autres stratégies d'accès conditionnel sont requises
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
Où : Description
scopes Contient les étendues demandées (c’est-à-dire [ "user.read" ] pour Microsoft Graph ou [ "<Application ID URL>/scope" ] pour les API web personnalisées (api://<Application ID>/access_as_user)

acquireTokenSilent : Obtenir un jeton d’accès en mode silencieux

Les applications ne doivent pas demander aux utilisateurs de se connecter chaque fois qu'elles ont besoin d'un jeton. Si l'utilisateur est déjà connecté, cette méthode permet aux applications demander des jetons en mode silencieux.

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 */}
}
Où : Description
scopes Contient les étendues demandées (c’est-à-dire [ "user.read" ] pour Microsoft Graph ou [ "<Application ID URL>/scope" ] pour les API web personnalisées (api://<Application ID>/access_as_user)
account Compte pour lequel un jeton est demandé. Ce guide de démarrage rapide concerne une application monocompte. Si vous souhaitez créer une application multicompte, vous devez définir une logique permettant d’identifier le compte à utiliser pour les demandes de jetons à l’aide de accountsFromDeviceForParameters:completionBlock: et de transmettre le accountIdentifier correct.

Aide et support

Si vous avez besoin d’aide, si vous souhaitez signaler un problème ou si vous voulez en savoir plus sur vos options de support, consultez Aide et support pour les développeurs.

Étapes suivantes

Passez au tutoriel pas à pas dans lequel vous créez une application iOS ou macOS qui obtient un jeton d’accès auprès de la plateforme d’identités Microsoft et l’utilise pour appeler l’API Microsoft Graph.