Бөлісу құралы:

Использование Microsoft Authenticator или корпоративного портала Intune в приложениях Xamarin

  • Мақала

В Android и iOS такими брокерами, как Microsoft Authenticator и корпоративный портал Microsoft Intune для Android, обеспечивается:

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

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

Настройка проверки подлинности через брокер в библиотеке проверки подлинности Майкрософт для .NET (MSAL.NET) зависит от платформы:

Примечание.

MSAL.NET версии 4.61.0 и выше не поддерживают универсальная платформа Windows (UWP), Xamarin Android и Xamarin iOS. Мы рекомендуем перенести приложения Xamarin в современные платформы, такие как MAUI. Дополнительные сведения о нерекомендуемом объявлении о предстоящей отмене MSAL.NET для Xamarin и UWP.

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

Чтобы разрешить взаимодействие приложения Xamarin.iOS с приложением Microsoft Authenticator, выполните следующие действия. Если вы ориентируетесь на iOS 13, рекомендуем ознакомиться с критическими изменениями API компании Apple.

Шаг 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. Разрешение доступа к цепочке ключей

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

var builder = PublicClientApplicationBuilder
     .Create(ClientId)
     .WithIosKeychainSecurityGroup("com.microsoft.adalcache")
     .Build();

Дополнительные сведения см. в разделе Разрешение доступа к цепочке ключей.

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

Когда MSAL.NET вызывает брокер, он отправляет обратный вызов в приложение с помощью метода OpenUrl класса AppDelegate. Так как 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.

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

Находясь в файле AppDelegate.cs, установите окно объекта. Обычно для Xamarin iOS устанавливать окно объекта не требуется, но оно необходимо для отправки и получения ответов от брокера.

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

  1. В файле 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"

  2. В вызове 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();

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

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

Имя CFBundleURLSchemes должно включать msauth. в качестве префикса. После префикса используйте CFBundleURLName.

В схеме URL-адресов BundleId является уникальным идентификатором приложения: $"msauth.(BundleId)". Таким образом, если для BundleId задано значение com.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>

Шаг 6. Добавление идентификатора брокера в раздел LSApplicationQueriesSchemes

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

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

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

Шаг 7. Добавление URI перенаправления в регистрацию приложения

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

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

$"msauth.{BundleId}://auth"

Приведем пример:

public static string redirectUriOnIos = "msauth.com.yourcompany.XForms://auth";

Обратите внимание, что URI перенаправления совпадает с именем CFBundleURLSchemes, включенным в файл Info.plist.

Добавьте URI перенаправления в регистрацию приложения. Чтобы создать правильный формат URI перенаправления, используйте Регистрация приложений для создания URI перенаправления через брокер из идентификатора пакета.

Для создания URI перенаправления выполните следующие действия:

  1. Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.

  2. Перейдите к приложениям> удостоверений>Регистрация приложений.

  3. Найдите и выберите приложение.

  4. Выберите Проверка подлинности>Добавить платформу>iOS / macOS.

  5. Введите идентификатор пакета и нажмите Настроить.

    Скопируйте созданный URI перенаправления, который отображается в текстовом поле URI перенаправления, для включения в код:

    Параметры платформы iOS с созданным URI перенаправления

  6. Нажмите Готово, чтобы завершить создание URI перенаправления.

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

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

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

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithRedirectUri(redirectUriOnAndroid) // See step #4
                .Build();

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

Когда MSAL.NET вызывает брокер, тот, в свою очередь, отправляет обратный вызов в приложение с использованием метода OnActivityResult(). Так как MSAL будет ждать ответ от брокера, приложению необходимо направить результат в MSAL.NET.

Направьте результат в метод SetAuthenticationContinuationEventArgs(int requestCode, Result resultCode, Intent data), переопределив метод OnActivityResult(), как показано ниже:

protected override void OnActivityResult(int requestCode, Result resultCode, Intent data)
{
   base.OnActivityResult(requestCode, resultCode, data);
   AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(requestCode, resultCode, data);
}

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

Шаг 3. Задание действия

Чтобы включить проверку подлинности через брокер, настройте действие таким образом, чтобы MSAL могла отправлять и получать ответ от брокера. Для этого укажите действие (обычно MainActivity) для родительского объекта WithParentActivityOrWindow(object parent).

Например, в вызове для AcquireTokenInteractive():

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow((Activity)context))
             .ExecuteAsync();

Шаг 4. Добавление URI перенаправления в регистрацию приложения

MSAL использует URL-адреса для вызова брокера и для последующего возврата ответа в приложение. Чтобы завершить это круглое путешествие, зарегистрируйте универсальный код ресурса (URI перенаправления) для приложения.

Формат URI перенаправления для приложения зависит от сертификата, используемого для подписи APK. Например:

msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=

Последняя часть URI, hgbUYHVBYUTvuvT&Y6tr554365466= — это версия сигнатуры в кодировке Base64, с помощью которой подписывается APK. Если при разработке приложения в Visual Studio отладка кода осуществляется без подписи APK с помощью определенного сертификата, Visual Studio подписывает для вас APK в целях отладки. Когда Visual Studio подписывает APK для вас таким способом, компьютеру, на котором выполняется его сборка, предоставляется уникальная подпись. Таким образом, каждый раз, когда вы создаете приложение на другом компьютере, необходимо обновить URI перенаправления в коде приложения и регистрации приложения для проверки подлинности с помощью MSAL.

При отладке можно столкнуться с исключением MSAL (или сообщением журнала), сообщающим, что указанный URI перенаправления неверен. Исключение или сообщение журнала также указывает URI перенаправления, который следует использовать с компьютером, где в данный момент выполняется отладка. Вы можете использовать предоставленный URI перенаправления для продолжения разработки приложения до тех пор, пока вы обновляете URI перенаправления в коде и добавляете предоставленный URI перенаправления в регистрацию приложения.

Когда вы будете готовы завершить код, обновите URI перенаправления в коде и регистрацию приложения, чтобы использовать подпись сертификата, с которым вы подписываете APK.

На практике это означает, что следует добавить URI перенаправления для каждого члена вашей команды разработчиков, а также URI перенаправления для версии APK, подписанной для рабочей среды.

Вы можете вычислить подпись самостоятельно аналогично тому, как это делает MSAL:

   private string GetRedirectUriForBroker()
   {
      string packageName = Application.Context.PackageName;
      string signatureDigest = this.GetCurrentSignatureForPackage(packageName);
      if (!string.IsNullOrEmpty(signatureDigest))
      {
            return string.Format(CultureInfo.InvariantCulture, "{0}://{1}/{2}", RedirectUriScheme,
               packageName.ToLowerInvariant(), signatureDigest);
      }

      return string.Empty;
   }

   private string GetCurrentSignatureForPackage(string packageName)
   {
      Android.Content.PM.Signature signature = null;
      if (Build.VERSION.SdkInt >= BuildVersionCodes.Tiramisu)
      {
          var packageInfo = Application.Context.PackageManager.GetPackageInfo(packageName, PackageManager.PackageInfoFlags.Of((long)PackageInfoFlags.SigningCertificates));
          if (packageInfo.SigningInfo != null)
          {
              var signatures = packageInfo.SigningInfo.GetApkContentsSigners();
              if (signatures != null && signatures.Length > 0)
                  signature = signatures[0];
          }
      }
      else
      {
#pragma warning disable CS0618 // Type or member is obsolete
          var packageInfo = Application.Context.PackageManager.GetPackageInfo(packageName, PackageInfoFlags.Signatures);
          if (packageInfo != null && packageInfo.Signatures != null && packageInfo.Signatures.Count > 0)
              signature = packageInfo.Signatures[0];
#pragma warning restore CS0618 // Type or member is obsolete
      }
    
      if (signature != null)
      {
          // First available signature. Applications can be signed with multiple signatures.
          // The order of Signatures is not guaranteed.
          var md = MessageDigest.GetInstance("SHA");
          md.Update(signature.ToByteArray());
          return Convert.ToBase64String(md.Digest(), Base64FormattingOptions.None);
          // Server side needs to register all other tags. ADAL will
          // send one of them.
      }
   }

Вы также можете получить подпись для пакета, используя keytool с помощью следующих команд:

  • Windows: 
    keytool.exe -list -v -keystore "%LocalAppData%\Xamarin\Mono for Android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
  • macOS: 
    keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

Шаг 5 (необязательно). Возврат в системный браузер

Если MSAL настроен для использования брокера, но брокер не установлен, MSAL вернется к использованию веб-представления (браузера). MSAL попытается пройти проверку подлинности с помощью системного браузера по умолчанию на устройстве, что завершится ошибкой, так как URI перенаправления настроен для использования брокера, а системному браузеру не известно, как использовать его для возврата в MSAL. Чтобы избежать этой ошибки, можно настроить фильтр намерений с помощью URI перенаправления брокера, который использовался на шаге 4.

Измените манифест приложения, чтобы добавить фильтр намерений:

<!-- NOTE the SLASH (required) that prefixes the signature value in the path attribute.
     The signature value is the Base64-encoded signature discussed above. -->
<intent-filter>
      <data android:scheme="msauth"
                    android:host="Package Name"
                    android:path="/Package Signature"/>

Например, если у вас есть URI перенаправления для msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=, манифест должен выглядеть как следующий фрагмент кода XML.

Перед подписью в значенииandroid:path требуется косая черта (/).

<!-- NOTE the SLASH (required) that prefixes the signature value in the path attribute.
     The signature value is the Base64-encoded signature discussed above. -->
<intent-filter>
      <data android:scheme="msauth"
                    android:host="com.microsoft.xforms.testApp"
                    android:path="/hgbUYHVBYUTvuvT&Y6tr554365466="/>

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

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

.WithUseEmbeddedWebUi(true)

Советы по устранению неполадок при проверке подлинности через брокер в Android

Ниже приведены несколько советов по предотвращению проблем при внедрении проверки подлинности через брокер в Android:

  • Универсальный код ресурса (URI перенаправления) — добавление URI перенаправления в регистрацию приложения. Отсутствующий или неверный URI перенаправления является распространенной проблемой, с которой сталкиваются разработчики.

  • Версия брокера: установите минимально необходимую версию приложений брокера. Для проверки подлинности через брокер в Android можно использовать одно из этих двух приложений.

  • Приоритет брокера: при установке нескольких брокеров MSAL взаимодействует с первым установленным на устройстве брокером.

    Например, если сначала установить Microsoft Authenticator, а затем — корпоративный портал Intune, то проверка подлинности через брокер будет выполняться только с помощью Microsoft Authenticator.

  • Журналы: при возникновении проблемы с проверкой подлинности через брокер просмотр журналов брокера может помочь в диагностике причины.

    • Получение журналов Microsoft Authenticator:

      1. Нажмите кнопку меню в правом верхнем углу приложения.
      2. Выберите Отправить отзыв>Возникли проблемы?.
      3. Под вопросом Что вы пытаетесь сделать? выберите вариант и добавьте описание.
      4. Чтобы отправить журналы, нажмите стрелку в правом верхнем углу приложения.

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

    • Получение журналов корпоративного портала Intune:

      1. Нажмите кнопку меню в левом верхнем углу приложения.
      2. Выберите Справка>Написать в поддержку.
      3. Чтобы отправить журналы, выберите Отправить только журналы.

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

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

См. Рекомендации по использованию универсальной платформы Windows с MSAL.NET.