Konfigurációs követelmények és hibaelhárítási tippek Xamarin Androidhoz MSAL.NET

Cikk
04/13/2024

A Xamarin Android és a Microsoft Authentication Library for .NET (MSAL.NET) használatakor számos konfigurációs módosításra van szükség a kódban. A következő szakaszok ismertetik a szükséges módosításokat, majd egy hibaelhárítási szakaszt, amely segít elkerülni a leggyakoribb problémákat.

Feljegyzés

MSAL.NET 4.61.0-s és újabb verziók nem támogatják Univerzális Windows-platform (UWP), Xamarin Android és Xamarin iOS rendszert. Javasoljuk, hogy a Xamarin-alkalmazásokat modern keretrendszerekbe, például a MAUI-ba migrálja. További információ a Xamarin- és UWP-MSAL.NET közelgő elavulásáról szóló közleményben.

A szülőtevékenység beállítása

Xamarin Android rendszeren állítsa be a szülőtevékenységet, hogy a jogkivonat az interakció után visszatérjen:

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

A MSAL.NET 4.2-es és újabb verzióiban ezt a funkciót a PublicClientApplication szintjén is beállíthatja. Ehhez használjon visszahívást:

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

A CurrentActivityPlugin használata esetén a PublicClientApplication szerkesztőkódnak az alábbi kódrészlethez hasonlóan kell kinéznie:

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

Győződjön meg arról, hogy a vezérlő visszatér az MSAL-hez

Amikor a hitelesítési folyamat interaktív része véget ér, az MSAL-hez való visszatéréshez felül kell bírálnia a Activity.OnActivityResult() módszer.

A felülbírálás során hívja meg az MSAL-t. NET's AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs() metódust, amely a hitelesítési folyamat interaktív részének végén adja vissza a vezérlést az MSAL-nak.

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

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

Az Android-jegyzék frissítése a System WebView támogatásához

A System WebView támogatásához a AndroidManifest.xml fájlnak a következő értékeket kell tartalmaznia:

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

Az android:scheme érték az alkalmazásportálon konfigurált átirányítási URI-ból jön létre. Ha például az átirányítási URI az msal00001111-aaaa-2222-bbbb-3333cccc4444://auth, a android:scheme jegyzékben szereplő bejegyzés a következő példához hasonlóan nézne ki:

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

Azt is megteheti, hogy a tevékenységet kódban hozza létre ahelyett, hogy manuálisan szerkeszti a AndroidManifest.xml. A tevékenység kódban való létrehozásához először hozzon létre egy osztályt, amely tartalmazza az attribútumot és az ActivityIntentFilter attribútumot.

Íme egy példa az XML-fájl értékeit képviselő osztályra:

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

A System WebView használata közvetítőalapú hitelesítésben

Ha a System WebView-t tartalékként szeretné használni az interaktív hitelesítéshez, ha úgy konfigurálta az alkalmazást, hogy közvetítőalapú hitelesítést használjon, és az eszközre nincs telepítve közvetítő, engedélyezze az MSAL számára a hitelesítési válasz rögzítését a közvetítő átirányítási URI-jával. Az MSAL az eszköz alapértelmezett System WebView-jának használatával próbálja meg a hitelesítést, ha azt észleli, hogy a közvetítő nem érhető el. Ez az alapértelmezett beállítás sikertelen lesz, mert az átirányítási URI konfigurálva van egy közvetítő használatára, és a System WebView nem tudja, hogyan kell azt használni az MSAL-hez való visszatéréshez. A probléma megoldásához hozzon létre egy szándékszűrőt a korábban konfigurált közvetítőátirányítási URI használatával. A szándékszűrő hozzáadásához módosítsa az alkalmazás jegyzékfájlját az alábbi példához hasonlóan:

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

Cserélje le az Azure Portalon regisztrált csomagnevet az android:host= értékre. Cserélje le az Azure Portalon regisztrált kulcskivonatot az android:path= értékre. Az aláírás kivonata nem lehet URL-kódolású. Győződjön meg arról, hogy az aláírás kivonatának elején megjelenik egy előrevezető perjel (/).

Xamarin.Forms 4.3.x jegyzék

A Xamarin.Forms 4.3.x olyan kódot hoz létre, amely beállítja az attribútumot com.companyname.{appName}a package AndroidManifest.xml. Ha a névtér msal{client_id}értékét használjaDataScheme, érdemes lehet módosítani az értéket úgy, hogy az megfeleljen a MainActivity.cs névtér értékének.

Android 11-támogatás

A rendszerböngésző és a közvetített hitelesítés Android 11-ben való használatához először deklarálnia kell ezeket a csomagokat, hogy azok láthatóak legyenek az alkalmazás számára. Az Android 10-et (API 29) és korábbi verziót megcélzott alkalmazások lekérdezhetik az operációs rendszert az eszközön bármikor elérhető csomagok listájához. Az adatvédelem és a biztonság támogatása érdekében az Android 11 csökkenti a csomagok láthatóságát az operációsrendszer-csomagok alapértelmezett listájára és az alkalmazás AndroidManifest.xml fájljában megadott csomagokra.

Ha engedélyezni szeretné az alkalmazás számára a hitelesítést a rendszerböngésző és a közvetítő használatával, adja hozzá a következő szakaszt a 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>

Cserélje le {Package Name} az alkalmazáscsomag nevére.

A frissített jegyzéknek, amely mostantól támogatja a rendszerböngészőt és a közvetítőalapú hitelesítést, az alábbi példához hasonlóan kell kinéznie:

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

Beágyazott webes nézet használata (nem kötelező)

Alapértelmezés szerint MSAL.NET a rendszer webböngészőt használja. Ez a böngésző lehetővé teszi az egyszeri bejelentkezést (SSO) webalkalmazások és más alkalmazások használatával. Bizonyos ritka esetekben előfordulhat, hogy a rendszer beágyazott webes nézetet szeretne használni.

Ez a példakód bemutatja, hogyan állíthat be beágyazott webes nézetet:

bool useEmbeddedWebView = !app.IsSystemWebViewAvailable;

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

További információ: A böngészők használata MSAL.NET és Xamarin Android rendszerböngészővel kapcsolatos szempontok.

Hibaelhárítás

Általános tippek

Frissítse a meglévő MSAL.NET NuGet-csomagot a MSAL.NET legújabb verziójára.
Ellenőrizze, hogy a Xamarin.Forms a legújabb verzióban van-e.
Ellenőrizze, hogy a Xamarin.Android.Support.v4 a legújabb verzióra van-e telepítve.
Győződjön meg arról, hogy az összes Xamarin.Android.Support csomag a legújabb verziót célozza.
Az alkalmazás tisztítása vagy újraépítése.
A Visual Studióban próbálja meg 1-re állítani a párhuzamos projekt buildjeinek maximális számát. Ehhez válassza a Beállítások>projektek és megoldások>összeállítása és futtatása>párhuzamos projektek maximális száma lehetőséget.
Ha a parancssorból épít, és a parancs használja /m, próbálja meg eltávolítani ezt az elemet a parancsból.

Hiba: Az AuthenticationContinuationHelper név nem létezik az aktuális környezetben

Ha egy hiba azt jelzi, hogy a jelenlegi környezetben nem létezik, előfordulhat, hogy AuthenticationContinuationHelper a Visual Studio helytelenül frissítette az Android.csproj* fájlt. Előfordulhat, hogy az elem fájlelérési <HintPath> útja helytelenül tartalmazza ahelyett, hogy monoandroid90a fájlt tartalmaztanetstandard13.

Ez a példa a megfelelő fájl elérési útját tartalmazza:

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

Következő lépések

További információ: egy Microsoft Identitásplatform használó Xamarin mobilalkalmazás mintája. Az alábbi táblázat összefoglalja a README-fájlban található releváns információkat.

Minta	Platform	Leírás
https://github.com/Azure-Samples/active-directory-xamarin-native-v2	Xamarin.iOS, Android, UWP	Egy Xamarin mobilalkalmazás, amely bemutatja, hogyan használható MSAL.NET munkahelyi vagy iskolai és Microsoft személyes fiókok hitelesítésére a Microsoft Identitásplatform, és hogyan férhet hozzá a Microsoft Graph API-hoz az eredményül kapott jogkivonattal.

Megosztás a következőn keresztül: