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

Статья
10/24/2023

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

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

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

Платформа	Проект на сайте GitHub	Пакет	Получение из этих вариантов	Общедоступная версия (GA) или Общедоступная предварительная версия¹
Android (Java)	MSAL Android	MSAL	Краткое руководство	Общедоступная версия
Android (Kotlin)	MSAL Android	MSAL	—	Общедоступная версия
iOS (Swift/Obj-C)	MSAL для iOS и macOS	MSAL	Руководство	Общедоступная версия
Xamarin (.NET)	MSAL для .NET	Microsoft.Identity.Client	—	Общедоступная версия

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

Создание экземпляра приложения

Android

Мобильные приложения используют класс 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.

Xamarin или UWP

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

Создание экземпляра приложения

В Xamarin или 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, см. в справочной документации.

Задачи для Xamarin iOS

При использовании MSAL.NET в Xamarin iOS выполните следующие задачи.

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

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

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

Задачи для Xamarin.Android

При использовании Xamarin.Android выполните следующие задачи:

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

Рекомендации по работе с браузерами в Android см. в разделе Рекомендации касательно Xamarin.Android при использовании MSAL.NET.

Задачи для UWP

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

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

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

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

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

Включение брокера в Xamarin

Чтобы включить брокер в Xamarin, используйте параметр WithBroker() при вызове метода PublicClientApplicationBuilder.CreateApplication. По умолчанию для .WithBroker() установлено значение true.

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

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

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

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

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

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

Включение проверки подлинности через брокер для Xamarin iOS

Выполните шаги, описанные в этом разделе, чтобы разрешить приложению Xamarin.iOS взаимодействовать с приложением Microsoft Authenticator.

Шаг 1. Включение поддержки брокера

По умолчанию поддержка брокера отключена. Ее можно включить для отдельного класса PublicClientApplication. При создании класса PublicClientApplication с помощью PublicClientApplicationBuilder используйте параметр WithBroker(). Для параметра WithBroker() по умолчанию задается значение true.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

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

Когда MSAL.NET вызывает брокер, он отправляет обратный вызов в приложение. Брокер отправляет обратный вызов, применяя метод AppDelegate.OpenUrl. Так как MSAL ожидает ответ от брокера, приложение должно взаимодействовать для отправки обратного вызова в MSAL.NET. Это поведение настраивается путем обновления файла AppDelegate.cs для переопределения метода, как показано в следующем коде.

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
 if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
 {
  AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
  return true;
 }
 else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
 {
  return false;
 }
 return true;
}

Этот метод вызывается при каждом запуске приложения. Это дает возможность обработать ответ от брокера и завершить процесс проверки подлинности, запущенный MSAL.NET.

Шаг 3. Настройка UIViewController()

Для Xamarin iOS обычно не требуется настраивать окно объекта. Но в этом случае его следует настроить, чтобы можно было отправлять и получать ответы от брокера. Чтобы настроить окно объекта в AppDelegate.cs, необходимо задать ViewController.

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

В AppDelegate.cs задайте App.RootViewController в новом UIViewController(). Этот параметр обеспечивает включение UIViewController в вызов брокеру. Если он задан неправильно, может появиться следующее сообщение об ошибке:

"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker."
В вызове AcquireTokenInteractive используйте .WithParentActivityOrWindow(App.RootViewController). Передайте ссылку в окно объекта, которое вы будете использовать. Приведем пример:

В App.cs:
```
   public static object RootViewController { get; set; }
```
В AppDelegate.cs:
```
   LoadApplication(new App());
   App.RootViewController = new UIViewController();
```
В вызове AcquireToken:
```
result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();
```

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

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

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

Добавьте в CFBundleURLSchemes префикс msauth.
Добавьте CFBundleURLName в конце. Используйте следующий шаблон:

$"msauth.(BundleId)"

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

Эта схема URL-адресов станет частью URI перенаправления, который является уникальным идентификатором вашего приложения при получении ответа брокера.
```
 <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.xforms</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>msauth.com.yourcompany.xforms</string>
        </array>
      </dict>
    </array>
```

Шаг 5. Добавление в раздел LSApplicationQueriesSchemes

MSAL использует –canOpenURL: для проверки того, установлен ли брокер на устройстве. В iOS 9 компания Apple заблокировала схемы, которые может запрашивать приложение.

Добавьте msauthv2 в раздел LSApplicationQueriesSchemes файла Info.plist, как показано в следующем примере кода:

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

Проверка подлинности через брокер для 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.

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

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

$"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, если оно установлено.

Примечание.

Схема msauthv3 необходима, если сборка приложения выполняется с помощью Xcode 11 или более поздней версии.

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

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

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

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

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

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

Share via

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

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

Создание экземпляра приложения

Android

iOS

Xamarin или UWP

Создание экземпляра приложения

Указание родительского пользовательского интерфейса, окна или действия

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

Задачи для Xamarin iOS

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

Задачи для Xamarin.Android

Задачи для UWP

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

Включение брокера в Xamarin

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

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

Включение проверки подлинности через брокер для Xamarin iOS

Шаг 1. Включение поддержки брокера

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

Шаг 3. Настройка UIViewController()

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

Шаг 5. Добавление в раздел LSApplicationQueriesSchemes

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

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

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

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

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

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

Дополнительные ресурсы