Menggunakan Microsoft Authenticator atau Intune Company Portal pada aplikasi Xamarin

Artikel
10/24/2023

Di Android dan iOS, broker seperti Microsoft Authenticator dan Microsoft Intune Company Portal khusus Android mengaktifkan:

Akses menyeluruh (SSO): Pengguna tidak perlu masuk ke setiap aplikasi.
Identifikasi perangkat: Broker mengakses sertifikat perangkat. Sertifikat ini dibuat pada perangkat ketika bergabung ke tempat kerja.
Verifikasi identifikasi aplikasi: Ketika aplikasi memanggil broker, aplikasi melewati URL pengalihannya. Broker memverifikasi URL.

Untuk mengaktifkan salah satu fitur ini, gunakan parameter WithBroker() saat Anda memanggil metode PublicClientApplicationBuilder.CreateApplication ini. Parameter .WithBroker() diatur ke true secara default.

Penyiapan autentikasi menggunakan broker di Microsoft Authentication Library untuk .NET (MSAL.NET) bervariasi menurut platform:

Aplikasi iOS
Aplikasi Android

Autentikasi menggunakan broker untuk iOS

Gunakan langkah-langkah berikut untuk mengaktifkan aplikasi Xamarin.iOS Anda untuk berkomunikasi dengan aplikasi Microsoft Authenticator. Jika Anda menargetkan iOS 13, pertimbangkan untuk membaca tentang perubahan API pemutus Apple.

Langkah 1: Aktifkan dukungan broker

Anda harus mengaktifkan dukungan broker untuk masing-masing contoh PublicClientApplication. Dukungan dinonaktifkan secara default. Saat Anda membuat PublicClientApplication melalui PublicClientApplicationBuilder, gunakan parameter WithBroker() seperti yang ditunjukkan pada contoh berikut. Parameter WithBroker() diatur ke true secara default.

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

Langkah 2: Aktifkan akses rantai kunci

Untuk mengaktifkan akses rantai kunci, Anda harus memiliki grup akses rantai kunci untuk aplikasi Anda. Anda dapat menggunakan API WithIosKeychainSecurityGroup() untuk mengatur grup akses rantai kunci saat membuat aplikasi:

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

Untuk informasi selengkapnya, lihat Mengaktifkan akses rantai kunci.

Langkah 3: Perbarui AppDelegate untuk menangani panggilan balik

Ketika MSAL.NET memanggil broker, broker memanggil balik ke aplikasi Anda melalui metode OpenUrl kelas AppDelegate. Karena MSAL menunggu respons broker, aplikasi Anda harus bekerja sama untuk memanggil balik MSAL.NET. Untuk mengaktifkan kerja sama ini, perbarui file AppDelegate.cs untuk mengambil alih metode berikut.

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;
}

Metode ini dipanggil setiap kali aplikasi dimulai. Ini digunakan sebagai kesempatan untuk memproses respons dari broker dan menyelesaikan proses autentikasi yang telah dimulai MSAL.NET.

Langkah 4: Atur UIViewController()

Masih dalam file AppDelegate.cs, atur jendela objek. Anda biasanya tidak perlu mengatur jendela objek untuk Xamarin iOS, tetapi Anda memerlukan jendela objek untuk mengirim dan menerima respons dari broker.

Untuk menyiapkan jendela objek:

Di file AppDelegate.cs atur App.RootViewController ke UIViewController() baru. Tugas ini memastikan bahwa panggilan ke broker mencakup UIViewController. Jika penetapan pengaturan ini salah, Anda akan mendapatkan kesalahan ini:

"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker"

Pada panggilan AcquireTokenInteractive, gunakan .WithParentActivityOrWindow(App.RootViewController) lalu meluluskan referensi ke jendela objek yang akan Anda gunakan.

Di App.cs:

   public static object RootViewController { get; set; }

Di AppDelegate.cs:

   LoadApplication(new App());
   App.RootViewController = new UIViewController();

Dalam panggilan AcquireToken:

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

Langkah 5: Daftarkan skema URL

MSAL.NET menggunakan URL untuk memanggil broker, lalu mengembalikan respons broker ke aplikasi Anda. Untuk menyelesaikan komunikasi dua arah, daftarkan skema URL untuk aplikasi Anda di file Info.plist.

Nama CFBundleURLSchemes harus menyertakan msauth. sebagai awalan. Ikuti awalan dengan CFBundleURLName.

Dalam skema URL, BundleId secara unik mengidentifikasi aplikasi: $"msauth.(BundleId)". Jadi jika BundleId adalah com.yourcompany.xforms, maka skema URL-nya adalah msauth.com.yourcompany.xforms.

Catatan

Skema URL ini menjadi bagian dari URI pengalihan, yang secara unik mengidentifikasi aplikasi ketika menerima respons dari broker.

 <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>

Langkah 6: Tambahkan pengidentifikasi broker ke bagian LSApplicationQueriesSchemes

MSAL menggunakan –canOpenURL: untuk memeriksa apakah broker diinstal pada perangkat. Di iOS 9, Apple mengunci skema yang dapat dikueri oleh aplikasi.

Tambahkan msauthv2 ke bagian LSApplicationQueriesSchemes dari file Info.plist, seperti dalam contoh berikut:

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

Langkah 7: Tambahkan URI pengalihan ke pendaftaran aplikasi Anda

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Ketika Anda menggunakan broker, URI pengalihan Anda memiliki persyaratan tambahan. URI pengalihan harus memiliki format berikut:

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

Berikut contohnya:

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

Perhatikan bahwa URI pengalihan cocok dengan nama CFBundleURLSchemes yang Anda sertakan dalam file Info.plist.

Tambahkan URI pengalihan ke pendaftaran aplikasi. Untuk menghasilkan URI pengalihan yang diformat dengan benar, gunakan Pendaftaran aplikasi untuk menghasilkan URI pengalihan broker dari ID bundel.

Untuk menghasilkan URI pengalihan:

Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
Cari dan pilih aplikasi.
Pilih Autentikasi>Tambahkan platform>iOS / macOS
Masukkan ID bundel Anda, lalu pilih Konfigurasikan.

Salin URI pengalihan yang dihasilkan yang muncul di kotak URI Pengalihan untuk disertakan dalam kode Anda:
Pilih Selesai untuk menyelesaikan pembuatan URI pengalihan.

Autentikasi menggunakan broker untuk Android

Langkah 1: Aktifkan dukungan broker

Dukungan broker diaktifkan basis per-PublicClientApplication. Ini dinonaktifkan secara default. Gunakan parameter WithBroker() (diatur ke true secara default) saat membuat IPublicClientApplication melalui PublicClientApplicationBuilder.

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

Langkah 2: Perbarui aktivitas utama untuk menangani panggilan balik

Ketika MSAL.NET memanggil broker, broker akan pada gilirannya memanggil bali ke aplikasi Anda dengan metode OnActivityResult(). Karena MSAL akan menunggu respons dari broker, aplikasi Anda perlu merutekan hasilnya ke MSAL.NET.

Merutekan hasil ke metode SetAuthenticationContinuationEventArgs(int requestCode, Result resultCode, Intent data) dengan mengambil alih metode OnActivityResult() seperti yang ditunjukkan di sini:

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

Metode ini dipanggil setiap kali aplikasi broker diluncurkan, dan digunakan sebagai kesempatan untuk memproses respons dari broker, dan menyelesaikan proses autentikasi yang dimulai oleh MSAL.NET.

Langkah 3: Mengatur Aktivitas

Untuk mengaktifkan autentikasi menggunakan broker, atur aktivitas sehingga MSAL dapat mengirim dan menerima respons ke dan dari broker. Untuk melakukannya, berikan aktivitas (biasanya ke MainActivity) ke WithParentActivityOrWindow(object parent) objek induk.

Misalnya, dalam panggilan ke AcquireTokenInteractive():

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

Langkah 4: Tambahkan URI pengalihan ke pendaftaran aplikasi Anda

MSAL menggunakan URL untuk memanggil broker lalu kembali ke aplikasi Anda. Untuk menyelesaikan perjalanan pulang pergi tersebut, daftarkan URI Pengalihan untuk aplikasi Anda.

Format URI pengalihan untuk aplikasi Anda tergantung pada sertifikat yang digunakan untuk menandatangani APK. Misalnya:

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

Bagian terakhir dari URI, hgbUYHVBYUTvuvT&Y6tr554365466=, adalah versi tanda tangan yang dikodekan Base64 yang digunakan untuk menandatangani APK. Saat mengembangkan aplikasi di Visual Studio, jika Anda menelusuri kesalahan kode tanpa menandatangani APK dengan sertifikat tertentu, Visual Studio akan menandatangani APK untuk Anda untuk tujuan penelusuran kesalahan. Saat Visual Studio menandatangani APK untuk Anda dengan cara ini, ini akan memberi tanda tangan unik untuk komputer yang dibangunnya. Dengan demikian, setiap kali Anda membuat aplikasi di komputer yang berbeda, Anda harus memperbarui URI pengalihan dalam kode aplikasi dan pendaftaran aplikasi untuk mengautentikasi dengan MSAL.

Saat menelusuri kesalahan, Anda mungkin menemukan pengecualian MSAL (atau pesan log) yang menyatakan URI pengalihan yang disediakan salah. Pengecualian atau pesan log juga menunjukkan URI pengalihan yang seharusnya digunakan dengan komputer saat ini yang Anda telusuri kesalahannya. Anda dapat menggunakan URI pengalihan yang disediakan untuk terus mengembangkan aplikasi selama Anda memperbarui URI pengalihan dalam kode dan menambahkan URI pengalihan yang disediakan ke pendaftaran aplikasi.

Setelah Anda siap untuk menyelesaikan kode Anda, perbarui URI pengalihan dalam kode dan pendaftaran aplikasi untuk menggunakan tanda tangan sertifikat yang Anda tanda tangani APK.

Dalam praktiknya, ini berarti Anda harus mempertimbangkan menambahkan URI pengalihan untuk setiap anggota tim pengembangan Anda, ditambah URI pengalihan untuk versi APK yang ditandatangani produksi.

Anda dapat mengkomputasi tanda tangan sendiri, mirip dengan bagaimana MSAL melakukannya:

   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.
      }
   }

Anda juga memiliki opsi untuk mendapatkan tanda tangan untuk paket Anda menggunakan keytool dengan perintah berikut:

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

Langkah 5 (opsional): Kembali ke browser sistem

Jika MSAL dikonfigurasi untuk menggunakan broker tetapi broker tidak diinstal, MSAL akan kembali menggunakan tampilan web (browser). MSAL akan mencoba mengautentikasi menggunakan browser sistem default pada perangkat, yang gagal karena URI pengalihan dikonfigurasi untuk broker dan browser sistem tidak tahu cara menggunakannya untuk mengarahkan kembali ke MSAL. Untuk menghindari kegagalan, Anda dapat mengonfigurasi filter tujuan dengan broker URI pengalihan yang Anda gunakan di langkah 4.

Mengubah manifes aplikasi Anda untuk menambahkan filter tujuan:

<!-- 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"/>

Misalnya, jika Anda memiliki URI pengalihan msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=, manifes Anda akan terlihat seperti cuplikan XML berikut.

Garis miring (/) di depan tanda tangan dalam nilai android:path yang dibutuhkan.

<!-- 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="/>

Untuk informasi selengkapnya tentang mengonfigurasi aplikasi Anda untuk browser sistem dan dukungan Android 11, lihat Memperbarui manifes Android untuk dukungan browser sistem.

Sebagai alternatif, Anda dapat mengonfigurasi MSAL untuk kembali ke browser tersemat, yang tidak bergantung pada URI pengalihan:

.WithUseEmbeddedWebUi(true)

Tips pemecahan masalah untuk autentikasi menggunakan broker Android

Berikut adalah beberapa tips untuk menghindari masalah saat Anda menerapkan autentikasi menggunakan broker di Android:

URI Pengalihan - Tambahkan URI pengalihan ke pendaftaran aplikasi Anda. URI pengalihan yang hilang atau salah adalah masalah umum yang dihadapi oleh pengembang.
Versi broker - Instal versi minimum yang diperlukan aplikasi broker. Salah satu dari kedua aplikasi ini dapat digunakan untuk autentikasi menggunakan broker di Android.
- Intune Company Portal (versi 5.0.4689.0 atau lebih tinggi)
- Microsoft Authenticator (versi 6.2001.0140 atau lebih tinggi).
Broker prioritas - MSAL berkomunikasi dengan broker pertama yang diinstal pada perangkat ketika beberapa broker diinstal.

Contoh: Jika Anda pertama kali menginstal Microsoft Authenticator lalu menginstal Intune Company Portal, autentikasi menggunakan broker hanya akan terjadi pada Microsoft Authenticator.
Log - Jika Anda mengalami masalah dengan autentikasi menggunakan broker, dengan melihat log broker mungkin membantu Anda mendiagnosis penyebabnya.
- Dapatkan log Microsoft Authenticator:
  1. Pilih tombol menu di sudut kanan atas aplikasi.
  2. Pilih Kirim Umpan Balik>Mengalami Masalah?.
  3. Pada Apa yang anda coba lakukan?, pilih opsi untuk menambahkan deskripsi.
  4. Untuk mengirim log, pilih tanda panah di sudut kanan atas aplikasi.
  Setelah Anda mengirim log, kotak dialog menampilkan ID insiden. Catat ID insiden, dan sertakan saat Anda meminta bantuan.
- Mendapatkan log Intune Company Portal:
  1. Pilih tombol menu di sudut kiri atas aplikasi.
  2. Pilih Bantuan>Dukungan Email.
  3. Untuk mengirim log, pilih Hanya Unggah Log.
  Setelah Anda mengirim log, kotak dialog menampilkan ID insiden. Catat ID insiden, dan sertakan saat Anda meminta bantuan.

Langkah berikutnya

Pelajari tentang Pertimbangan untuk menggunakan Universal Windows Platform dengan MSAL.NET.

Menggunakan Microsoft Authenticator atau Intune Company Portal pada aplikasi Xamarin

Autentikasi menggunakan broker untuk iOS

Langkah 1: Aktifkan dukungan broker

Langkah 2: Aktifkan akses rantai kunci

Langkah 3: Perbarui AppDelegate untuk menangani panggilan balik

Langkah 4: Atur UIViewController()

Langkah 5: Daftarkan skema URL

Langkah 6: Tambahkan pengidentifikasi broker ke bagian LSApplicationQueriesSchemes

Langkah 7: Tambahkan URI pengalihan ke pendaftaran aplikasi Anda

Autentikasi menggunakan broker untuk Android

Langkah 1: Aktifkan dukungan broker

Langkah 2: Perbarui aktivitas utama untuk menangani panggilan balik

Langkah 3: Mengatur Aktivitas

Langkah 4: Tambahkan URI pengalihan ke pendaftaran aplikasi Anda

Langkah 5 (opsional): Kembali ke browser sistem

Tips pemecahan masalah untuk autentikasi menggunakan broker Android

Langkah berikutnya

Sumber Daya Tambahan: