Démarrage rapide : connectez les utilisateurs et appelez Microsoft Graph à partir d'une application Android

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

Les applications doivent être représentées par un objet d’application dans Microsoft Entra ID. La plateforme d’identités Microsoft peut ainsi fournir des jetons à votre application.

Prérequis

Fonctionnement de l’exemple

Diagramme illustrant le fonctionnement de l'exemple d'application généré par ce guide de démarrage rapide.

Le code est organisé en fragments qui montrent comment écrire une application MSAL monocompte et multicompte. Les fichiers de code sont organisés comme suit :

Fichier Illustre le
MainActivity Gère l’interface utilisateur
MSGraphRequestWrapper Appelle l’API Microsoft Graph à l’aide du jeton fourni par l’application MSAL.
MultipleAccountModeFragment Initialise une application multicompte, charge un compte d’utilisateur et obtient un jeton pour appeler l’API Microsoft Graph.
SingleAccountModeFragment Initialise une application monocompte, charge un compte d’utilisateur et obtient un jeton pour appeler l’API Microsoft Graph.
res/auth_config_multiple_account.json Fichier de configuration multicompte
res/auth_config_single_account.json Fichier de configuration monocompte
Scripts Gradle/build.grade (Module : app) Les dépendances de la bibliothèque MSAL sont ajoutées ici.

Nous allons maintenant examiner ces fichiers plus en détail, notamment le code spécifique à MSAL.

Obtenir l’exemple d’application

Enregistrer l’exemple d’application

Conseil

Les étapes décrites dans cet article peuvent varier légèrement en fonction du portail de départ.

  1. Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant que Développeur d’application.

  2. Si vous avez accès à plusieurs tenants, utilisez l’icône Paramètres dans le menu supérieur pour basculer vers le tenant dans lequel vous voulez inscrire l’application à partir du menu Répertoires + abonnements.

  3. Accédez à Identité>Applications>Inscriptions d’applications.

  4. Sélectionnez Nouvelle 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. Sous Types de comptes pris en charge, sélectionnez Comptes dans un annuaire d’organisation (tout annuaire Microsoft Entra - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox). Pour plus d’informations sur les différents types de comptes, sélectionnez l’option M’aider à choisir.

  7. Sélectionnez Inscription.

  8. Sous Gérer, sélectionnez Authentification>Ajouter une plateforme>Android.

  9. Entrez le nom du package de votre projet en fonction du type d’exemple que vous avez téléchargé ci-dessus.

    • Exemple Java : com.azuresamples.msalandroidapp
    • Exemple Kotlin : com.azuresamples.msalandroidkotlinapp
  10. Dans la section Hachage de signature de la page Configurer votre application Android, sélectionnez Création d’un hachage de signature de développement, puis copiez la commande KeyTool vers votre ligne de commande.

  11. Entrez le Hachage de signature généré par KeyTool.

  12. Sélectionnez Configurer et enregistrez la Configuration MSAL qui apparaît dans la page Configuration Android pour pouvoir l’entrer plus tard quand vous devrez configurer votre application.

  13. Cliquez sur Terminé.

Configurer l’exemple d’application

  1. Dans le volet de projet d’Android Studio, accédez à app\src\main\res.

  2. Cliquez avec le bouton droit sur res, puis choisissez Nouveau>Répertoire. Entrez raw en tant que nouveau nom de répertoire, puis sélectionnez OK.

  3. Dans app>src>main>res>raw, accédez au fichier JSON appelé auth_config_single_account.json, puis collez la configuration MSAL que vous avez enregistrée.

    Sous l’URI de redirection, collez :

      "account_mode" : "SINGLE",
    

    Votre fichier de configuration doit ressembler à l’exemple suivant :

    {
      "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
      "authorization_user_agent": "WEBVIEW",
      "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
      "broker_redirect_uri_registered": true,
      "account_mode": "SINGLE",
      "authorities": [
        {
          "type": "AAD",
          "audience": {
            "type": "AzureADandPersonalMicrosoftAccount",
            "tenant_id": "common"
          }
        }
      ]
    }
    

    Comme ce tutoriel montre uniquement comment configurer une application en mode compte unique, consultez Le mode compte unique ou multiple et la configuration de votre application pour plus d’informations

Exécution de l'exemple d'application

Sélectionnez votre émulateur (ou votre appareil physique) à partir de la liste déroulante des Appareils disponibles d’Android Studio et exécutez l’application.

L’exemple d’application démarre sur l’écran Single Account Mode (Mode monocompte). Une étendue par défaut, user.read, est fournie d’office, qui est utilisée lors de la lecture de vos propres données de profil pendant l’appel de l’API Microsoft Graph. L’URL de l’appel de l’API Microsoft Graph est fournie par défaut. Vous pouvez changer ces deux éléments si vous le souhaitez.

Capture d'écran de l'exemple d'application MSAL montrant l'utilisation d'un seul et de plusieurs comptes.

Utilisez le menu de l’application pour passer d’un mode de compte à l’autre.

En mode monocompte, connectez-vous à l’aide d’un compte professionnel ou familial :

  1. Sélectionnez Get graph data interactively (Obtenir les données de graphique de manière interactive) pour inviter l’utilisateur à entrer ses informations d’identification. Vous verrez la sortie de l’appel à l’API Microsoft Graph en bas de l’écran.
  2. Une fois connecté, sélectionnez Obtenir les données du graphique en mode silencieux pour appeler l’API Microsoft Graph sans réinviter l’utilisateur à fournir ses informations d’identification. Vous verrez la sortie de l’appel à l’API Microsoft Graph en bas de l’écran.

En mode multicompte, vous pouvez répéter les mêmes étapes. En outre, vous pouvez supprimer le compte connecté, ce qui supprime également les jetons mis en cache pour ce compte.

Informations supplémentaires

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

Ajouter MSAL à l’application

MSAL (com.microsoft.identity.client) 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. Gradle 3.0 et plus installe la bibliothèque quand vous ajoutez le code suivant à Scripts Gradle>build.gradle (Module : app) , sous Dépendances :

dependencies {
    ...
    implementation 'com.microsoft.identity.client:msal:5.1.0'
    implementation 'com.android.volley:volley:1.2.1'
    ...
}

Ce code indique à Gradle de télécharger et de générer la bibliothèque MSAL à partir de Maven central.

Vous devez également ajouter des références à maven dans la partie allprojects>repositories de settings.gradle (Module: app) sous dependencyResolutionManagement :

dependencyResolutionManagement {
...
maven 
{
 url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
... 
}

Importations pour la bibliothèque MSAL

Les importations pertinentes pour la bibliothèque MSAL sont com.microsoft.identity.client.*. Par exemple, vous verrez import com.microsoft.identity.client.PublicClientApplication;, qui est l’espace de noms de la classe PublicClientApplication, qui représente votre application cliente publique.

SingleAccountModeFragment.java

Ce fichier montre comment créer une application MSAL monocompte et appeler une API Microsoft Graph.

Les applications monocomptes sont utilisées uniquement par un seul utilisateur. Par exemple, vous pouvez avoir un seul compte avec lequel vous vous connectez à votre application de mappage.

Initialisation de MSAL monocompte

Dans SingleAccountModeFragment.java et dans la méthode onCreateView(), un compte unique PublicClientApplication est créé à l’aide des informations de configuration stockées dans le fichier auth_config_single_account.json. Voici comment initialisez la bibliothèque MSAL pour l’utiliser dans une application MSAL monocompte :

...
// Creates a PublicClientApplication object with res/raw/auth_config_single_account.json
PublicClientApplication.createSingleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_single_account,
        new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(ISingleAccountPublicClientApplication application) {
                /**
                 * This test app assumes that the app is only going to support one account.
                 * This requires "account_mode" : "SINGLE" in the config json file.
                 **/
                mSingleAccountApp = application;
                loadAccount();
            }

            @Override
            public void onError(MsalException exception) {
                displayError(exception);
            }
        });

Connecter un utilisateur

Dans SingleAccountModeFragment.java, le code permettant de connecter un utilisateur se trouve dans initializeUI(), dans le gestionnaire de clic signInButton.

Appelez signIn() avant d’essayer d’acquérir des jetons. signIn() se comporte comme si acquireToken() est appelé, ce qui se traduit par une invite interactive permettant à l’utilisateur de se connecter.

La connexion d’un utilisateur est une opération asynchrone. Un rappel est passé qui appelle l’API Microsoft Graph et met à jour l’interface utilisateur une fois que l’utilisateur se connecte :

mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());

Déconnecter un utilisateur

Dans SingleAccountModeFragment.java, le code permettant de déconnecter un utilisateur se trouve dans initializeUI(), dans le gestionnaire de clic signOutButton. La déconnexion d’un utilisateur est une opération asynchrone. La déconnexion de l’utilisateur efface également le cache de jeton pour ce compte. Un rappel est créé pour mettre à jour l’interface utilisateur une fois que le compte d’utilisateur est déconnecté :

mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {
    @Override
    public void onSignOut() {
        updateUI(null);
        performOperationOnSignOut();
    }

    @Override
    public void onError(@NonNull MsalException exception) {
        displayError(exception);
    }
});

Obtenir un jeton de manière interactive ou silencieuse

Pour réduire au minimum le nombre d’invites présentées à l’utilisateur, vous obtenez généralement un jeton en mode silencieux. En cas d’erreur, essayez ensuite d’obtenir un jeton de manière interactive. La première fois que l’application appelle signIn(), elle agit efficacement comme un appel à acquireToken(), ce qui a pour effet d’inviter l’utilisateur à fournir des informations d’identification.

Voici certaines situations dans lesquelles l’utilisateur final peut être amené à sélectionner son compte, entrer ses informations d’identification ou accepter les autorisations que votre application a demandées :

  • La première fois que l’utilisateur se connecte à l’application
  • Si un utilisateur réinitialise son mot de passe, il doit entrer ses informations d’identification
  • Si le consentement est révoqué
  • Si votre application requiert un consentement explicite
  • 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

Le code permettant d’obtenir un jeton de manière interactive, c’est-à-dire avec l’interface utilisateur qui implique l’utilisateur, se trouve dans SingleAccountModeFragment.java, dans initializeUI(), dans le gestionnaire de clic callGraphApiInteractiveButton :

/**
 * If acquireTokenSilent() returns an error that requires an interaction (MsalUiRequiredException),
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your Single Sign-On refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mSingleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Si l’utilisateur s’est déjà connecté, acquireTokenSilentAsync() permet aux applications de demander des jetons en mode silencieux, comme indiqué dans initializeUI(), dans le gestionnaire de clic callGraphApiSilentButton :

/**
 * Once you've signed the user in,
 * you can perform acquireTokenSilent to obtain resources without interrupting the user.
 **/
  mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());

Charger un compte

Le code permettant de charger un compte se trouve dans SingleAccountModeFragment.java, dans loadAccount(). Le chargement du compte de l’utilisateur étant une opération asynchrone, les rappels pour gérer le moment où le compte se charge, change ou une erreur se produit sont passés à MSAL. Le code suivant gère également onAccountChanged(), qui se produit quand un compte est supprimé, que l’utilisateur change de compte, etc.

private void loadAccount() {
    ...

    mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback() {
        @Override
        public void onAccountLoaded(@Nullable IAccount activeAccount) {
            // You can use the account data to update your UI or your app database.
            updateUI(activeAccount);
        }

        @Override
        public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable IAccount currentAccount) {
            if (currentAccount == null) {
                // Perform a cleanup task as the signed-in account changed.
                performOperationOnSignOut();
            }
        }

        @Override
        public void onError(@NonNull MsalException exception) {
            displayError(exception);
        }
    });

Appeler Microsoft Graph

Quand un utilisateur est connecté, l’appel à Microsoft Graph est effectué par le biais d’une requête HTTP par callGraphAPI() qui est définie dans SingleAccountModeFragment.java. Cette fonction est un wrapper qui simplifie l’exemple en exécutant des tâches telles que l’obtention du jeton d’accès à partir du authenticationResult ainsi que l’empaquetage de l’appel à MSGraphRequestWrapper et l’affichage des résultats de l’appel.

private void callGraphAPI(final IAuthenticationResult authenticationResult) {
    MSGraphRequestWrapper.callGraphAPIUsingVolley(
            getContext(),
            graphResourceTextView.getText().toString(),
            authenticationResult.getAccessToken(),
            new Response.Listener<JSONObject>() {
                @Override
                public void onResponse(JSONObject response) {
                    /* Successfully called graph, process data and send to UI */
                    ...
                }
            },
            new Response.ErrorListener() {
                @Override
                public void onErrorResponse(VolleyError error) {
                    ...
                }
            });
}

auth_config_single_account.json

Il s’agit du fichier de configuration d’une application MSAL qui utilise un seul compte.

Consultez Comprendre le fichier de configuration MSAL Android pour obtenir une explication de ces champs.

Notez la présence de "account_mode" : "SINGLE", qui configure cette application pour qu’elle utilise un seul compte.

"client_id" est préconfiguré pour utiliser une inscription d’objet d’application gérée par Microsoft. "redirect_uri"est préconfiguré pour utiliser la clé de signature fournie avec l’exemple de code.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "SINGLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

MultipleAccountModeFragment.java

Ce fichier montre comment créer une application MSAL multicompte et appeler une API Microsoft Graph.

Un exemple d’application multicompte est une application de messagerie qui vous permet d’utiliser plusieurs comptes d’utilisateur, tels qu’un compte professionnel et un compte personnel.

Initialisation de MSAL multicompte

Dans le fichier MultipleAccountModeFragment.java, dans onCreateView(), un objet d’application multicompte (IMultipleAccountPublicClientApplication) est créé à l’aide des informations de configuration stockées dans le fichier auth_config_multiple_account.json file :

// Creates a PublicClientApplication object with res/raw/auth_config_multiple_account.json
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_multiple_account,
        new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(IMultipleAccountPublicClientApplication application) {
                mMultipleAccountApp = application;
                loadAccounts();
            }

            @Override
            public void onError(MsalException exception) {
                ...
            }
        });

L’objet MultipleAccountPublicClientApplication créé est stocké dans une variable membre de classe afin qu’il puisse être utilisé pour interagir avec la bibliothèque MSAL afin d’obtenir des jetons et de charger et supprimer le compte d’utilisateur.

Charger un compte

Les applications multicomptes appellent généralement getAccounts() afin de sélectionner le compte à utiliser pour les opérations MSAL. Le code permettant de charger un compte se trouve dans le fichier MultipleAccountModeFragment.java, dans loadAccounts(). Le chargement du compte de l’utilisateur est une opération asynchrone. Ainsi, un rappel gère les situations où le compte est chargé, change ou une erreur se produit.

/**
 * Load currently signed-in accounts, if there's any.
 **/
private void loadAccounts() {
    if (mMultipleAccountApp == null) {
        return;
    }

    mMultipleAccountApp.getAccounts(new IPublicClientApplication.LoadAccountsCallback() {
        @Override
        public void onTaskCompleted(final List<IAccount> result) {
            // You can use the account data to update your UI or your app database.
            accountList = result;
            updateUI(accountList);
        }

        @Override
        public void onError(MsalException exception) {
            displayError(exception);
        }
    });
}

Obtenir un jeton de manière interactive ou silencieuse

Voici certaines situations dans lesquelles l’utilisateur final peut être amené à sélectionner son compte, entrer ses informations d’identification ou accepter les autorisations que votre application a demandées :

  • La première connexion des utilisateurs à l’application
  • Si un utilisateur réinitialise son mot de passe, il doit entrer ses informations d’identification
  • Si le consentement est révoqué
  • Si votre application requiert un consentement explicite
  • 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

Les applications multicomptes doivent généralement acquérir des jetons de manière interactive, c’est-à-dire avec l’interface utilisateur qui implique l’utilisateur, avec un appel à acquireToken(). Le code permettant d’obtenir un jeton de manière interactive se trouve dans le fichier MultipleAccountModeFragment.java, dans initializeUI(), dans le gestionnaire de clic callGraphApiInteractiveButton :

/**
 * Acquire token interactively. It will also create an account object for the silent call as a result (to be obtained by getAccount()).
 *
 * If acquireTokenSilent() returns an error that requires an interaction,
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your SSO refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mMultipleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Les applications ne doivent pas demander à l’utilisateur de se connecter chaque fois qu’elles ont besoin d’un jeton. Si l’utilisateur s’est déjà connecté, acquireTokenSilentAsync() permet aux applications de demander des jetons sans solliciter l’utilisateur, comme indiqué dans le fichier MultipleAccountModeFragment.java, dans initializeUI(), dans le gestionnaire de clic callGraphApiSilentButton :

/**
 * Performs acquireToken without interrupting the user.
 *
 * This requires an account object of the account you're obtaining a token for.
 * (can be obtained via getAccount()).
 */
mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),
    accountList.get(accountListSpinner.getSelectedItemPosition()),
    AUTHORITY,
    getAuthSilentCallback());

Supprimer un compte

Le code permettant de supprimer un compte et tous les jetons mis en cache pour le compte se trouve dans le fichier MultipleAccountModeFragment.java, dans initializeUI(), dans le gestionnaire du bouton de suppression de compte. Avant de pouvoir supprimer un compte, vous avez besoin d’un objet compte, que vous obtenez à partir de méthodes MSAL comme getAccounts() et acquireToken(). Étant donné que la suppression d’un compte est une opération asynchrone, le rappel onRemoved est fourni pour mettre à jour l’interface utilisateur.

/**
 * Removes the selected account and cached tokens from this app (or device, if the device is in shared mode).
 **/
mMultipleAccountApp.removeAccount(accountList.get(accountListSpinner.getSelectedItemPosition()),
        new IMultipleAccountPublicClientApplication.RemoveAccountCallback() {
            @Override
            public void onRemoved() {
                ...
                /* Reload account asynchronously to get the up-to-date list. */
                loadAccounts();
            }

            @Override
            public void onError(@NonNull MsalException exception) {
                displayError(exception);
            }
        });

auth_config_multiple_account.json

Il s’agit du fichier de configuration d’une application MSAL qui utilise plusieurs comptes.

Consultez Comprendre le fichier de configuration MSAL Android pour obtenir une explication de chacun de ces champs.

Contrairement au fichier de configuration auth_config_single_account.json, ce fichier de configuration a "account_mode" : "MULTIPLE" au lieu de "account_mode" : "SINGLE", car il s’agit d’une application multicompte.

"client_id" est préconfiguré pour utiliser une inscription d’objet d’application gérée par Microsoft. "redirect_uri"est préconfiguré pour utiliser la clé de signature fournie avec l’exemple de code.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

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 Android dans lequel vous créez une application Android 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.