Перенос приложений в MSAL для iOS и macOS

Библиотека аутентификации Azure Active Directory (ADAL Objective-C) была создана для работы с учетными записями Microsoft Entra через конечную точку версии 1.0.

Библиотека Microsoft Authentication Library для iOS и macOS (MSAL) создана для работы со всеми типами учетных записей Microsoft, такими как учетные записи Microsoft Entra, личные учетные записи Microsoft и учетные записи Azure AD B2C, через платформу платформа удостоверений Майкрософт (ранее — конечная точка Azure AD v2.0).

платформа удостоверений Майкрософт имеет несколько ключевых различий с Azure AD версии 1.0. В этой статье рассматриваются эти различия и приводятся рекомендации по переносу приложения из ADAL в MSAL.

Различия возможностей приложений ADAL и MSAL

Кто может войти

  • ADAL поддерживает только рабочие и учебные учетные записи, также известные как Microsoft Entra учетные записи.
  • MSAL поддерживает личные учетные записи Microsoft (учетные записи MSA), такие как Hotmail.com, Outlook.com и Live.com.
  • MSAL поддерживает рабочие или учебные учетные записи, а также учетные записи Azure AD B2C.

Соответствие стандартам

  • платформа удостоверений Майкрософт следует стандартам OAuth 2.0 и OpenId Connect.
  • платформа удостоверений Майкрософт позволяет динамически запрашивать разрешения. Приложения могут запрашивать разрешения только по мере необходимости и запрашивать больше, так как приложение нуждается в них. Дополнительные сведения см. в разделе "Разрешения и согласие".

Различия библиотек ADAL и MSAL

Общедоступный API MSAL отражает несколько ключевых различий между Azure AD версии 1.0 и платформа удостоверений Майкрософт.

MSALPublicClientApplication вместо ADAuthenticationContext

ADAuthenticationContext — это первый объект, который создает приложение ADAL. Он представляет экземпляр ADAL. Приложения создают новый экземпляр ADAuthenticationContext для каждой комбинации облака Microsoft Entra и клиента (центра авторизации). Один и тот же ADAuthenticationContext можно использовать для получения токенов для нескольких общедоступных клиентских приложений.

В MSAL основное взаимодействие происходит через объект MSALPublicClientApplication, который смоделирован по образцу общедоступного клиента OAuth 2.0. Один экземпляр MSALPublicClientApplication можно использовать для взаимодействия с несколькими облачными средами Microsoft Entra и арендаторами без необходимости создавать новый экземпляр для каждого центра авторизации. Для большинства приложений достаточно одного MSALPublicClientApplication экземпляра.

Области действия вместо ресурсов

В ADAL приложение должно было предоставить идентификатор ресурса, например https://graph.microsoft.com, чтобы получить маркеры из конечной точки Azure AD v1.0. Ресурс может определить ряд областей или oAuth2Permissions в манифесте приложения, которые он понимает. Это позволило клиентским приложениям запрашивать маркеры из этого ресурса для определенного набора областей, предварительно определенных во время регистрации приложения.

В MSAL вместо одного идентификатора ресурса приложения предоставляют набор областей для каждого запроса. Область действия — это идентификатор ресурса, после которого указывается имя разрешения в формате resource/permission. Например: https://graph.microsoft.com/user.read

В MSAL есть два способа указать области действия:

  • Укажите список всех необходимых разрешений для приложений. Рассмотрим пример.

    @[@"https://graph.microsoft.com/directory.read", @"https://graph.microsoft.com/directory.write"]

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

  • Область /.default.

Это встроенная область для каждого приложения. Он ссылается на статический список разрешений, настроенных при регистрации приложения. Его поведение аналогично поведению resource. Это может быть полезно при миграции, чтобы обеспечить сохранение аналогичного набора областей и взаимодействия с пользователем.

Чтобы использовать /.default область, добавьте /.default к идентификатору ресурса. Например: https://graph.microsoft.com/.default. Если ваш ресурс заканчивается косой чертой (/), вам всё равно следует добавить в конец /.default, включая начальную косую черту, в результате чего получится область действия с двойной косой чертой (//).

Дополнительные сведения об использовании области "/.default" см. в разрешениях и областях.

Поддержка различных типов WebView и браузеров

ADAL поддерживает только UIWebView/WKWebView для iOS и WebView для macOS. MSAL для iOS поддерживает больше вариантов отображения веб-содержимого при запросе кода авторизации и больше не поддерживает UIWebView; что может повысить удобство работы пользователя и безопасность.

По умолчанию MSAL в iOS использует ASWebAuthenticationSession, веб-компонент, который Apple рекомендует для аутентификации на устройствах iOS 12+. Он предоставляет преимущества единого входа через общий доступ к файлам cookie между приложениями и браузером Safari.

Вы можете использовать другой веб-компонент в зависимости от требований приложения и пользовательского интерфейса. Дополнительные сведения см. в поддерживаемых типах веб-представлений .

При переходе с ADAL на MSAL WKWebView предоставляется наиболее похожий интерфейс на ADAL на iOS и macOS. Мы рекомендуем вам перейти на ASWebAuthenticationSession iOS, если это возможно. Для macOS рекомендуется использовать WKWebView.

Различия API управления учетными записями

При вызове методов ADAL acquireToken() или acquireTokenSilent() вы получаете объект ADUserInformation, содержащий список утверждений из объекта id_token, который представляет учетную запись, проходящую проверку подлинности. Кроме того, ADUserInformation возвращает userId на основе утверждения upn. После первоначального интерактивного получения токена ADAL ожидает, что разработчик будет передавать userId во всех неинтерактивных вызовах.

ADAL не предоставляет API для получения известных идентификаторов пользователей. Оно использует приложение для сохранения и управления этими учетными записями.

MSAL предоставляет набор API, позволяющих получить список всех учетных записей, известных библиотеке MSAL, без необходимости получать токен.

Как и ADAL, MSAL возвращает сведения об учетной записи, содержащие список утверждений из id_token. Она является частью MSALAccount объекта внутри MSALResult объекта.

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

Кроме того, MSAL также возвращает идентификатор учетной записи, который позже можно использовать для запроса токена без взаимодействия с пользователем. Однако идентификатор учетной записи (доступный через свойство identifier объекта MSALAccount) не предназначен для отображения, и вы не можете предполагать, в каком формате он представлен, равно как и не следует пытаться интерпретировать или разбирать его.

Перенос кэша учетной записи

При миграции с ADAL приложения обычно хранят userId ADAL, который не содержит identifier, необходимый MSAL. В качестве однократного шага миграции приложение может запрашивать учетную запись MSAL с помощью идентификатора пользователя ADAL со следующим API:

- (nullable MSALAccount *)accountForUsername:(nonnull NSString *)username error:(NSError * _Nullable __autoreleasing * _Nullable)error;

Этот API считывает кэши MSAL и ADAL, чтобы найти учетную запись по userId пользователя ADAL (UPN).

Если учетная запись найдена, разработчик должен использовать эту учетную запись, чтобы получить токен без вмешательства пользователя. Первое получение токена в фоновом режиме фактически обновит учетную запись, и разработчик получит в результате MSAL совместимый с MSAL идентификатор учетной записи (identifier). После этого для поиска учетных записей следует использовать только identifier, используя следующий API:

- (nullable MSALAccount *)accountForIdentifier:(nonnull NSString *)identifier error:(NSError * _Nullable __autoreleasing * _Nullable)error;

Хотя в MSAL можно продолжать использовать ADAL userId для всех операций, userId основан на UPN, поэтому он имеет ряд ограничений, которые негативно сказываются на пользовательском опыте. Например, если UPN меняется, пользователь должен снова войти в систему. Мы рекомендуем всем приложениям использовать не отображаемую учетную запись identifier для всех операций.

Подробнее о миграции состояния кэша.

Изменения в получении токенов

MSAL вносит некоторые изменения в вызовы получения токенов:

  • Как и ADAL, acquireTokenSilent всегда приводит к выполнению запроса без участия пользователя.
  • В отличие от ADAL, acquireToken всегда вызывает отображение интерфейса, требующего действий со стороны пользователя, либо через веб-представление, либо через приложение Microsoft Authenticator. В зависимости от состояния единого входа в webview/Microsoft Authenticator пользователю может потребоваться ввести свои учетные данные.
  • В ADAL acquireToken с AD_PROMPT_AUTO сначала пытается получить маркер без вывода пользовательского интерфейса и показывает интерфейс только в том случае, если этот запрос завершается неудачей. В MSAL эту логику можно реализовать, сначала вызвав acquireTokenSilent, и вызывать acquireToken только в том случае, если тихое получение токена завершается неудачей. Это позволяет разработчикам настраивать пользовательский интерфейс перед началом интерактивного получения токена.

Различия в обработке ошибок

MSAL обеспечивает более четкость между ошибками, которые могут обрабатываться приложением и теми, которые требуют вмешательства пользователя. Разработчик должен обрабатывать ограниченное количество ошибок:

  • MSALErrorInteractionRequired: пользователь должен выполнить интерактивный запрос. Это может быть вызвано различными причинами, например: истек срок действия сеанса аутентификации, изменилась политика условного доступа, истек срок действия токена обновления или он был отозван, в кэше отсутствуют действительные токены и т. д.
  • MSALErrorServerDeclinedScopes: Запрос не был полностью выполнен, и для некоторых областей доступа не был предоставлен доступ. Это может быть вызвано отказом пользователя от согласия на одну или несколько областей.

Обработка всех остальных ошибок в спискеMSALError необязательна. Эти ошибки можно использовать для улучшения взаимодействия с пользователем.

Дополнительные сведения об обработке ошибок MSAL см. в разделе Обработка исключений и ошибок с помощью MSAL.

Поддержка брокера

MSAL, начиная с версии 0.3.0, обеспечивает поддержку проверки подлинности через брокер с помощью приложения Microsoft Authenticator. Microsoft Authenticator также обеспечивает поддержку сценариев условного доступа. В число примеров сценариев условного доступа входят политики соответствия устройств, которые требуют, чтобы пользователь зарегистрировал устройство через Intune или зарегистрировался в Microsoft Entra ID для получения токена. И политики условного доступа для управления мобильными приложениями (MAM), которые требуют подтверждения соответствия, прежде чем приложение сможет получить маркер.

Чтобы включить брокер для приложения, выполните приведенные действия.

  1. Зарегистрируйте формат URI перенаправления, совместимый с брокером, для приложения. URI перенаправления, совместимый с брокером, имеет формат msauth.<app.bundle.id>://auth. Замените <app.bundle.id> идентификатором пакета приложения. Если вы переходите с ADAL и ваше приложение уже поддерживало работу через брокер, вам не нужно делать ничего дополнительно. Предыдущий URI перенаправления полностью совместим с MSAL, поэтому вы можете перейти к шагу 3.

  2. Добавьте схему URI перенаправления приложения в файл info.plist. Для URI перенаправления MSAL по умолчанию используется msauth.<app.bundle.id>формат. Рассмотрим пример.

    <key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>

  3. Добавьте следующие схемы в файл Info.plist вашего приложения в раздел LSApplicationQueriesSchemes:

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

  4. Добавьте следующий код в файл AppDelegate.m для обработки обратных вызовов: Objective-C:

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

    Swift:

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

B2B (бизнес-бизнес)

В ADAL вы создаёте отдельные экземпляры ADAuthenticationContext для каждого арендатора, для которого приложение запрашивает токены. Это больше не обязательно в MSAL. В MSAL можно создать один экземпляр MSALPublicClientApplication и использовать его для любого облака Microsoft Entra и любой организации, указывая другой центр авторизации при вызовах acquireToken и acquireTokenSilent.

SSO в сочетании с другими SDK

MSAL для iOS может обеспечивать единый вход в систему (SSO) через общий кэш с ADAL Objective-C 2.7.x+.

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

SSO с общим хранилищем ключей iOS — единственный тип тихого SSO.

В macOS MSAL может обеспечивать единый вход с другими приложениями для iOS и macOS, использующими MSAL, а также с приложениями, использующими ADAL Objective-C.

MSAL на iOS также поддерживает два других типа единого входа:

  • Единый вход через веб-браузер. MSAL для iOS поддерживает ASWebAuthenticationSession, который обеспечивает единый вход с помощью файлов cookie, общих для других приложений на устройстве и, в частности, браузера Safari.
  • SSO через брокер аутентификации. На устройстве iOS Microsoft Authenticator выступает в качестве брокера проверки подлинности. Он может следовать политикам условного доступа, таким как требование соответствующего устройства, и предоставляет единый вход для зарегистрированных устройств. Пакеты SDK MSAL, начиная с версии 0.3.0, поддерживают брокер по умолчанию.

Intune MAM SDK

Пакет SDK для Intune MAM поддерживает MSAL для iOS, начиная с версии 11.1.2

MSAL и ADAL в одном приложении

ADAL версии 2.7.0 и выше не может сосуществовать с MSAL в одном приложении. Основная причина заключается в общем коде совместно используемого подмодуля. Так как Objective-C не поддерживает пространства имен, при добавлении платформ ADAL и MSAL в приложение будет два экземпляра одного класса. Нет никакой гарантии, какой именно будет выбран во время выполнения. Если оба пакета SDK используют одну и ту же версию конфликтующего класса, приложение может по-прежнему работать. Однако если это другая версия, ваше приложение может столкнуться с непредвиденными сбоями, которые сложно диагностировать.

Запуск ADAL и MSAL в том же рабочем приложении не поддерживается. Однако если вы просто тестируете и переносите пользователей из ADAL Objective-C в MSAL для iOS и macOS, вы можете продолжать использовать ADAL Objective-C 2.6.10. Это единственная версия, которая работает с MSAL в одном приложении. Для этой версии ADAL не будет новых обновлений компонентов, поэтому его следует использовать только для миграции и тестирования. Ваше приложение не должно в долгосрочной перспективе полагаться на сосуществование ADAL и MSAL.

Сосуществование ADAL и MSAL в одном приложении не поддерживается. Сосуществование ADAL и MSAL между несколькими приложениями полностью поддерживается.

Практические шаги по миграции

Миграция регистрации приложений

Вам не нужно изменять существующее приложение Microsoft Entra, чтобы переключиться на MSAL и включить учетные записи Microsoft Entra. Однако, если приложение, использующее ADAL, не поддерживает брокерную аутентификацию, перед тем как вы сможете перейти на MSAL, необходимо зарегистрировать для него новый URI перенаправления.

URI перенаправления должен иметь следующий формат: msauth.<app.bundle.id>://auth. Замените <app.bundle.id> идентификатором пакета приложения. Укажите URI перенаправления в Центр администрирования Microsoft Entra.

Только для iOS: для поддержки аутентификации на основе сертификатов необходимо зарегистрировать в приложении и в центре администрирования Microsoft Entra дополнительный URI перенаправления в следующем формате: msauth://code/<broker-redirect-uri-in-url-encoded-form> Например: msauth://code/msauth.com.microsoft.mybundleId%3A%2F%2Fauth

Мы рекомендуем всем приложениям зарегистрировать оба URI перенаправления.

Если вы хотите добавить поддержку поэтапного согласия, выберите API и разрешения, доступ к которым настроено запрашивать ваше приложение, в регистрации приложения на вкладке Разрешения API.

Если вы выполняете миграцию из ADAL и хотите поддерживать как Microsoft Entra ID, так и учетные записи MSA, необходимо обновить существующую регистрацию приложения для поддержки обоих. Мы не рекомендуем обновить существующее рабочее приложение, чтобы сразу поддерживать как Microsoft Entra ID, так и MSA. Вместо этого создайте другой идентификатор клиента, поддерживающий как Microsoft Entra ID, так и MSA для тестирования, а затем убедившись, что все сценарии работают, обновите существующее приложение.

Добавьте MSAL в ваше приложение

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

Обновление файла Info.plist приложения

Только для iOS добавьте схему URI перенаправления вашего приложения в файле info.plist. Для приложений, совместимых с брокером ADAL, это уже должно быть доступно. Схема URI перенаправления MSAL по умолчанию будет иметь следующий формат: msauth.<app.bundle.id>

<key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>

Добавьте следующие схемы в Info.plist вашего приложения под LSApplicationQueriesSchemes.

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

Обновление кода AppDelegate

Только для iOS добавьте в файл AppDelegate.m следующее:

Objective-C.

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

Swift:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Если вы используете Xcode 11, следует вместо этого поместить обработчик обратного вызова MSAL в файл SceneDelegate. Если вы поддерживаете UISceneDelegate и UIApplicationDelegate для совместимости с более старыми версиями iOS, вызов MSAL необходимо поместить в оба файла.

Objective-C.

 - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
 {
     UIOpenURLContext *context = URLContexts.anyObject;
     NSURL *url = context.URL;
     NSString *sourceApplication = context.options.sourceApplication;
     
     [MSALPublicClientApplication handleMSALResponse:url sourceApplication:sourceApplication];
 }

Swift:

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        
        guard let urlContext = URLContexts.first else {
            return
        }
        
        let url = urlContext.url
        let sourceApp = urlContext.options.sourceApplication
        
        MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
    }

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

Включить кэширование токенов

По умолчанию MSAL кэширует маркеры приложения в цепочке ключей iOS или macOS.

Чтобы включить кэширование токенов:

  1. Убедитесь, что приложение правильно подписано
  2. Перейдите в настройки проекта Xcode >на вкладку «Возможности»>Включите общий доступ к связке ключей
  3. Щелкните + и введите следующую запись в поле Keychain Groups: 3.a Для iOS введите com.microsoft.adalcache 3.b Для macOS введите com.microsoft.identity.universalstorage

Создайте MSALPublicClientApplication и переключитесь на вызовы acquireToken и acquireTokeSilent

Можно создать MSALPublicClientApplication с помощью следующего кода:

Objective-C.

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

Swift:

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
do {
  let application = try MSALPublicClientApplication(configuration: config)
  // continue on with application
            
} catch let error as NSError {
  // handle error here
}

Затем вызовите API управления учетными записями, чтобы узнать, есть ли в кэше какие-либо учетные записи:

Objective-C.

NSString *accountIdentifier = nil /*previously saved MSAL account identifier */;
NSError *error = nil;
MSALAccount *account = [application accountForIdentifier:accountIdentifier error:&error];

Swift:

// definitions that need to be initialized
let application: MSALPublicClientApplication!
let accountIdentifier: String! /*previously saved MSAL account identifier */

do {
  let account = try application.account(forIdentifier: accountIdentifier)
  // continue with account usage
} catch let error as NSError {
  // handle error here
}

или прочитайте все описания:

Objective-C.

NSError *error = nil;
NSArray<MSALAccount *> *accounts = [application allAccounts:&error];

Swift:

let application: MSALPublicClientApplication!
do {
  let accounts = try application.allAccounts()
  // continue with account usage
} catch let error as NSError {
  // handle error here
}

Если учетная запись найдена, вызовите API MSAL acquireTokenSilent :

Objective-C.

MSALSilentTokenParameters *silentParameters = [[MSALSilentTokenParameters alloc] initWithScopes:@[@"<your-resource-here>/.default"] account:account];
    
[application acquireTokenSilentWithParameters:silentParameters
                              completionBlock:^(MSALResult *result, NSError *error)
{
    if (result)
    {
        NSString *accessToken = result.accessToken;
        // Use your token
    }
    else
    {
        // Check the error
        if ([error.domain isEqual:MSALErrorDomain] && error.code == MSALErrorInteractionRequired)
        {
            // Interactive auth will be required
        }
            
        // Other errors may require trying again later, or reporting authentication problems to the user
    }
}];

Swift:

let application: MSALPublicClientApplication!
let account: MSALAccount!
        
let silentParameters = MSALSilentTokenParameters(scopes: ["<your-resource-here>/.default"], 
                                                 account: account)
application.acquireTokenSilent(with: silentParameters) {
  (result: MSALResult?, error: Error?) in
  if let accessToken = result?.accessToken {
     // use accessToken
  }
  else {
    // Check the error
    guard let error = error else {
      assert(true, "callback should contain a valid result or error")
      return
    }
    
    let nsError = error as NSError
    if (nsError.domain == MSALErrorDomain
        && nsError.code == MSALError.interactionRequired.rawValue) {
      // Interactive auth will be required
    }
                
    // Other errors may require trying again later, or reporting authentication problems to the user
  }
}

Дальнейшие действия

Дополнительные сведения о потоках проверки подлинности и сценариях приложений

  • Last updated on