Руководство по миграции ADAL в MSAL для Android

В этой статье рассматриваются изменения, необходимые для переноса приложения, использующего библиотеку проверки подлинности Azure Active Directory (ADAL) для использования Microsoft Authentication Library (MSAL).

Основные моменты различий

ADAL работает с конечной точкой Azure AD версии 1.0. Microsoft Authentication Library (MSAL) работает с платформа удостоверений Майкрософт, ранее известной как конечная точка Azure AD версии 2.0. платформа удостоверений Майкрософт отличается от Azure AD версии 1.0 в этом:

Поддерживает:

• Удостоверение организации (Microsoft Entra ID)

• Учетные записи, не связанные с организацией, такие как Outlook.com, Xbox Live и т. д.

• (только для Azure AD B2C) Федеративный вход с помощью Google, Facebook, X и Amazon

• Совместимы ли стандарты со следующими стандартами:

  • OAuth версии 2.0
  • OpenID Connect (OIDC)

Общедоступный API MSAL вводит важные изменения, в том числе:

• Новая модель доступа к токенам:
  • ADAL предоставляет доступ к токенам через AuthenticationContext, который представляет сервер. MSAL предоставляет доступ к токенам через PublicClientApplication, который представляет клиент. Разработчикам клиентов не нужно создавать новый экземпляр PublicClientApplication для каждого Authority, с которым нужно взаимодействовать. Требуется только одна PublicClientApplication конфигурация.
  • Поддержка запроса токенов доступа с использованием областей действия в дополнение к идентификаторам ресурсов.
  • Поддержка добавочного согласия. Разработчики могут запрашивать области, так как пользователь обращается к более и более функциональным возможностям в приложении, включая те, которые не включены во время регистрации приложения.
  • Центры сертификации больше не проверяются во время выполнения. Вместо этого разработчик объявляет список "известных властей" во время разработки.
• Изменения в API токенов:
  • В ADAL AcquireToken() сначала выполняет тихий запрос. Если это не удаётся, выполняется интерактивный запрос. Такое поведение привело к тому, что некоторые разработчики полагались исключительно на AcquireToken, из-за чего пользователям иногда неожиданно предлагалось ввести учетные данные. MSAL требует, чтобы разработчики осознанно определяли, когда пользователю отображается запрос интерфейса.
    • AcquireTokenSilent всегда приводит к тихому запросу, который либо выполняется успешно, либо завершается ошибкой.
    • AcquireToken всегда приводит к запросу, требующему взаимодействия со стороны пользователя через пользовательский интерфейс.
• MSAL поддерживает вход через браузер по умолчанию или встроенное веб-представление:
  • По умолчанию используется браузер по умолчанию на устройстве. Это позволяет MSAL использовать сведения о состоянии аутентификации (файлы cookie), которые уже могут присутствовать для одной или нескольких учетных записей, для которых уже выполнен вход в систему. Если состояние проверки подлинности отсутствует, проверка подлинности во время авторизации через MSAL приводит к созданию состояния проверки подлинности (cookie) для преимущества других веб-приложений, которые будут использоваться в том же браузере.
• Новая модель исключений:
  • Исключения более четко определяют тип ошибки, которая произошла, и то, что разработчик должен сделать для ее устранения.
• MSAL поддерживает объекты параметров в вызовах AcquireToken и AcquireTokenSilent.
• MSAL поддерживает декларативную конфигурацию для:
  • Идентификатор клиента, URI перенаправления.
  • Внедренный браузер и браузер по умолчанию
  • Полномочия
  • Параметры HTTP, такие как время ожидания чтения и подключения

Регистрация и миграция приложения в MSAL

Вам не нужно изменять существующую регистрацию приложения для использования MSAL. Если вы хотите воспользоваться преимуществами добавочного или прогрессивного согласия, может потребоваться просмотреть регистрацию, чтобы определить конкретные области, которые требуется запросить постепенно. Ниже приведены дополнительные сведения об областях и добавочном согласии.

В регистрации вашего приложения на портале вы увидите вкладку Разрешения API. На ней отображается список API и разрешений (областей действия), к которым ваше приложение в настоящее время настроено запрашивать доступ. В нем также отображается список имен областей, связанных с каждым разрешением API.

Согласие пользователя

При использовании ADAL и конечной точки Azure AD v1.0 согласие пользователя на ресурсы, которыми он владеет, предоставлялось при первом использовании. С помощью MSAL и платформа удостоверений Майкрософт можно запрашивать согласие постепенно. Добавочное согласие полезно для разрешений, которые пользователь может рассмотреть с высоким уровнем привилегий, или в противном случае может задаться вопросом, если не предоставлено четкое объяснение того, почему требуется разрешение. В ADAL эти разрешения могут привести к отказу пользователя от входа в приложение.

Согласие администратора

Администраторы организации могут согласиться на разрешения, необходимые приложению от имени всех членов своей организации. Некоторые организации разрешают администраторам предоставлять согласие на приложения. Согласие администратора требует включения всех разрешений и областей API, используемых приложением в регистрации приложения.

Переход от идентификаторов ресурсов к областям

Проверка подлинности и запрос авторизации для всех разрешений при первом использовании

Если вы используете ADAL и не хотите использовать добавочное согласие, самый простой способ начать использование MSAL — сделать acquireToken запрос с помощью нового AcquireTokenParameter объекта и задать значение идентификатора ресурса.

Это приведёт к тому же поведению v1, к которому вы привыкли. Все разрешения, запрошенные в регистрации приложения, запрашиваются от пользователя во время первого взаимодействия.

Проверка подлинности и запрос разрешений только по мере необходимости

Чтобы воспользоваться преимуществами добавочного согласия, сделайте список разрешений (областей), которые приложение использует из регистрации приложения, и упорядочите их в два списка на основе:

• Какие области необходимо запросить во время первого взаимодействия пользователя с приложением во время входа.
• Разрешения, связанные с важной функцией приложения, которые также необходимо объяснить пользователю.

После того как вы упорядочите области, упорядочьте каждый список по тому, для какого ресурса (API) вы хотите запросить токен. А также любые другие области, которые пользователь хочет авторизовать одновременно.

Объект параметров, используемый для выполнения запроса к MSAL, поддерживает:

• Scope: список областей, для которого требуется запросить авторизацию и получить маркер доступа.
• ExtraScopesToConsent: дополнительный список областей, для которого требуется запросить авторизацию при запросе маркера доступа для другого ресурса. Этот список областей позволяет свести к минимуму количество раз, когда требуется запросить авторизацию пользователя. Это означает, что меньше запросов на авторизацию или согласие пользователя.

Миграция из AuthenticationContext в PublicClientApplications

Создание PublicClientApplication

При использовании MSAL вы создаете экземпляр PublicClientApplication. Этот объект описывает идентификатор вашего приложения и используется для отправки запросов к одному или нескольким центрам авторизации. С помощью этого объекта можно настроить идентификатор клиента, URI перенаправления, центр авторизации по умолчанию, использовать ли браузер устройства или встроенное веб-представление, уровень логирования и многое другое.

Этот объект можно декларативно настроить с помощью JSON, который предоставляется как файл или хранится как ресурс в APK.

Хотя этот объект не является синглтоном, внутри он использует общий Executors как для интерактивных, так и для неинтерактивных запросов.

Бизнес для бизнеса

В ADAL для каждой организации, у которой вы запрашиваете маркеры доступа, требуется отдельный экземпляр AuthenticationContext. В MSAL это больше не обязательно. Вы можете указать центр, из которого требуется запросить токен в рамках автоматического или интерактивного запроса.

Переход от проверки центра к доверенным центрам

В MSAL нет флага для включения или отключения проверки центра идентификации. Проверка центра авторизации — это функция ADAL и ранних версий MSAL, которая не позволяет вашему коду запрашивать токены у потенциально вредоносного центра авторизации. MSAL теперь получает список центров авторизации, известных Microsoft, и объединяет этот список со списком центров авторизации, указанных в вашей конфигурации.

Если вы попытаетесь использовать центр сертификации, который неизвестен Microsoft и не включён в вашу конфигурацию, вы получите UnknownAuthorityException.

Logging

Теперь вы можете декларативно настроить ведение журнала в рамках конфигурации, как показано ниже.

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

Миграция из UserInfo в учетную запись

В ADAL элемент AuthenticationResult предоставляет объект UserInfo, используемый для получения сведений о прошедшей проверку подлинности учетной записи. Термин "пользователь", который имел в виду человека или агента программного обеспечения, применялся таким образом, чтобы было трудно сообщить, что некоторые приложения поддерживают одного пользователя (будь то агент человека или программного обеспечения), у которого есть несколько учетных записей.

Рассмотрим банковский счет. У вас может быть несколько счетов в нескольких финансовых учреждениях. При открытии учетной записи вы (пользователь) выдаете учетные данные, такие как карта ATM и ПИН-код, которые используются для доступа к балансу, выставлению счетов и т. д. для каждой учетной записи. Эти учетные данные можно использовать только в финансовом учреждении, которое их выдало.

По аналогии: как и доступ к учетным записям в финансовом учреждении, доступ к учетным записям на платформе идентификации Microsoft осуществляется с помощью учетных данных. Эти учетные данные зарегистрированы или выданы Microsoft. Или со стороны Microsoft от имени организации.

Где платформа удостоверений Майкрософт отличается от финансового учреждения в этой аналогии, заключается в том, что платформа удостоверений Майкрософт предоставляет платформу, которая позволяет пользователю использовать одну учетную запись и связанные с ней учетные данные для доступа к ресурсам, принадлежащим нескольким лицам и организациям. Это как возможность использовать карту, выданную одним банком, в еще одном финансовом учреждении. Это работает, так как все организации, о которых идет речь, используют платформу идентификации Microsoft, которая позволяет использовать одну учетную запись в нескольких организациях. Приведем пример:

Сэм работает для Contoso.com, но управляет Azure виртуальными машинами, принадлежащими Fabrikam.com. Чтобы Сэм управлял виртуальными машинами Fabrikam, он должен быть авторизован для доступа к ним. Этот доступ можно предоставить, добавив учетную запись Сэма в Fabrikam.com, и предоставив ему роль, которая позволяет ему работать с виртуальными машинами. Это будет сделано с помощью портала Azure.

Добавление учетной записи Сэма на Contoso.com в качестве участника Fabrikam.com приведет к созданию новой записи для Сэма в Microsoft Entra ID организации Fabrikam.com. Запись о Sam в Microsoft Entra ID называется пользовательским объектом. В этом случае этот объект пользователя будет ссылаться обратно на объект пользователя Сэма в Contoso.com. Объект пользователя Fabrikam Sam — это локальное представление Sam и будет использоваться для хранения сведений об учетной записи, связанной с Sam в контексте Fabrikam.com. В компании Contoso.com Сэм занимает должность старшего консультанта по DevOps. В компании Fabrikam должность Сэма — подрядчик по виртуальным машинам. В Contoso.com Сэм не несет ответственности, а также не авторизован для управления виртуальными машинами. В компании Fabrikam.com это его единственная должностная обязанность. Тем не менее у Сэма по-прежнему есть только один набор учетных данных, за которым нужно следить, — это учетные данные, выданные Contoso.com.

После успешного acquireToken вызова вы увидите ссылку на IAccount объект, который можно использовать в последующих acquireTokenSilent запросах.

IMultiTenantAccount

Если у вас есть приложение, которое получает доступ к утверждениям об учетной записи из каждого арендатора, в котором представлена эта учетная запись, вы можете привести объекты IAccount к типу IMultiTenantAccount. Этот интерфейс предоставляет отображение ITenantProfiles, где ключом является идентификатор арендатора, и позволяет получать доступ к утверждениям, принадлежащим учетной записи в каждом из арендаторов, у которых вы запросили токен, относительно текущей учетной записи.

Утверждения на верхнем уровне IAccount и IMultiTenantAccount всегда содержат утверждения домашнего арендатора. Если вы еще не запрашивали токен в домашнем тенанте, эта коллекция будет пустой.

Другие изменения

Использование нового компонента 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);
}

Перейдите на новые исключения

В ADAL существует один тип исключения, AuthenticationException, который содержит метод для получения значения перечисления ADALError. В MSAL существует иерархия исключений, и каждый из них имеет собственный набор связанных кодов ошибок.

Преобразование ADALError в MsalException

От журналирования ADAL к журналированию 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
}