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

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

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

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

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

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

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

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

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

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

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

• Новая модель для доступа к маркерам:
  • ADAL предоставляет доступ к маркерам через AuthenticationContextсервер. MSAL предоставляет доступ к маркерам через PublicClientApplicationклиент. Разработчикам клиентов не нужно создавать новый PublicClientApplication экземпляр для каждого центра, с которым они должны взаимодействовать. Требуется только одна 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 версии 1.0 пользователю было предоставлено согласие на ресурсы, которыми они владеет, при первом использовании. С помощью MSAL и платформа удостоверений Майкрософт можно запрашивать согласие постепенно. Добавочное согласие полезно для разрешений, которые пользователь может рассмотреть с высоким уровнем привилегий, или в противном случае может задаться вопросом, если не предоставлено четкое объяснение того, почему требуется разрешение. В ADAL эти разрешения могут привести к отказу пользователя от входа в приложение.

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

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

Миграция с идентификаторов ресурсов на области

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

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

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

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

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

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

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

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

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

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

Создание PublicClientApplication

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

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

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

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

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

Миграция с проверки центра на известные центры

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

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

Лесозаготовка

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

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

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

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

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

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

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

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

Добавление учетной записи Contoso.com Sam в качестве члена Fabrikam.com приведет к созданию новой записи в Fabrikam.com Идентификатор Microsoft Entra для Sam. Запись Sam в идентификаторе Microsoft Entra называется объектом пользователя. В этом случае объект пользователя будет указывать на объект пользователя Sam в 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
}