Een mobiele app configureren die web-API's aanroept

Artikel
10/24/2023

Nadat u een toepassing hebt gemaakt, leert u hoe u de code configureert met behulp van de parameters voor app-registratie. Mobiele toepassingen leveren enkele uitdagingen op met betrekking tot het inpassen in het creatieframework.

Microsoft-bibliotheken die mobiele apps ondersteunen

De volgende Microsoft-bibliotheken ondersteunen mobiele apps:

Platform	Project over GitHub	Pakket	Aan de slag	Algemeen beschikbaar (GA) of Openbare preview¹
Android (Java)	MSAL Android	MSAL	Snelstartgids	GA
Android (Kotlin)	MSAL Android	MSAL	—	GA
iOS (Swift/Obj-C)	MSAL voor iOS en macOS	MSAL	Zelfstudie	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹ Universele licentievoorwaarden voor onlineservices zijn van toepassing op bibliotheken in openbare preview.

De toepassing instantiëren

Android

Mobiele toepassingen gebruiken de klasse PublicClientApplication. U kunt deze als volgt instantiëren:

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Mobiele toepassingen op iOS moeten de klasse MSALPublicClientApplication instantiëren. Gebruik de volgende code om de klasse te instantiëren.

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Aanvullende MSALPublicClientApplicationConfig-eigenschappen kunnen de standaardinstantie overschrijven, een omleidings-URI opgeven of het gedrag van MSAL-tokencaching wijzigen.

Xamarin of UWP

In deze sectie wordt uitgelegd hoe u de toepassing kunt instantiëren voor Xamarin.iOS-, Xamarin.Android- en UWP-apps.

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 toepassing instantiëren

In Xamarin of UWP kunt u de toepassing het eenvoudigst instantiëren door de volgende code te gebruiken. In deze code is ClientId de unieke id van uw geregistreerde app.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Aanvullende With<Parameter>-methoden stellen de bovenliggende gebruikersinterface in, overschrijven de standaardinstantie, geven een clientnaam en -versie op voor telemetrie, geven een omleidings-URI op en geven de HTTP-factory op die moet worden gebruikt. De HTTP-factory kan bijvoorbeeld worden gebruikt om proxy's te verwerken en telemetrie en logboekregistratie op te geven.

De volgende gedeelten bevatten meer informatie over het instantiëren van de toepassing.

De bovenliggende gebruikersinterface, het bovenliggende venster of de bovenliggende activiteit opgeven

Geef op Android de bovenliggende activiteit door voordat u de interactieve verificatie uitvoert. Geef op iOS, wanneer u een broker gebruikt, ViewController door. Op dezelfde manier wilt u op UWP mogelijk het bovenliggende venster doorgeven. U geeft het door wanneer u het token ophaalt. Maar wanneer u de app maakt, kunt u ook een callback opgeven als gemachtigde die UIParent retourneert.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

Op Android raden we u aan om CurrentActivityPlugin te gebruiken. De resulterende PublicClientApplication-opbouwcode ziet er als volgt uit:

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

Meer parameters voor het bouwen van apps zoeken

Zie de lijst met methoden voor alle methoden die beschikbaar zijn in PublicClientApplicationBuilder.

Zie de referentiedocumentatie voor een beschrijving van alle opties die worden weergegeven in PublicClientApplicationOptions.

Taken voor MSAL voor iOS en macOS

Deze taken zijn nodig wanneer u MSAL gebruikt voor iOS en macOS:

Taken voor Xamarin.Android

Als u Xamarin.Android gebruikt, voert u de volgende taken uit:

Zie Overwegingen voor Xamarin.Android voor meer informatie.

Zie Xamarin.Android-specifieke overwegingen met MSAL.NET voor overwegingen over de browsers op Android.

Taken voor UWP

Op UWP kunt u bedrijfsnetwerken gebruiken. In de volgende secties worden de taken beschreven die u moet uitvoeren in het bedrijfsscenario.

Zie UWP-specifieke overwegingen met MSAL.NET voor meer informatie.

De toepassing configureren voor het gebruik van de broker

Op Android en iOS schakelen brokers het volgende in:

Eenmalige aanmelding (SSO): u kunt eenmalige aanmelding gebruiken voor apparaten die zijn geregistreerd bij Microsoft Entra ID. Wanneer u eenmalige aanmelding gebruikt, hoeven uw gebruikers zich niet bij elke toepassing aan te melden.
Apparaatidentificatie: Met deze instelling wordt beleid voor voorwaardelijke toegang ingeschakeld dat is gerelateerd aan Microsoft Entra-apparaten. Het verificatieproces maakt gebruik van het apparaatcertificaat dat is gemaakt toen het apparaat aan de werkplek werd toegevoegd.
Verificatie van toepassingsidentificatie: wanneer een toepassing de broker aanroept, wordt de omleidings-URL doorgegeven. Vervolgens controleert de makelaar deze.

De broker inschakelen op Xamarin

Als u de broker op Xamarin wilt inschakelen, gebruikt u de parameter WithBroker() wanneer u de methode PublicClientApplicationBuilder.CreateApplication aanroept. .WithBroker() is standaard ingesteld op Waar.

Als u brokered verificatie voor Xamarin.iOS wilt inschakelen, volgt u de stappen in de sectie Xamarin.iOS in dit artikel.

De broker voor MSAL voor Android inschakelen

Zie Brokered verificatie op Android voor meer informatie over het inschakelen van een broker op Android.

De broker voor MSAL voor iOS en macOS inschakelen

Brokered-verificatie is standaard ingeschakeld voor Microsoft Entra-scenario's in MSAL voor iOS en macOS.

De volgende secties bevatten instructies om uw toepassing te configureren voor ondersteuning van brokered verificatie voor MSAL voor Xamarin.iOS of MSAL voor iOS en macOS. De twee reeksen instructies bevatten enkele verschillende stappen.

Brokered verificatie inschakelen voor Xamarin iOS

Volg de stappen in deze sectie om uw Xamarin.iOS-app te laten communiceren met de Microsoft Authenticator-app.

Stap 1: Broker-ondersteuning inschakelen

Broker-ondersteuning is standaard uitgeschakeld. U schakelt deze in voor een afzonderlijke PublicClientApplication-klasse. Gebruik de parameter WithBroker() wanneer u de PublicClientApplication-klasse maakt via PublicClientApplicationBuilder. 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: AppDelegate bijwerken om de callback af te handelen

Wanneer MSAL.NET de broker aanroept, roept de broker vervolgens uw toepassing terug. De broker roept de toepassing terug met behulp van de methode AppDelegate.OpenUrl. Omdat MSAL wacht op het antwoord van de broker, moet uw toepassing samenwerken om MSAL.NET terug te roepen. U stelt dit gedrag in door het AppDelegate.cs-bestand bij te werken om de methode te overschrijven, zoals in de volgende code wordt weergegeven.

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 aangeroepen wanneer de toepassing wordt gestart. Het is een mogelijkheid om het antwoord van de broker te verwerken en het verificatieproces te voltooien dat MSAL.NET heeft gestart.

Stap 3: een UIViewController() instellen

Voor Xamarin iOS hoeft u normaal gesproken geen objectvenster in te stellen. Maar in dit geval moet u het zo instellen dat u antwoorden kunt verzenden naar en ontvangen van een broker. Als u een objectvenster wilt instellen, stelt u in AppDelegate.cs een ViewController in.

Voer de volgende stappen uit om het objectvenster in te stellen:

Stel in AppDelegate.cs de App.RootViewController in op een nieuwe UIViewController(). Deze instelling zorgt ervoor dat de aanroep naar de broker UIViewController omvat. Als deze niet juist is ingesteld, wordt mogelijk deze fout 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."

Gebruik .WithParentActivityOrWindow(App.RootViewController) in de aanroep AcquireTokenInteractive. Geef de verwijzing door naar het objectvenster dat u gaat gebruiken. Hier volgt een voorbeeld:

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 4: Een URL-schema registreren

MSAL.NET gebruikt URL's om de broker aan te roepen en vervolgens het antwoord van de broker naar uw app terug te sturen. Registreer het URL-schema van uw app in het bestand Info.plist om de retour af te ronden.

Voer de volgende stappen uit om het URL-schema van uw app te registreren:

Voeg een CFBundleURLSchemes het voorvoegsel msauth toe.

Voeg CFBundleURLName toe aan het einde. Volg dit patroon:

$"msauth.(BundleId)"

Hier is BundleId een unieke identificatie van uw apparaat. Als BundleId bijvoorbeeld yourcompany.xforms is, is msauth.com.yourcompany.xforms uw URL-schema.

Dit URL-schema wordt onderdeel 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 5: 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 de sectie LSApplicationQueriesSchemes van het bestand Info.plist, zoals in het volgende voorbeeld:

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

Brokered verificatie voor MSAL voor iOS en macOS

Brokered-verificatie is standaard ingeschakeld voor Microsoft Entra-scenario's.

Stap 1: AppDelegate bijwerken om de callback af te handelen

Wanneer MSAL voor iOS en macOS de broker aanroept, roept de broker terug naar uw toepassing met behulp van de methode openURL. Omdat MSAL wacht op het antwoord van de broker, moet uw toepassing samenwerken om MSAL terug te roepen. U stelt deze mogelijkheid in door het AppDelegate.m-bestand bij te werken om de methode te overschrijven, zoals in de volgende codevoorbeelden wordt weergegeven.

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

Als u UISceneDelegate in gebruikt hebt genomen op iOS 13 of hoger, plaatst u de MSAL-callback in plaats daarvan in de scene:openURLContexts: van UISceneDelegate. MSAL handleMSALResponse:sourceApplication: mag slechts één keer worden aangeroepen voor elke URL.

Zie de Apple-documentatie voor meer informatie.

Stap 2: Een URL-schema registreren

MSAL voor iOS en macOS gebruikt URL's om de broker aan te roepen en vervolgens het broker-antwoord naar uw app te retourneren. Registreer het URL-schema voor uw app in het bestand Info.plist om de retour af te ronden.

Een schema voor uw app registreren:

Voeg het voorvoegsel msauth toe aan uw aangepaste URL-schema.
Voeg uw bundel-id toe aan het einde van uw schema. Volg dit patroon:

$"msauth.(BundleId)"

Hier is BundleId een unieke identificatie van uw apparaat. Als BundleId bijvoorbeeld yourcompany.xforms is, is msauth.com.yourcompany.xforms uw URL-schema.

Dit URL-schema wordt onderdeel van de omleidings-URI die uw app uniek identificeert wanneer deze het antwoord van de broker ontvangt. Zorg ervoor dat de omleidings-URI in de indeling msauth.(BundleId)://auth is geregistreerd voor uw toepassing.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Stap 3: LSApplicationQueriesSchemes toevoegen

Voeg LSApplicationQueriesSchemes toe om aanroepen naar de Microsoft Authenticator-app toe te staan, als deze is geïnstalleerd.

Notitie

Het msauthv3-schema is nodig wanneer uw app wordt gecompileerd met Xcode 11 en hoger.

Hier volgt een voorbeeld van het toevoegen van LSApplicationQueriesSchemes:

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

Brokered verificatie voor Xamarin.Android

Zie Brokered verificatie op Xamarin.Android voor meer informatie over het inschakelen van een broker op Android.

Volgende stappen

Ga verder met het volgende artikel in dit scenario: Een token ophalen.

Delen via

Een mobiele app configureren die web-API's aanroept

Microsoft-bibliotheken die mobiele apps ondersteunen

De toepassing instantiëren

Android

iOS

Xamarin of UWP

De toepassing instantiëren

De bovenliggende gebruikersinterface, het bovenliggende venster of de bovenliggende activiteit opgeven

Meer parameters voor het bouwen van apps zoeken

Taken voor MSAL voor iOS en macOS

Taken voor Xamarin.Android

Taken voor UWP

De toepassing configureren voor het gebruik van de broker

De broker inschakelen op Xamarin

De broker voor MSAL voor Android inschakelen

De broker voor MSAL voor iOS en macOS inschakelen

Brokered verificatie inschakelen voor Xamarin iOS

Stap 1: Broker-ondersteuning inschakelen

Stap 2: AppDelegate bijwerken om de callback af te handelen

Stap 3: een UIViewController() instellen

Stap 4: Een URL-schema registreren

Stap 5: Toevoegen aan de sectie LSApplicationQueriesSchemes

Brokered verificatie voor MSAL voor iOS en macOS

Stap 1: AppDelegate bijwerken om de callback af te handelen

Stap 2: Een URL-schema registreren

Stap 3: LSApplicationQueriesSchemes toevoegen

Brokered verificatie voor Xamarin.Android

Volgende stappen

Feedback

Aanvullende resources