Configurer une application mobile qui appelle des API web

Article
10/25/2023

Après avoir créé votre application, vous allez apprendre à configurer le code à l’aide des paramètres d’inscription de l’application. Les applications mobiles présentent quelques complexités liées à l’ajustement dans leur infrastructure de création.

Bibliothèques Microsoft prenant en charge des applications mobiles

Les bibliothèques Microsoft suivantes prennent en charge les applications mobiles :

Plateforme	Projet sur GitHub	Package	Bien démarrer démarré	Disponibilité générale ou Préversion publique¹
Android (Java)	MSAL pour Android	MSAL	Démarrage rapide	GA
Android (Kotlin)	MSAL pour Android	MSAL	—	GA
iOS (Swift/Obj-C)	MSAL pour iOS et macOS	MSAL	Didacticiel	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹Les termes du contrat de licence universelle pour les services en ligne s’appliquent aux bibliothèques en préversion publique.

Instancier l’application

Android

Les applications mobiles utilisent la classe PublicClientApplication. Voici comment l’instancier :

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Les applications mobiles sur iOS doivent instancier la classe MSALPublicClientApplication. Pour instancier la classe, utilisez le code suivant.

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Des propriétés MSALPublicClientApplicationConfig supplémentaires peuvent remplacer l’autorité par défaut, spécifier un URI de redirection ou modifier le comportement de mise en cache des jetons MSAL.

Xamarin ou UWP

Cette section explique comment instancier l’application pour des applications Xamarin.iOS, Xamarin.Android et UWP.

Instancier l’application

Dans Xamarin ou UWP, le moyen le plus simple d’instancier l’application consiste à utiliser le code suivant. Dans ce code, ClientId est le GUID de votre application inscrite.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Des méthodes With<Parameter> supplémentaires définissent le parent de l’interface utilisateur, remplacent l’autorité par défaut, spécifient un nom et une version de client pour la télémétrie, spécifient un URI de redirection et spécifient la fabrique HTTP à utiliser. La fabrique HTTP peut être utilisée, par exemple, pour gérer les proxies et pour spécifier la télémétrie et la journalisation.

Les sections ci-dessous fournissent plus d’informations sur l’instanciation de l’application.

Spécifier l’interface utilisateur, la fenêtre ou l’activité parente

Sur Android, transmettez l’activité parente avant d’effectuer l’authentification interactive. Sur iOS, lorsque vous utilisez un répartiteur, transmettez ViewController. De la même façon sur UWP, vous pouvez transmettre la fenêtre parente. Vous la transmettez lorsque vous acquérez le jeton. Toutefois, lorsque vous créez l’application, vous pouvez également spécifier un rappel comme délégué qui retourne UIParent.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

Sur Android, nous vous recommandons d’utiliser CurrentActivityPlugin. Le code de générateur PublicClientApplication qui en résulte ressemble à l’exemple suivant :

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

Rechercher d’autres paramètres de création d’applications

Pour obtenir la liste de toutes les méthodes disponibles sur PublicClientApplicationBuilder, consultez la liste des méthodes.

Pour obtenir une description de toutes les options exposées dans PublicClientApplicationOptions, consultez la documentation de référence.

Tâches pour Xamarin iOS

Si vous utilisez MSAL.NET sur Xamarin iOS, effectuez les tâches suivantes.

Pour plus d’informations, consultez Considérations relatives à Xamarin iOS.

Tâches pour MSAL pour iOS et macOS

Ces tâches sont nécessaires lorsque vous utilisez MSAL pour iOS et macOS :

Tâches pour Xamarin.Android

Si vous utilisez Xamarin.Android, effectuez les tâches suivantes :

Pour plus d’informations, consultez Considérations relatives à Xamarin.Android.

Pour plus d’informations concernant les navigateurs sur Android, consultez Considérations spécifiques à Xamarin.Android lors de l’utilisation de MSAL.NET.

Tâches pour UWP

Sur UWP, vous pouvez utiliser des réseaux d’entreprise. Les sections suivantes décrivent les tâches que vous devez effectuer dans le scénario d’entreprise.

Pour plus d’informations, consultez Considérations spécifiques à UWP lors de l’utilisation de MSAL.NET.

Configurer l’application pour utiliser le répartiteur

Sur Android et iOS, les répartiteurs activent :

Authentification unique (SSO) : vous pouvez utiliser l’authentification unique pour les appareils inscrits avec Microsoft Entra ID. Lorsque vous utilisez la SSO, vos utilisateurs n’ont pas besoin de se connecter à chaque application.
Identification des appareils : ce paramètre active les stratégies d’accès conditionnel qui sont liées aux appareils Microsoft Entra. Le processus d’authentification utilise le certificat de l’appareil qui a été créé lorsque l’appareil a été joint à l’espace de travail.
Vérification de l’identification de l’application : Lorsqu’une application appelle le répartiteur, elle transmet son URL de redirection. Le répartiteur la vérifie ensuite.

Activer le répartiteur sur Xamarin

Pour activer le répartiteur sur Xamarin, utilisez le paramètre WithBroker() lorsque vous appelez la méthode PublicClientApplicationBuilder.CreateApplication. Par défaut, .WithBroker() est défini sur true.

Pour activer l’authentification répartie pour Xamarin.iOS, suivez les étapes de la section Xamarin.iOS dans cet article.

Activer le répartiteur pour MSAL pour Android

Pour plus d’informations sur l’activation d’un répartiteur sur Android, consultez Authentification répartie sur Android.

Activer le répartiteur pour MSAL pour iOS et macOS

L’authentification répartie est activée par défaut pour les scénarios Microsoft Entra dans MSAL pour iOS et macOS.

Les sections suivantes fournissent des instructions pour configurer votre application pour la prise en charge de l’authentification répartie pour MSAL pour Xamarin.iOS ou MSAL pour iOS et macOS. Certaines étapes diffèrent dans les deux ensembles d’instructions.

Activer l’authentification répartie pour Xamarin iOS

Suivez les étapes de cette section pour permettre à votre application Xamarin.iOS de communiquer avec l’application Microsoft Authenticator.

Étape 1 : Activer la prise en charge du répartiteur

La prise en charge du répartiteur est désactivée par défaut. Vous l’activez pour une classe de PublicClientApplication individuelle. Utilisez le paramètre WithBroker() lorsque vous créez la classe PublicClientApplication par le biais de PublicClientApplicationBuilder. Par défaut, le paramètre WithBroker() est défini sur true.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

Étape 2 : Mettre à jour AppDelegate pour gérer le rappel

Quand MSAL.NET appelle le répartiteur, ce dernier rappelle votre application. Il la rappelle à l’aide de la méthode AppDelegate.OpenUrl. MSAL attendant la réponse du répartiteur, votre application doit coopérer pour rappeler MSAL.NET. Vous configurez ce comportement en mettant à jour le fichier AppDelegate.cs pour écraser la méthode, comme le montre le code suivant.

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
 if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
 {
  AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
  return true;
 }
 else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
 {
  return false;
 }
 return true;
}

Cette méthode est appelée chaque fois que l'application est lancée. Elle permet de traiter la réponse du répartiteur et de terminer le processus d’authentification que MSAL.NET a démarré.

Étape 3 : Définir un UIViewController()

Pour Xamarin iOS, vous n’êtes normalement pas tenu de définir la fenêtre d’objet. Mais dans ce cas, vous devez la définir afin de pouvoir envoyer et recevoir des réponses d’un répartiteur. Dans AppDelegate.cs, vous devez définir un paramètre ViewController pour définir une fenêtre d’objet.

Pour définir la fenêtre de l’objet, procédez comme suit :

Dans AppDelegate.cs, affectez la valeur App.RootViewController à un nouveau UIViewController(). Ce paramètre permet de s’assurer que l’appel au répartiteur comprend UIViewController. S’il n’est pas défini correctement, vous pouvez recevoir cette erreur :

"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker."

Lors de l’appel AcquireTokenInteractive, utilisez .WithParentActivityOrWindow(App.RootViewController). Transmettez la référence à la fenêtre de l’objet que vous allez utiliser. Voici un exemple :

Dans App.cs :

   public static object RootViewController { get; set; }

Dans AppDelegate.cs :

   LoadApplication(new App());
   App.RootViewController = new UIViewController();

Dans l’appel AcquireToken :

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

Étape 4 : Inscrire un schéma d’URL

MSAL.NET utilise des URL pour appeler le répartiteur, avant de retourner la réponse du répartiteur à votre application. Pour terminer l’aller-retour, inscrivez un schéma d’URL de votre application dans le fichier Info.plist.

Pour inscrire le schéma d’URL de votre application, procédez comme suit :

Ajoutez le préfixe msauth à CFBundleURLSchemes.
Ajoutez CFBundleURLName à la fin. Suivez ce modèle :

$"msauth.(BundleId)"

Ici, BundleId identifie de façon unique votre appareil. Par exemple, si BundleId est yourcompany.xforms, votre schéma d’URL est msauth.com.yourcompany.xforms.

Ce schéma d’URL fera partie de l’URI de redirection qui identifie de façon unique votre application lorsqu’il reçoit la réponse du répartiteur.
```
 <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.xforms</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>msauth.com.yourcompany.xforms</string>
        </array>
      </dict>
    </array>
```

Étape 5 : Ajouter à la section LSApplicationQueriesSchemes

MSAL utilise –canOpenURL: pour vérifier si le répartiteur est installé sur l’appareil. Dans iOS 9, Apple a verrouillé les schémas qu’une application peut interroger.

Ajoutez msauthv2 à la section LSApplicationQueriesSchemes du fichier Info.plist, comme dans l’exemple de code suivant :

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

Authentification répartie pour MSAL pour iOS et macOS

L’authentification répartie est activée par défaut pour les scénarios Microsoft Entra.

Étape 1 : Mettre à jour AppDelegate pour gérer le rappel

Quand MSAL pour iOS et macOS appelle le répartiteur, celui-ci rappelle votre application via la méthode openURL. MSAL attendant la réponse du répartiteur, votre application doit coopérer pour rappeler MSAL. Configurez cette capacité en mettant à jour le fichier AppDelegate.m pour écraser la méthode, comme le montre le code suivant.

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

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

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

Si vous avez adopté UISceneDelegate sur iOS 13 ou une version ultérieure, placez le rappel MSAL dans le scene:openURLContexts: de UISceneDelegate à la place. MSAL handleMSALResponse:sourceApplication: ne doit être appelé qu’une seule fois pour chaque URL.

Pour plus d’informations, consultez la documentation d’Apple.

Étape 2 : Inscrire un schéma d’URL

MSAL pour iOS et macOS utilise des URL pour appeler le répartiteur, avant de retourner la réponse du répartiteur à votre application. Pour terminer l’aller-retour, inscrivez un schéma d’URL pour votre application dans le fichier Info.plist.

Pour inscrire un schéma pour votre application :

Ajoutez le préfixe msauth à votre modèle d’URL personnalisée.
Ajoutez l’identificateur de votre offre groupée à la fin de votre schéma. Suivez ce modèle :

$"msauth.(BundleId)"

Ici, BundleId identifie de façon unique votre appareil. Par exemple, si BundleId est yourcompany.xforms, votre schéma d’URL est msauth.com.yourcompany.xforms.

Ce schéma d’URL fera partie de l’URI de redirection qui identifie de façon unique votre application lorsqu’il reçoit la réponse du répartiteur. Assurez-vous que l’URI de redirection au format msauth.(BundleId)://auth est inscrit pour votre application.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Étape 3 : Ajouter LSApplicationQueriesSchemes

Ajoutez LSApplicationQueriesSchemes pour autoriser les appels à l’application Microsoft Authenticator, si elle est installée.

Notes

Le schéma msauthv3 est nécessaire lorsque votre application est compilée à l’aide de Xcode 11 et versions ultérieures.

Voici un exemple d’ajout de LSApplicationQueriesSchemes :

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

Authentification répartie pour Xamarin.Android

Pour plus d’informations sur l’activation d’un répartiteur sur Android, consultez Authentification répartie sur Xamarin.Android.

Étapes suivantes

Passez à l’article suivant de ce scénario, Acquisition d’un jeton.

Configurer une application mobile qui appelle des API web

Bibliothèques Microsoft prenant en charge des applications mobiles

Instancier l’application

Android

iOS

Xamarin ou UWP

Instancier l’application

Spécifier l’interface utilisateur, la fenêtre ou l’activité parente

Rechercher d’autres paramètres de création d’applications

Tâches pour Xamarin iOS

Tâches pour MSAL pour iOS et macOS

Tâches pour Xamarin.Android

Tâches pour UWP

Configurer l’application pour utiliser le répartiteur

Activer le répartiteur sur Xamarin

Activer le répartiteur pour MSAL pour Android

Activer le répartiteur pour MSAL pour iOS et macOS

Activer l’authentification répartie pour Xamarin iOS

Étape 1 : Activer la prise en charge du répartiteur

Étape 2 : Mettre à jour AppDelegate pour gérer le rappel

Étape 3 : Définir un UIViewController()

Étape 4 : Inscrire un schéma d’URL

Étape 5 : Ajouter à la section LSApplicationQueriesSchemes

Authentification répartie pour MSAL pour iOS et macOS

Étape 1 : Mettre à jour AppDelegate pour gérer le rappel

Étape 2 : Inscrire un schéma d’URL

Étape 3 : Ajouter LSApplicationQueriesSchemes

Authentification répartie pour Xamarin.Android

Étapes suivantes

Ressources supplémentaires