Persyaratan konfigurasi dan tips pemecahan masalah untuk Xamarin Android dengan MSAL.NET

Artikel
07/16/2024

Ada beberapa perubahan konfigurasi yang harus Anda lakukan dalam kode Anda saat menggunakan Xamarin Android dengan Microsoft Authentication Library for .NET (MSAL.NET). Bagian berikut ini menjelaskan modifikasi yang diperlukan, diikuti dengan bagian Pemecahan Masalah untuk membantu Anda menghindari beberapa masalah yang paling umum.

Catatan

MSAL.NET versi 4.61.0 ke atas tidak memberikan dukungan untuk Platform Windows Universal (UWP), Xamarin Android, dan Xamarin iOS. Sebaiknya migrasikan aplikasi Xamarin Anda ke kerangka kerja modern seperti MAUI. Baca selengkapnya tentang penghentian dalam Mengumumkan Penghentian MSAL.NET mendatang untuk Xamarin dan UWP.

Mengatur aktivitas induk

Di Xamarin Android, atur aktivitas induk sehingga token kembali setelah interaksi:

var authResult = AcquireTokenInteractive(scopes)
 .WithParentActivityOrWindow(parentActivity)
 .ExecuteAsync();

Di MSAL.NET 4.2 dan yang lebih baru, Anda juga dapat mengatur fungsionalitas ini pada tingkat [PublicClientApplication][PublicClientApplication]. Untuk melakukannya, gunakan callback:

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

Jika Anda menggunakan CurrentActivityPlugin, kode pembuat [PublicClientApplication][PublicClientApplication] Anda akan terlihat mirip dengan cuplikan kode ini:

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

Pastikan kontrol tersebut kembali ke MSAL

Ketika bagian interaktif alur autentikasi berakhir, kembalikan kontrol ke MSAL dengan menimpa [Activity][Activity].[OnActivityResult()] Metode [OnActivityResult].

Dalam penimpaan Anda, panggil MSAL. NET' s AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs() metode untuk menampilkan kontrol ke MSAL di akhir bagian interaktif dari alur autentikasi.

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

    // Return control to MSAL
    AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(requestCode,
                                                                            resultCode,
                                                                            data);
}

Memperbarui manifes Android untuk dukungan System WebView

Untuk mendukung System WebView, file AndroidManifest.xml harus berisi nilai berikut:

<activity android:name="microsoft.identity.client.BrowserTabActivity" android:configChanges="orientation|screenSize" android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="msal{Client Id}" android:host="auth" />
  </intent-filter>
</activity>

Nilai android:scheme dibuat dari URI pengalihan yang dikonfigurasi di portal aplikasi. Misalnya, jika URI pengalihan Anda adalah msal00001111-aaaa-2222-bbbb-3333cccc4444://auth , entri android:scheme dalam manifes akan terlihat seperti contoh ini:

<data android:scheme="msal00001111-aaaa-2222-bbbb-3333cccc4444" android:host="auth" />

Atau, buat aktivitas dalam kode daripada secara manual mengedit AndroidManifest.xml. Untuk membuat aktivitas dalam kode, pertama-tama buat kelas yang menyertakan atribut Activity dan atribut IntentFilter.

Berikut ini contoh kelas yang mewakili nilai file XML:

  [Activity(Exported = true)]
  [IntentFilter(new[] { Intent.ActionView },
        Categories = new[] { Intent.CategoryBrowsable, Intent.CategoryDefault },
        DataHost = "auth",
        DataScheme = "msal{client_id}")]
  public class MsalActivity : BrowserTabActivity
  {
  }

Gunakan System WebView dalam autentikasi broker

Untuk menggunakan System WebView sebagai fallback untuk autentikasi interaktif ketika Anda telah mengonfigurasi aplikasi Anda untuk menggunakan autentikasi broker dan broker tidak terinstal di dalam perangkat, memungkinkan MSAL untuk menangkap respons autentikasi menggunakan URI pengalihan broker. MSAL akan mencoba mengautentikasi menggunakan System WebView default pada perangkat ketika mendeteksi bahwa broker tidak tersedia. Menggunakan default ini, itu akan gagal karena URI pengalihan dikonfigurasi untuk menggunakan broker, dan System WebView tidak tahu cara menggunakannya untuk kembali ke MSAL. Untuk mengatasinya, buat filter niat menggunakan URI pengalihan broker yang Anda konfigurasi sebelumnya. Tambahkan filter niat dengan memodifikasi manifes aplikasi Anda seperti contoh ini:

<!--Intent filter to capture System WebView or Authenticator calling back to our app after sign-in-->
<activity
      android:name="microsoft.identity.client.BrowserTabActivity">
    <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data android:scheme="msauth"
              android:host="Enter_the_Package_Name"
              android:path="/Enter_the_Signature_Hash" />
    </intent-filter>
</activity>

Ganti nama paket yang Anda daftarkan di portal Microsoft Azure untuk nilai android:host= tersebut. Ganti hash kunci yang Anda daftarkan di portal Microsoft Azure untuk nilai android:path= tersebut. Hash tanda tangan tidak boleh berupa URL yang terenkode. Pastikan bahwa garis miring ke depan (/) muncul di awal hash tanda tangan Anda.

Manifes Xamarin.Forms 4.3.x

Xamarin.Forms 4.3.x menghasilkan kode yang mengatur atribut package ke com.companyname.{appName} pada AndroidManifest.xml. Jika Anda menggunakan DataScheme sebagai msal{client_id}, maka Anda mungkin ingin mengubah nilai agar sesuai dengan nilai ruang nama MainActivity.cs.

Dukungan Android 11

Untuk menggunakan browser sistem dan autentikasi broker di Android 11, Anda harus terlebih dahulu mendeklarasikan paket-paket ini, sehingga terlihat oleh aplikasi. Aplikasi yang menargetkan Android 10 (API 29) dan yang lebih lama dapat meminta OS untuk daftar paket yang tersedia di perangkat pada waktu tertentu. Untuk mendukung privasi dan keamanan, Android 11 mengurangi visibilitas paket ke daftar default paket OS dan paket yang ditentukan dalam file AndroidManifest.xmldari aplikasi.

Untuk mengaktifkan aplikasi untuk mengautentikasi menggunakan browser sistem dan broker, tambahkan bagian berikut ke AndroidManifest.xml:

<!-- Required for API Level 30 to make sure the app can detect browsers and other apps where communication is needed.-->
<!--https://developer.android.com/training/basics/intents/package-visibility-use-cases-->
<queries>
  <package android:name="com.azure.authenticator" />
  <package android:name="{Package Name}" />
  <package android:name="com.microsoft.windowsintune.companyportal" />
  <!-- Required for API Level 30 to make sure the app detect browsers
      (that don't support custom tabs) -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" />
  </intent>
  <!-- Required for API Level 30 to make sure the app can detect browsers that support custom tabs -->
  <!-- https://developers.google.com/web/updates/2020/07/custom-tabs-android-11#detecting_browsers_that_support_custom_tabs -->
  <intent>
    <action android:name="android.support.customtabs.action.CustomTabsService" />
  </intent>
</queries>

Ganti {Package Name} dengan nama paket aplikasi.

Manifes Anda yang diperbarui, yang sekarang mencakup dukungan untuk browser sistem dan autentikasi broker, akan terlihat mirip dengan contoh ini:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.XamarinDev">
    <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="30" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <application android:theme="@android:style/Theme.NoTitleBar">
        <activity android:name="microsoft.identity.client.BrowserTabActivity" android:configChanges="orientation|screenSize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="msal00001111-aaaa-2222-bbbb-3333cccc4444" android:host="auth" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="msauth" android:host="com.companyname.XamarinDev" android:path="/Fc4l/5I4mMvLnF+l+XopDuQ2gEM=" />
            </intent-filter>
        </activity>
    </application>
    <!-- Required for API Level 30 to make sure we can detect browsers and other apps we want to
     be able to talk to.-->
    <!--https://developer.android.com/training/basics/intents/package-visibility-use-cases-->
    <queries>
        <package android:name="com.azure.authenticator" />
        <package android:name="com.companyname.xamarindev" />
        <package android:name="com.microsoft.windowsintune.companyportal" />
        <!-- Required for API Level 30 to make sure we can detect browsers
        (that don't support custom tabs) -->
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
        </intent>
        <!-- Required for API Level 30 to make sure we can detect browsers that support custom tabs -->
        <!-- https://developers.google.com/web/updates/2020/07/custom-tabs-android-11#detecting_browsers_that_support_custom_tabs -->
        <intent>
            <action android:name="android.support.customtabs.action.CustomTabsService" />
        </intent>
    </queries>
</manifest>

Menggunakan tampilan web tersemat (opsional)

Secara default, MSAL.NET menggunakan browser web sistem. Browser ini memungkinkan Anda untuk mendapat single sign-on (SSO) menggunakan aplikasi web dan aplikasi lainnya. Dalam beberapa kasus yang jarang terjadi, Anda mungkin ingin sistem Anda menggunakan tampilan web yang disematkan.

Contoh kode ini memperlihatkan cara menyiapkan tampilan web yang disematkan:

bool useEmbeddedWebView = !app.IsSystemWebViewAvailable;

var authResult = AcquireTokenInteractive(scopes)
 .WithParentActivityOrWindow(parentActivity)
 .WithEmbeddedWebView(useEmbeddedWebView)
 .ExecuteAsync();

Untuk informasi selengkapnya, lihat Menggunakan browser web untuk MSAL.NET dan pertimbangan browser sistem Android Xamarin.

Pemecahan Masalah

Tips umum

Perbarui paket MSAL.NET NuGet yang ada ke versi terbaru MSAL.NET.
Verifikasi bahwa Xamarin.Forms ada di versi terbaru.
Verifikasi bahwa Xamarin.Android.Support.v4 ada di versi terbaru.
Pastikan semua paket Xamarin.Android.Support menargetkan versi terbaru.
Bersihkan atau bangun kembali aplikasi.
Di Visual Studio, coba atur jumlah maksimum build proyect paralel menjadi 1. Untuk melakukannya, pilih Options>Projects and Solutions>Build and Run>Maximum number of parallel project builds.
Jika Anda membangun dari baris perintah dan perintah Anda menggunakan /m, coba hapus elemen ini dari perintah.

Kesalahan: Nama AuthenticationContinuationHelper tidak ada dalam konteks saat ini

Jika kesalahan menunjukkan bahwa AuthenticationContinuationHelper tidak ada dalam konteks saat ini, Visual Studio mungkin salah memperbarui file Android.csproj*. Terkadang jalur file dalam <HintPath>elemen yang salah berisi netstandard13 alih-alih monoandroid90.

Contoh ini berisi jalur file yang benar:

<Reference Include="Microsoft.Identity.Client, Version=3.0.4.0, Culture=neutral, PublicKeyToken=0a613f4dd989e8ae,
           processorArchitecture=MSIL">
  <HintPath>..\..\packages\Microsoft.Identity.Client.3.0.4-preview\lib\monoandroid90\Microsoft.Identity.Client.dll</HintPath>
</Reference>

Langkah berikutnya

Untuk mencoba sampel tambahan, Aplikasi klien publik seluler.

Bagikan melalui