Configuratievereisten en tips voor probleemoplossing voor Xamarin Android met MSAL.NET

Artikel
06/14/2024

Er zijn verschillende configuratiewijzigingen die u moet aanbrengen in uw code wanneer u Xamarin Android gebruikt met de Microsoft Authentication Library voor .NET (MSAL.NET). In de volgende secties worden de vereiste wijzigingen beschreven, gevolgd door een sectie Probleemoplossing om een aantal van de meest voorkomende problemen te voorkomen.

Notitie

MSAL.NET versies 4.61.0 en hoger bieden geen ondersteuning voor Universeel Windows-platform (UWP), Xamarin Android en Xamarin iOS. U wordt aangeraden uw Xamarin-toepassingen te migreren naar moderne frameworks zoals MAUI. Lees meer over de afschaffing in Aankondiging van de geplande afschaffing van MSAL.NET voor Xamarin en UWP.

De bovenliggende activiteit instellen

Stel in Xamarin Android de bovenliggende activiteit in zodat het token wordt geretourneerd na de interactie:

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

In MSAL.NET 4.2 en hoger kunt u deze functionaliteit ook instellen op het niveau van PublicClientApplication. Gebruik hiervoor een callback:

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

Als u CurrentActivityPlugin gebruikt, moet uw PublicClientApplication opbouwcode er ongeveer uitzien als dit codefragment:

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

Controleer of het besturingselement terugkeert naar MSAL

Wanneer het interactieve gedeelte van de verificatiestroom eindigt, keert u het besturingselement terug naar MSAL door det Activityte overschrijven.OnActivityResult() methode.

Roep bij uw onderdrukking AuthenticationContinuationHelper MSAL.NET aan.SetAuthenticationContinuationEventArgs() methode om het besturingselement te retourneren naar MSAL aan het einde van het interactieve gedeelte van de verificatiestroom.

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

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

Het Android-manifest voor System WebView-ondersteuning bijwerken

Ter ondersteuning van System WebView moet het AndroidManifest.xml-bestand de volgende waarden bevatten:

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

De android:scheme waarde wordt gemaakt op basis van de URI voor omleiding die is geconfigureerd in de portal van de toepassing. Als uw URI voor omleiding bijvoorbeeld is msal00001111-aaaa-2222-bbbb-3333cccc4444://auth, ziet de android:scheme vermelding in het manifest er als volgt uit:

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

U kunt ook de activiteit in code maken in plaats van handmatig AndroidManifest.xmlte bewerken. Als u de activiteit in code wilt maken, maakt u eerst een klasse die het Activity kenmerk en het IntentFilter kenmerk bevat.

Hier volgt een voorbeeld van een klasse die de waarden van het XML-bestand vertegenwoordigt:

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

System WebView gebruiken in verificatie met broker

Als u System WebView wilt gebruiken als terugval voor interactieve verificatie wanneer u uw toepassing hebt geconfigureerd voor het gebruik van verificatie met broker en het apparaat geen broker heeft geïnstalleerd, schakelt u MSAL in om het verificatieantwoord vast te leggen met de URI voor omleiding van de broker. MSAL probeert te verifiëren met behulp van de standaard webweergave van het systeem op het apparaat wanneer wordt gedetecteerd dat de broker niet beschikbaar is. Als u deze standaardinstelling gebruikt, mislukt dit omdat de URI voor omleiding is geconfigureerd voor het gebruik van een broker en System WebView niet weet hoe deze kan worden gebruikt om terug te keren naar MSAL. U kunt dit oplossen door een intentiefilter te maken met de URI voor omleiding van de broker die u eerder hebt geconfigureerd. Voeg het intentiefilter toe door het manifest van uw toepassing te wijzigen, zoals in dit voorbeeld:

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

Vervang de naam van het pakket dat u hebt geregistreerd in de Azure Portal door de waarde android:host=. Vervang de sleutel-hash die u hebt geregistreerd in Azure Portal door de waarde android:path=. De handtekening-hash mag niet als URL zijn gecodeerd. Zorg dat een voorloopslash (/) wordt weergegeven aan het begin van de handtekening-hash.

Xamarin.Forms 4.3.x-manifest

Xamarin.Forms 4.3.x genereert code waarmee het package kenmerk com.companyname.{appName} in AndroidManifest.xmlwordt ingesteld. Als u dit DataSchemegebruiktmsal{client_id}, kunt u de waarde wijzigen zodat deze overeenkomt met de waarde van de MainActivity.cs naamruimte.

Ondersteuning voor Android 11

Als u de systeembrowser en verificatie met broker in Android 11 wilt gebruiken, moet u deze pakketten eerst declareren, zodat ze zichtbaar zijn voor de app. Apps die zijn gericht op Android 10 (API 29) en eerder, kunnen op elk gewenst moment een query uitvoeren op het besturingssysteem voor een lijst met pakketten die beschikbaar zijn op het apparaat. Om privacy en beveiliging te ondersteunen, vermindert Android 11 de zichtbaarheid van pakketten voor pakketten met besturingssystemen en de pakketten die zijn opgegeven in het AndroidManifest.xml-bestand van de app.

Als u wilt dat de toepassing kan worden geverifieerd met zowel de systeembrowser als de broker, voegt u de volgende sectie toe aan 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>

Vervang {Package Name} door de pakketnaam van de toepassing.

Uw bijgewerkte manifest, dat nu ondersteuning bevat voor de systeembrowser en verificatie met broker, moet er ongeveer uitzien als in dit voorbeeld:

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

De ingesloten webweergave gebruiken (optioneel)

Standaard gebruikt MSAL.NET de webbrowser van het systeem. Met deze browser kunt u eenmalige aanmelding (SSO) ophalen met webtoepassingen en andere apps. In sommige zeldzame gevallen wilt u mogelijk dat uw systeem een ingesloten webweergave gebruikt.

In dit codevoorbeeld ziet u hoe u een ingesloten webweergave instelt:

bool useEmbeddedWebView = !app.IsSystemWebViewAvailable;

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

Zie voor meer informatie Webbrowsers gebruiken voor overwegingen voor MSAL.NET en Xamarin Android-systeembrowsers.

Probleemoplossing

Algemene tips

Werk het bestaande MSAL.NET NuGet-pakket bij naar de nieuwste versie van MSAL.NET.
Controleer of Xamarin.Forms de nieuwste versie heeft.
Controleer of Xamarin.Android.Support.v4 de nieuwste versie heeft.
Zorg dat alle Xamarin.Android.Support-pakketten gericht zijn op de nieuwste versie.
Herbouw de toepassing of schoon deze op.
Probeer in Visual Studio het maximum aantal parallelle projectversies in te stellen op 1. Hiervoor selecteert u Opties>Projecten en oplossingen>Bouwen en uitvoeren>Maximum aantal parallelle projectversies.
Als u bouwt vanaf de opdrachtregel en uw opdracht wordt gebruikt /m, verwijdert u dit element uit de opdracht.

Fout: de naam AuthenticationContinuationHelper bestaat niet in de huidige context

Als een fout aangeeft dat deze AuthenticationContinuationHelper niet bestaat in de huidige context, is het bestand Android.csproj* mogelijk onjuist bijgewerkt in Visual Studio. Soms bevat het bestandspad in het <HintPath> element onjuist netstandard13 in plaats van monoandroid90.

Dit voorbeeld bevat een correct bestandspad:

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

Volgende stappen

Zie voor meer informatie het voorbeeld van een mobiele Xamarin-toepassing die gebruikmaakt van het Microsoft Identity-platform. De volgende tabel bevat een overzicht van de relevante informatie in het README-bestand.

Voorbeeld	Platform	Beschrijving
https://github.com/Azure-Samples/active-directory-xamarin-native-v2	Xamarin.iOS, Android, UWP	Een mobiele Xamarin-toepassing die laat zien hoe u MSAL.NET kunt gebruiken om werk- of school- en Persoonlijke Microsoft-accounts te verifiëren met het Microsoft Identity Platform en toegang te krijgen tot de Microsoft Graph API met het resulterende token.

Delen via