Настройка мобильного приложения, вызывающего веб-API

Применяется к: Арендаторы рабочей области (дополнительные сведения)

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

Предпосылки

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно . Эта учетная запись должна иметь разрешения на управление приложениями. Используйте любую из следующих ролей, необходимых для регистрации приложения:
  • Администратор приложений
  • Разработчик приложения
• Зарегистрируйте новое приложение в Центре администрирования Microsoft Entra, настроенное только для учетных записей в этом каталоге организации. Дополнительные сведения см. в статье "Регистрация приложения ". Запишите следующие значения на странице обзора приложения для последующего использования:
  • Идентификатор приложения (клиента)
  • Идентификатор каталога (арендатора)

Добавьте URI перенаправления платформы

Чтобы указать тип приложения для регистрации приложения, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности>Добавить платформу>iOS/macOS.
2. Введите идентификатор пакета и нажмите кнопку "Настроить". URI перенаправления вычисляется для вас.

Если вы хотите настроить URI перенаправления вручную, это можно сделать с помощью манифеста приложения. Вот рекомендуемый формат манифеста:

• iOS:msauth.<BUNDLE_ID>://auth
  • Например, введите msauth.com.yourcompany.appName://auth.
• Андроид: msauth://<PACKAGE_NAME>/<SIGNATURE_HASH>
  • Хэш подписи Android можно создать, используя релизный ключ или ключ отладки с помощью команды KeyTool.

Включение публичного клиентского потока

Если приложение использует только проверку подлинности по имени пользователя и паролю, вам не нужно регистрировать для него URI перенаправления. Этот поток выполняет круговой путь к платформе удостоверений Майкрософт. Ваше приложение не получит обратного вызова на какой-либо конкретный URI. Но следует включить общедоступный поток клиента.

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

1. В разделе "Управление" выберите "Проверка подлинности".

2. В разделе "Дополнительные параметры" для параметра "Разрешить общедоступные потоки клиентов" нажмите кнопку "Да".

3. Выберите Сохранить, чтобы сохранить изменения.

Библиотеки Майкрософт, поддерживающие мобильные приложения

Мобильные приложения поддерживают следующие библиотеки Майкрософт:

Платформа	Проект в разработке GitHub	Пакет	Получение началось	Вход пользователей	Доступ к веб-API	Общедоступная версия (GA) или Общедоступная предварительная версия1
Android (Java)	MSAL Android	МСАЛ	Краткое руководство			Общедоступная версия
Android (Kotlin)	MSAL Android	МСАЛ	—			Общедоступная версия
iOS (Swift/Obj-C)	MSAL для iOS и macOS	МСАЛ	Руководство			Общедоступная версия

¹Универсальные условия лицензионного соглашения для веб-служб применяются к библиотекам в общедоступной предварительной версии.

Инстанцировать приложение

Андроид

Мобильные приложения используют класс PublicClientApplication. Вот как создать его экземпляр:

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Мобильным приложениям в iOS необходимо создать экземпляр класса MSALPublicClientApplication. Чтобы создать экземпляр класса, используйте следующий код.

NSError *msalError = nil;

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

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Дополнительные свойства MSALPublicClientApplicationConfig могут переопределить авторитет по умолчанию, указать URI перенаправления или изменить поведение кэширования токена MSAL.

UWP (Универсальная платформа Windows)

В этом разделе объясняется, как создать экземпляр приложения для приложений UWP.

Инстанцировать приложение

В UWP самый простой способ создания экземпляра приложения — использовать следующий код. В этом коде ClientId — это GUID зарегистрированного приложения.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Дополнительные методы With<Parameter> устанавливают родительский элемент пользовательского интерфейса, переопределяют полномочия по умолчанию, указывают имя и версию клиента для телеметрии, указывают URI перенаправления и фабрику HTTP для использования. Фабрика HTTP может использоваться, например, для работы с прокси-серверами, а также для указания телеметрии и ведения журнала.

В следующих разделах содержатся дополнительные сведения о создании приложения.

Определите родительский интерфейс, окно или действие

На Android перед осуществлением интерактивной проверки подлинности передайте родительскую активность. В iOS при использовании брокера передайте ViewController. Так же, как и в случае с UWP, может потребоваться передать родительское окно. Вы передаете его при получении маркера. Но при создании приложения можно также указать обратный вызов в качестве делегата, который возвращает UIParent.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

В Android рекомендуется использовать CurrentActivityPlugin. Получаемый код построителя PublicClientApplication выглядит как в следующем примере:

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

Ознакомление с дополнительными параметрами сборки приложений

Перечень всех методов, доступных в PublicClientApplicationBuilder, см. в Списке методов.

Описание всех параметров, предоставляемых в PublicClientApplicationOptions, см. в справочной документации.

Задачи для MSAL для iOS и macOS

Эти задачи необходимы при использовании MSAL для iOS и macOS:

• Реализуйте обратный вызов openURL
• Включение групп доступа цепочки ключей
• Настройка браузеров и WebViews

Задачи для UWP

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

Дополнительные сведения см. в разделе Рекомендации касательно UWP при использовании MSAL.NET.

Настройка приложения для использования брокера

В Android и iOS брокеры обеспечивают следующее:

• Единый вход (SSO) — вы можете использовать единый вход для устройств, зарегистрированных с идентификатором Microsoft Entra. При использовании SSO пользователям не нужно будет входить отдельно в каждое приложение.
• Идентификация устройства. Этот параметр включает политики условного доступа, связанные с устройствами Microsoft Entra. В процессе проверки подлинности используется сертификат устройства, созданный при подключении устройства к рабочему месту.
• Проверка идентификации приложения. Когда приложение вызывает брокер, ему передается URL-адрес перенаправления. Затем брокер проверяет его.

Включение брокера для MSAL для Android

Сведения о включении брокера в Android см. в статье Проверка подлинности через брокер в Android.

Включение брокера для MSAL для iOS и macOS

Аутентификация с брокером включена по умолчанию для сценариев Microsoft Entra в MSAL для iOS и macOS.

В следующих разделах приведены инструкции по настройке приложения для поддержки проверки подлинности с помощью брокера для iOS и macOS. В двух наборах инструкций некоторые шаги отличаются.

Проверка подлинности через брокер для MSAL для iOS и macOS

Аутентификация с брокером включена по умолчанию для сценариев Microsoft Entra.

Шаг 1. Обновление AppDelegate для обработки обратного вызова

Когда MSAL для iOS и macOS вызывает брокер, брокер выполняет обратный вызов к вашему приложению, используя метод openURL. Так как MSAL ожидает ответ от брокера, ваше приложение должно взаимодействовать с MSAL, чтобы инициировать обратный вызов. Эта возможность настраивается путем обновления файла AppDelegate.m для переопределения метода, как показано в следующем примере кода.

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

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

Если вы применяете UISceneDelegate в iOS 13 или более поздней версии, установите обратный вызов MSAL в scene:openURLContexts: вместо UISceneDelegate. MSAL handleMSALResponse:sourceApplication: должна вызываться только один раз для каждого URL-адреса.

Дополнительные сведения см. в документации Apple.

Шаг 2. Регистрация схемы URL-адреса

MSAL для iOS и macOS использует URL-адреса для вызова брокера и для последующего возврата ответа брокера в приложение. Чтобы завершить круговой путь, зарегистрируйте схему URL-адресов приложения в файле Info.plist.

Чтобы зарегистрировать схему для приложения, сделайте следующее:

1. Добавьте в пользовательскую схему URL-адресов префикс msauth.

2. Добавьте идентификатор пакета в конец схемы. Используйте следующий шаблон:

   $"msauth.(BundleId)"

   Здесь BundleId является уникальным идентификатором вашего устройства. Например, если BundleId присвоено значение yourcompany.xforms, то ваша схема URL-адресов будет msauth.com.yourcompany.xforms.

   Эта схема URL-адресов станет частью URI перенаправления, который является уникальным идентификатором вашего приложения при получении ответа брокера. Убедитесь, что URI перенаправления в формате msauth.(BundleId)://auth зарегистрирован для приложения.

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>msauth.[BUNDLE_ID]</string>
           </array>
       </dict>
   </array>
   

Шаг 3. Добавление LSApplicationQueriesSchemes

Добавьте LSApplicationQueriesSchemes , чтобы разрешить отправку вызовов в приложение Microsoft Authenticator, если оно установлено.

Ниже приведен пример добавления LSApplicationQueriesSchemes:

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

Следующие шаги

В этом сценарии перейдите к следующей статье — Получение токена.