Microsoft Authenticator of Intune-bedrijfsportal gebruiken in Xamarin-toepassingen
Op Android en iOS kunnen brokers zoals Microsoft Authenticator en de Android-specifieke Microsoft Intune-bedrijfsportal de volgende zaken inschakelen:
- Eenmalige aanmelding (SSO): gebruikers hoeven zich niet bij elke toepassing aan te melden.
- Apparaatidentificatie: de broker opent het apparaatcertificaat. Dit certificaat wordt gemaakt op het apparaat wanneer het is toegevoegd aan de werkplek.
- Verificatie van toepassingsidentificatie: wanneer een toepassing de broker aanroept, wordt de omleidings-URL doorgegeven. De broker controleert de URL.
Als u een van deze functies wilt inschakelen, gebruikt u de parameter WithBroker() wanneer u de PublicClientApplicationBuilder.CreateApplication-methode aanroept. De parameter .WithBroker() is standaard ingesteld op true.
De installatie van brokered verificatie in de Microsoft Authentication Library voor .NET (MSAL.NET) varieert per platform:
Brokered verificatie voor iOS
Gebruik de volgende stappen om uw Xamarin.iOS-app in te schakelen om te communiceren met de Microsoft Authenticator-app. Als u iOS 13 gebruikt, kunt u lezen over de belangrijke API-wijziging van Apple.
Stap 1: Broker-ondersteuning inschakelen
U moet broker-ondersteuning inschakelen voor afzonderlijke exemplaren van PublicClientApplication. Ondersteuning is standaard uitgeschakeld. Wanneer u PublicClientApplication maakt met behulp van PublicClientApplicationBuilder, gebruikt u de parameter WithBroker() zoals in het volgende voorbeeld wordt weergegeven. De parameter WithBroker() is standaard ingesteld op true.
var app = PublicClientApplicationBuilder
.Create(ClientId)
.WithBroker()
.WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
.Build();
Stap 2: Toegang tot sleutelketen inschakelen
Als u toegang tot de sleutelketen wilt inschakelen, moet u een sleutelketentoegangsgroep voor uw toepassing hebben. U kunt de API WithIosKeychainSecurityGroup() gebruiken om uw sleutelketentoegangsgroep in te stellen wanneer u uw toepassing maakt:
var builder = PublicClientApplicationBuilder
.Create(ClientId)
.WithIosKeychainSecurityGroup("com.microsoft.adalcache")
.Build();
Zie Toegang tot sleutelketen inschakelen voor meer informatie.
Stap 3: AppDelegate bijwerken om de aanroep af te handelen
Wanneer MSAL.NET de broker aanroept, roept de broker via de OpenUrl-methode van de AppDelegate-klasse terug naar uw toepassing. Omdat MSAL wacht op het antwoord van de broker, moet uw toepassing samenwerken om MSAL.NET terug te roepen. Als u deze samenwerking wilt inschakelen, werkt u het bestand AppDelegate.cs bij om de volgende methode te overschrijven.
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;
}
Deze methode wordt steeds aangeroepen wanneer de toepassing wordt gestart. Het wordt gebruikt als een mogelijkheid om het antwoord van de broker te verwerken en het verificatieproces te voltooien dat MSAL.NET heeft gestart.
Stap 4: UIViewController() instellen
U bent nog steeds in het bestand AppDelegate.cs. Stel hier een objectvenster in. Normaal gesproken hoeft u het objectvenster voor Xamarin iOS niet in te stellen, maar u hebt wel een objectvenster nodig om antwoorden van de broker te verzenden en te ontvangen.
Het objectvenster instellen:
Stel in het bestand AppDelegate.cs
App.RootViewControllerin op een nieuweUIViewController(). Deze opdracht zorgt ervoor dat de aanroep van de brokerUIViewControlleromvat. Als deze instelling onjuist is toegewezen, wordt deze fout mogelijk weergegeven:"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker"In de aanroep
AcquireTokenInteractivegebruikt u.WithParentActivityOrWindow(App.RootViewController). Geef de verwijzing door naar het objectvenster dat u gaat gebruiken.In App.cs:
public static object RootViewController { get; set; }In AppDelegate.cs:
LoadApplication(new App()); App.RootViewController = new UIViewController();In de aanroep
AcquireToken:result = await app.AcquireTokenInteractive(scopes) .WithParentActivityOrWindow(App.RootViewController) .ExecuteAsync();
Stap 5: Een URL-schema registreren
MSAL.NET gebruikt URL's om de broker aan te roepen en vervolgens het broker-antwoord naar uw app te retourneren. Als u de retour wilt voltooien, registreert u een URL-schema voor uw app in het bestand Info.plist.
De CFBundleURLSchemes-naam moet msauth. als voorvoegsel bevatten. Volg het voorvoegsel op met CFBundleURLName.
In het URL-schema identificeert BundleId de volgende app uniek: $"msauth.(BundleId)". Dus als BundleIdcom.yourcompany.xforms is, is msauth.com.yourcompany.xforms het URL-schema.
Notitie
Dit URL-schema maakt deel uit van de omleidings-URI die uw app uniek identificeert wanneer deze het antwoord van de broker ontvangt.
<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>
Stap 6: De broker-id toevoegen aan de sectie LSApplicationQueriesSchemes
MSAL gebruikt –canOpenURL: om te controleren of de broker is geïnstalleerd op het apparaat. In iOS 9 heeft Apple de schema's vergrendeld waarvoor een toepassing query's kan uitvoeren.
Voeg msauthv2 toe aan sectie LSApplicationQueriesSchemes van het bestand Info.plist, zoals in het volgende voorbeeld:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>msauthv2</string>
<string>msauthv3</string>
</array>
Stap 7: Een omleidings-URI toevoegen aan uw app-registratie
Tip
Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.
Wanneer u de broker gebruikt, heeft uw omleidings-URI een extra vereiste. De omleidings-URI moet de volgende indeling hebben:
$"msauth.{BundleId}://auth"
Hier volgt een voorbeeld:
public static string redirectUriOnIos = "msauth.com.yourcompany.XForms://auth";
U ziet dat de omleidings-URI overeenkomt met de naam CFBundleURLSchemes die u hebt opgenomen in het bestand Info.plist.
Voeg de omleidings-URI toe aan de registratie van de app. Als u een correct opgemaakte omleidings-URI wilt genereren, gebruikt u App-registraties om de omleidings-URI met brokered te genereren op basis van de bundel-id.
De omleidings-URI genereren:
Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een cloudtoepassing Beheer istrator.
Blader naar identiteitstoepassingen>> App-registraties.
Zoek en selecteer de toepassing.
Selecteer Verificatie>Een platform toevoegen>iOS / macOS
Voer uw bundel-id in en selecteer vervolgens Configureren.
Kopieer de gegenereerde omleidings-URI die wordt weergegeven in het tekstvak Omleidings-URI voor opname in uw code:
Selecteer Gereed om het genereren van de omleidings-URI te voltooien.
Brokered-verificatie voor Android
Stap 1: Broker-ondersteuning inschakelen
Broker-ondersteuning is ingeschakeld op een per PublicClientApplication-basis. Standaard is deze instellin uitgeschakeld. Gebruik de parameter WithBroker() (standaard ingesteld op true) bij het maken van de IPublicClientApplication via de PublicClientApplicationBuilder.
var app = PublicClientApplicationBuilder
.Create(ClientId)
.WithBroker()
.WithRedirectUri(redirectUriOnAndroid) // See step #4
.Build();
Stap 2: De hoofdactiviteit bijwerken om de callback af te handelen
Wanneer MSAL.NET de broker aanroept, zal de broker op zijn beurt met de OnActivityResult()-methode terugroepen naar uw toepassing. Omdat MSAL wacht op het antwoord van de broker, moet uw toepassing het resultaat omleiden naar MSAL.NET.
Routeer het resultaat naar de SetAuthenticationContinuationEventArgs(int requestCode, Result resultCode, Intent data)-methode door de OnActivityResult()-methode te overschrijven, zoals hier wordt weergegeven:
protected override void OnActivityResult(int requestCode, Result resultCode, Intent data)
{
base.OnActivityResult(requestCode, resultCode, data);
AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(requestCode, resultCode, data);
}
Deze methode wordt steeds aangeroepen wanneer de brokertoepassing wordt gestart en wordt gebruikt als een mogelijkheid om het antwoord van de broker te verwerken en het verificatieproces te voltooien dat door MSAL.NET is gestart.
Stap 3: Een activiteit instellen
Als u brokered verificatie wilt inschakelen, stelt u een activiteit in zodat MSAL het antwoord naar en van de broker kan verzenden en ontvangen. Als u dit wilt doen, geeft u de activiteit (meestal de MainActivity) op aan het bovenliggende object WithParentActivityOrWindow(object parent).
Bijvoorbeeld in de aanroep naar AcquireTokenInteractive():
result = await app.AcquireTokenInteractive(scopes)
.WithParentActivityOrWindow((Activity)context))
.ExecuteAsync();
Stap 4: Een omleidings-URI toevoegen aan uw app-registratie
MSAL gebruikt URL's om de broker aan te roepen en vervolgens terug te keren naar uw app. Registreer een omleidings-URI voor uw app om die retour te voltooien.
De indeling van de omleidings-URI voor uw toepassing is afhankelijk van het certificaat dat wordt gebruikt om de APK te ondertekenen. Voorbeeld:
msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=
Het laatste deel van de URI, hgbUYHVBYUTvuvT&Y6tr554365466=, is de Base64-gecodeerde versie van de handtekening waarmee de APK is ondertekend. Als u tijdens het ontwikkelen van uw app in Visual Studio fouten in uw code opspoort zonder de APK te ondertekenen met een specifiek certificaat, ondertekent Visual Studio de APK voor u voor foutopsporingsdoeleinden. Wanneer Visual Studio de APK op deze manier ondertekent, krijgt deze een unieke handtekening voor de computer waarop deze is gebouwd. Telkens wanneer u uw app op een andere computer bouwt, moet u dus de omleidings-URI bijwerken in de code van de toepassing en de registratie van de toepassing om te verifiëren met MSAL.
Tijdens foutopsporing kunt u een MSAL-uitzondering (of logboekbericht) tegenkomen waarin staat dat de opgegeven omleidings-URI onjuist is. Het uitzonderings- of logboekbericht geeft ook de omleidings-URI aan die u moet gebruiken met de huidige computer waarop u foutopsporing uitvoert. U kunt de opgegeven omleidings-URI gebruiken om door te gaan met het ontwikkelen van uw app zolang u de omleidings-URI in code bijwerkt en de opgegeven omleidings-URI toevoegt aan de registratie van de app.
Zodra u klaar bent om uw code te voltooien, werkt u de omleidings-URI bij in de code en de registratie van de toepassing om de handtekening van het certificaat waarmee u de APK ondertekent te gebruiken.
In de praktijk betekent dit dat u een omleidings-URI kunt toevoegen voor elk lid van uw ontwikkelingsteam, plus een omleidings-URI voor de voor productie ondertekende versie van de APK.
U kunt de handtekening zelf berekenen, op soortgelijke wijze als hoe MSAL dit doet:
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.
}
}
U hebt ook de mogelijkheid om de handtekening voor uw pakket te verkrijgen met behulp van keytool met de volgende opdrachten:
- 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
Stap 5 (optioneel): Terugvallen naar de systeembrowser
Als MSAL is geconfigureerd voor het gebruik van de broker, maar de broker niet is geïnstalleerd, valt MSAL terug op het gebruik van een webweergave (een browser). MSAL probeert met behulp van de standaardsysteembrowser te verifiëren op het apparaat, wat vervolgens mislukt omdat de omleidings-URI is geconfigureerd voor de broker en de systeembrowser niet weet hoe deze moet worden gebruikt om terug te navigeren naar MSAL. Om de fout te voorkomen, kunt u een intentiefilter configureren met de omleidings-URI van de broker die u in stap 4 hebt gebruikt.
Wijzig het manifest van uw toepassing om het intentiefilter toe te voegen:
<!-- 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"/>
Als u bijvoorbeeld een omleidings-URI van msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466= hebt, moet uw manifest eruitzien als het volgende XML-fragment.
De slash (/) vóór de handtekening in de waarde android:path is vereist.
<!-- 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="/>
Zie Het Android-manifest bijwerken voor systeembrowserondersteuning voor meer informatie over het configureren van uw toepassing voor systeembrowser- en Android 11-ondersteuning.
Als alternatief kunt u MSAL configureren om terug te vallen op de ingesloten browser, die niet afhankelijk is van een omleidings-URI:
.WithUseEmbeddedWebUi(true)
Tips voor het oplossen van problemen met brokered-verificatie op Android
Hier volgen enkele tips voor het voorkomen van problemen bij het implementeren van brokered verificatie op Android:
Omleidings-URI: voeg een omleidings-URI toe aan uw toepassingsregistratie. Een ontbrekende of onjuiste omleidings-URI is een veelvoorkomend probleem dat ontwikkelaars ondervinden.
Broker-versie: installeer de minimaal vereiste versie van de broker-apps. Een van deze twee apps kan worden gebruikt voor brokered verificatie op Android.
- Intune-bedrijfsportal (versie 5.0.4689.0 of hoger)
- Microsoft Authenticator (versie 6.2001.0140 of hoger).
Brokerprioriteit: MSAL communiceert met de eerste broker die op het apparaat is geïnstalleerd wanneer meerdere brokers worden geïnstalleerd.
Voorbeeld: Als u Microsoft Authenticator eerst installeert en vervolgens Intune-bedrijfsportal installeert, vindt brokered verificatie alleen plaats op de Microsoft Authenticator.
Logboeken: als u een probleem ondervindt met brokered verificatie, kan het bekijken van de logboeken van de broker u helpen bij het vaststellen van de oorzaak.
Microsoft Authenticator-logboeken ophalen:
- Selecteer de menuknop in de rechterbovenhoek van de app.
- Selecteer Feedback verzenden>Hebt u problemen?.
- Selecteer onder Wat wilt u doen? een optie en voeg een beschrijving toe.
- Als u de logboeken wilt verzenden, selecteert u de pijl in de rechterbovenhoek van de app.
Nadat u de logboeken hebt verzonden, wordt in een dialoogvenster de incident-id weergegeven. Noteer de incident-id en geef deze op wanneer u hulp aanvraagt.
Logboeken van Intune-bedrijfsportal ophalen:
- Selecteer de menuknop in de linkerbovenhoek van de app.
- Selecteer Help>Email Ondersteuning.
- Als u de logboeken wilt verzenden, selecteert u Alleen logboeken uploaden.
Nadat u de logboeken hebt verzonden, wordt in een dialoogvenster de incident-id weergegeven. Noteer de incident-id en geef deze op wanneer u hulp aanvraagt.
Volgende stappen
Meer informatie over overwegingen voor het gebruik van Universeel Windows-platform met MSAL.NET.