Guide de migration ADAL vers MSAL pour Android

Cet article met en évidence les modifications que vous devez apporter pour migrer une application qui utilise la bibliothèque d’authentification Azure Active Directory (ADAL) pour utiliser la Microsoft Authentication Library (MSAL).

Points forts de la différence

ADAL fonctionne avec le point de terminaison Azure AD v1.0. Le Microsoft Authentication Library (MSAL) fonctionne avec le Plateforme d'identités Microsoft, anciennement appelé point de terminaison Azure AD v2.0. Le Plateforme d'identités Microsoft diffère de Azure AD v1.0 dans ce cas :

Soutient:

• Identité organisationnelle (Microsoft Entra ID)

• Identités non organisationnelles telles que Outlook.com, Xbox Live, etc.

• (Azure AD B2C uniquement) Connexion fédérée avec Google, Facebook, X et Amazon

• Normes compatibles avec :

  • OAuth v2.0
  • OpenID Connect (OIDC)

L’API publique MSAL introduit des modifications importantes, notamment :

• Un nouveau modèle pour accéder aux jetons :
  • ADAL fournit l’accès aux jetons via AuthenticationContext, qui représente le serveur. MSAL fournit l’accès aux jetons via le PublicClientApplication, qui représente le client. Les développeurs clients n’ont pas besoin de créer une PublicClientApplication instance pour chaque autorité avec laquelle ils doivent interagir. PublicClientApplication Une seule configuration est requise.
  • Prise en charge de la demande de jetons d’accès à l’aide d’étendues en plus des identificateurs de ressources.
  • Prise en charge du consentement incrémentiel. Les développeurs peuvent demander des étendues lorsque l’utilisateur accède à de plus en plus de fonctionnalités dans l’application, y compris celles qui ne sont pas incluses lors de l’inscription de l’application.
  • Les autorités ne sont plus validées au moment de l’exécution. Au lieu de cela, le développeur déclare une liste de « autorités connues » pendant le développement.
• Modifications de l’API de jeton :
  • Dans ADAL, AcquireToken() effectue d’abord une requête silencieuse. En cas d’échec, il effectue une requête interactive. Ce comportement a conduit certains développeurs à s’appuyer uniquement sur AcquireToken, ce qui a amené l’utilisateur à être invité de manière inattendue à saisir ses informations d’identification par moments. MSAL exige des développeurs qu’ils déterminent explicitement à quel moment l’utilisateur reçoit une invite de l’interface utilisateur.
    • AcquireTokenSilent génère toujours une demande silencieuse qui réussit ou échoue.
    • AcquireToken génère toujours une demande qui invite l’utilisateur via l’interface utilisateur.
• MSAL prend en charge la connexion à partir d’un navigateur par défaut ou d’une vue web incorporée :
  • Par défaut, le navigateur par défaut sur l’appareil est utilisé. Cela permet à MSAL d’utiliser l’état d’authentification (cookies) qui peut déjà être présent pour un ou plusieurs comptes connectés. Si aucun état d’authentification n’est présent, l’authentification pendant l’autorisation via MSAL entraîne la création d’un état d’authentification (cookies) à l’avantage d’autres applications web qui seront utilisées dans le même navigateur.
• Nouveau modèle d’exception :
  • Les exceptions définissent plus clairement le type d’erreur qui s’est produit et ce que le développeur doit faire pour le résoudre.
• MSAL prend en charge les objets de paramètre pour les appels AcquireToken et AcquireTokenSilent.
• MSAL prend en charge la configuration déclarative pour :
  • ID client, URI de redirection.
  • Navigateur incorporé et par défaut
  • Autorités
  • Paramètres HTTP tels que le délai d’expiration de lecture et de connexion

Inscription et migration de votre application vers MSAL

Vous n’avez pas besoin de modifier votre inscription d’application existante pour utiliser MSAL. Si vous souhaitez tirer parti du consentement incrémentiel/progressif, vous devrez peut-être passer en revue l’inscription pour identifier les étendues spécifiques que vous souhaitez demander de manière incrémentielle. De plus amples informations sur les portées et le consentement incrémentiel sont fournies ci-après.

Dans l’inscription de votre application dans le portail, vous verrez un onglet Autorisations d’API . Cela fournit une liste des API et autorisations (étendues) auxquelles votre application est actuellement configurée pour demander l’accès. Il affiche également une liste des noms d’étendue associés à chaque autorisation d’API.

Consentement de l’utilisateur

Avec ADAL et le point de terminaison Azure AD v1.0, le consentement de l’utilisateur aux ressources qu’il possède était accordé lors de la première utilisation. Avec MSAL et le Plateforme d'identités Microsoft, le consentement peut être demandé de manière incrémentielle. Le consentement progressif est utile pour les autorisations qu’un utilisateur peut considérer comme particulièrement sensibles, ou qu’il peut autrement remettre en question si aucune explication claire ne lui est fournie quant à la raison pour laquelle l’autorisation est requise. Dans ADAL, ces autorisations peuvent avoir entraîné l’abandon par l’utilisateur de la connexion à votre application.

Consentement de l’administrateur

Les administrateurs d’organisation peuvent consentir aux autorisations requises par votre application pour le compte de tous les membres de leur organisation. Certaines organisations autorisent uniquement les administrateurs à donner leur consentement aux applications. Le consentement administrateur exige que vous incluiez toutes les autorisations et étendues d’API utilisées par votre application dans l’inscription de votre application.

Migration des ID de ressource vers des étendues

Authentifier et demander l’autorisation pour toutes les autorisations lors de la première utilisation

Si vous utilisez actuellement ADAL et que vous n’avez pas besoin d’utiliser le consentement incrémentiel, le moyen le plus simple de commencer à utiliser MSAL consiste à effectuer une acquireToken demande à l’aide du nouvel AcquireTokenParameter objet et à définir la valeur de l’ID de ressource.

Cela aboutira au même comportement v1 auquel vous êtes habitué. Toutes les autorisations demandées dans l’inscription de votre application sont demandées à l’utilisateur lors de sa première interaction.

Authentifier et demander des autorisations uniquement si nécessaire

Pour tirer parti du consentement incrémentiel, faites une liste d’autorisations (étendues) que votre application utilise à partir de votre inscription d’application et organisez-les en deux listes en fonction des éléments suivants :

• Quelles étendues vous souhaitez demander pendant la première interaction de l’utilisateur avec votre application lors de la connexion.
• Les autorisations associées à une fonctionnalité importante de votre application que vous devez également expliquer à l’utilisateur.

Une fois que vous avez organisé les portées, organisez chaque liste en fonction de la ressource (API) pour laquelle vous souhaitez demander un jeton. ainsi que toutes les autres étendues que vous voulez que l’utilisateur autorise en même temps.

L’objet de paramètres utilisé pour effectuer votre requête auprès de MSAL prend en charge :

• Scope: La liste des étendues d’autorisation pour lesquelles vous souhaitez demander une autorisation et recevoir un jeton d’accès.
• ExtraScopesToConsent: Liste supplémentaire d’étendues pour lesquelles vous souhaitez demander une autorisation lorsque vous demandez un jeton d’accès pour une autre ressource. Cette liste d’étendues vous permet de réduire le nombre de fois où vous devez demander l’autorisation de l’utilisateur. Cela signifie moins d’invites d’autorisation ou de consentement de l’utilisateur.

Migrer de AuthenticationContext vers PublicClientApplications

Construction de PublicClientApplication

Lorsque vous utilisez MSAL, vous instanciez un PublicClientApplication. Cet objet modélise votre identité d’application et est utilisé pour effectuer des demandes à une ou plusieurs autorités. Avec cet objet, vous allez configurer votre identité cliente, l’URI de redirection, l’autorité par défaut, s’il faut utiliser le navigateur de l’appareil et l’affichage web incorporé, le niveau de journal, etc.

Vous pouvez configurer cet objet de manière déclarative à l’aide de JSON, que vous fournissez soit sous forme de fichier, soit en tant que ressource dans votre APK.

Bien que cet objet ne soit pas un singleton, il utilise en interne un Executors partagé pour les requêtes interactives et silencieuses.

Entre entreprises

Dans ADAL, chaque organisation à partir de laquelle vous demandez des jetons d’accès nécessite une instance distincte du AuthenticationContext. Dans MSAL, il ne s’agit plus d’une exigence. Vous pouvez spécifier l’autorité à partir de laquelle vous souhaitez demander un jeton dans le cadre de votre demande silencieuse ou interactive.

Migrer de la validation des autorités vers des autorités connues

MSAL n’a pas d’indicateur pour activer ou désactiver la validation de l’autorité. La validation de l’autorité est une fonctionnalité de la bibliothèque ADAL et, dans les premières versions de MSAL, qui empêche votre code de demander des jetons à une autorité potentiellement malveillante. MSAL récupère maintenant une liste d'autorités connues pour Microsoft et fusionne cette liste avec les autorités que vous avez spécifiées dans votre configuration.

Si vous tentez d'utiliser une autorité qui n'est pas connue pour Microsoft et n'est pas incluse dans votre configuration, vous obtiendrez un UnknownAuthorityException.

Logging

Vous pouvez maintenant configurer la journalisation de manière déclarative dans le cadre de votre configuration, comme suit :

"logging": {
  "pii_enabled": false,
  "log_level": "WARNING",
  "logcat_enabled": true
}

Migrer de UserInfo vers un compte

Dans ADAL, l’objet AuthenticationResult fournit un UserInfo objet utilisé pour récupérer des informations sur le compte authentifié. Le terme « utilisateur », qui signifiait un agent humain ou logiciel, était appliqué de manière à ce qu’il soit difficile de communiquer que certaines applications prennent en charge un seul utilisateur (qu’il s’agisse d’un agent humain ou logiciel) qui a plusieurs comptes.

Considérez un compte bancaire. Vous pouvez avoir plusieurs comptes à plusieurs institutions financières. Lorsque vous ouvrez un compte, vous (l’utilisateur) êtes émis des informations d’identification, telles qu’une carte ATM et un code confidentiel, qui sont utilisées pour accéder à votre solde, vos paiements de facturation, etc. pour chaque compte. Ces justificatifs ne peuvent être utilisés qu’à l’institution financière qui les a émises.

Par analogie, comme les comptes d’une institution financière, les comptes de l’Plateforme d'identités Microsoft sont accessibles à l’aide des informations d’identification. Ces informations d’identification sont inscrites ou émises par Microsoft. Ou par Microsoft au nom d’une organisation.

Là où le Plateforme d'identités Microsoft diffère d’une institution financière, dans cette analogie, est que le Plateforme d'identités Microsoft fournit un framework qui permet à un utilisateur d’utiliser un compte et ses informations d’identification associées, d’accéder aux ressources appartenant à plusieurs individus et organisations. C’est comme être en mesure d’utiliser une carte émise par une banque, à une autre institution financière. Cela fonctionne parce que toutes les organisations en question utilisent le Plateforme d'identités Microsoft, ce qui permet à un compte d’être utilisé dans plusieurs organisations. Prenons un exemple :

Sam travaille pour Contoso.com, mais gère Azure machines virtuelles appartenant à Fabrikam.com. Pour que Sam gère les machines virtuelles de Fabrikam, il doit être autorisé à y accéder. Cet accès peut être accordé en ajoutant le compte de Sam à Fabrikam.com et en lui accordant un rôle qui lui permet de travailler avec les machines virtuelles. Pour ce faire, utilisez le portail Azure.

L’ajout du compte Contoso.com de Sam en tant que membre de Fabrikam.com entraînerait la création d’un nouvel enregistrement dans l’ID Microsoft Entra de Fabrikam.com pour Sam. L'enregistrement de Sam dans Microsoft Entra ID est appelé objet utilisateur. Dans ce cas, cet objet utilisateur pointe vers l’objet utilisateur de Sam dans Contoso.com. L’objet utilisateur Fabrikam de Sam est la représentation locale de Sam. Il est utilisé pour stocker des informations sur le compte associé à Sam dans le contexte de Fabrikam.com. Dans Contoso.com, Sam est consultant senior DevOps. Dans Fabrikam, le titre de Sam est Contractor-Machines Virtuelles. Dans Contoso.com, Sam n’est pas responsable, ni autorisé, à gérer les machines virtuelles. Dans Fabrikam.com, c’est sa seule fonction de travail. Cependant, Sam n’a toujours qu’un seul ensemble d’informations d’identification à suivre, qui sont les informations d’identification émises par Contoso.com.

Une fois qu’un appel réussi acquireToken est effectué, vous verrez une référence à un IAccount objet qui peut être utilisé dans les requêtes ultérieures acquireTokenSilent .

IMultiTenantAccount

Si vous avez une application qui accède à des revendications à propos d’un compte à partir de chacun des locataires dans lesquels le compte est représenté, vous pouvez caster des objets IAccount en IMultiTenantAccount. Cette interface fournit un mappage des ITenantProfiles, indexé par ID de locataire, qui vous permet d’accéder aux revendications appartenant au compte dans chacun des locataires à partir desquels vous avez demandé un jeton, par rapport au compte actuel.

Les revendications à la racine de IAccount et de IMultiTenantAccount contiennent toujours les revendications du locataire d’origine. Si vous n’avez pas encore effectué de demande de jeton dans le locataire de base, cette collection est vide.

Autres modifications

Utiliser le nouvel AuthenticationCallback

// Existing ADAL Interface
public interface AuthenticationCallback<T> {

    /**
     * This will have the token info.
     *
     * @param result returns <T>
     */
    void onSuccess(T result);

    /**
     * Sends error information. This can be user related error or server error.
     * Cancellation error is AuthenticationCancelError.
     *
     * @param exc return {@link Exception}
     */
    void onError(Exception exc);
}

// New Interface for Interactive AcquireToken
public interface AuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException}
     */
    void onError(final MsalException exception);

    /**
     * Will be called if user cancels the flow.
     */
    void onCancel();
}

// New Interface for Silent AcquireToken
public interface SilentAuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException} or
     *                  {@link MsalUiRequiredException}.
     */
    void onError(final MsalException exception);
}

Migrer vers les nouvelles exceptions

Dans ADAL, il existe un type d’exception, AuthenticationExceptionqui inclut une méthode pour récupérer la ADALError valeur d’énumération. Dans MSAL, il existe une hiérarchie d’exceptions, et chacun possède son propre ensemble de codes d’erreur spécifiques associés.

Conversion de ADALError en MsalException

Journalisation ADAL vers journalisation MSAL

// Legacy Interface
    StringBuilder logs = new StringBuilder();
    Logger.getInstance().setExternalLogger(new ILogger() {
            @Override
            public void Log(String tag, String message, String additionalMessage, LogLevel logLevel, ADALError errorCode) {
                logs.append(message).append('\n');
            }
        });

// New interface
  StringBuilder logs = new StringBuilder();
  Logger.getInstance().setExternalLogger(new ILoggerCallback() {
      @Override
      public void log(String tag, Logger.LogLevel logLevel, String message, boolean containsPII) {
          logs.append(message).append('\n');
      }
  });

// New Log Levels:
public enum LogLevel
{
    /**
     * Error level logging.
     */
    ERROR,
    /**
     * Warning level logging.
     */
    WARNING,
    /**
     * Info level logging.
     */
    INFO,
    /**
     * Verbose level logging.
     */
    VERBOSE
}