Konfigurieren einer mobilen App, die Web-APIs aufruft

Nachdem Sie Ihre Anwendung erstellt haben, erfahren Sie, wie Sie den Code mithilfe der App-Registrierungsparameter konfigurieren. Mobile Anwendungen halten im Hinblick auf ihre Einpassung in ihr Erstellungsframework eine Reihe von Schwierigkeiten bereit.

Microsoft-Bibliotheken, die mobile Apps unterstützen

Die folgenden Microsoft-Bibliotheken unterstützen mobile Apps:

Plattform	Projekt auf GitHub	Paket	Erste Schritte gestartet	Anmelden von Benutzern	Zugriff auf Web-APIs	Allgemein verfügbar (Generally Available, GA) oder Öffentliche Vorschau1
Android (Java)	MSAL Android	MSAL	Schnellstart			Allgemein verfügbar
Android (Kotlin)	MSAL Android	MSAL	—			Allgemein verfügbar
iOS (Swift/Obj-C)	MSAL für iOS und macOS	MSAL	Tutorial			Allgemein verfügbar
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—			Allgemein verfügbar

¹ Universelle Lizenzbedingungen für Onlinedienste gelten für Bibliotheken in der öffentlichen Vorschauversion.

Instanziierung der Anwendung

Android

Mobile Anwendungen verwenden die PublicClientApplication-Klasse. Hier sehen Sie, wie sie instanziiert wird:

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

iOS

Mobile Anwendungen unter iOS müssen die MSALPublicClientApplication-Klasse instanziieren. Verwenden Sie zum Instanziieren der Klasse den folgenden Code.

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 */}

Zusätzliche MSALPublicClientApplicationConfig-Eigenschaften können die Standardautorität überschreiben, einen Umleitungs-URI angeben oder das Verhalten der MSAL-Tokenzwischenspeicherung ändern.

Xamarin oder UWP

In den folgenden Abschnitten wird erläutert, wie Sie die Anwendung für Xamarin.iOS-, Xamarin.Android- und UWP-Apps instanziieren.

Instanziierung der Anwendung

In Xamarin oder UWP ist das einfachste Verfahren zum Instanziieren die Verwendung des folgenden Codes. In diesem Code ist ClientId die GUID der registrierten App.

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

Mithilfe zusätzlicher With<Parameter>-Methoden werden das übergeordnete Element der Benutzeroberfläche festgelegt, die Standardautorität außer Kraft gesetzt, ein Clientname und eine Version für die Telemetrie sowie ein Umleitungs-URI und die zu verwendende HTTP-Factory angegeben. Die HTTP-Factory kann beispielsweise für das Behandeln von Proxys und das Angeben von Telemetrie und Protokollierung verwendet werden.

In den folgenden Abschnitten finden Sie weitere Informationen zum Instanziieren der Anwendung.

Angeben des übergeordneten Elements der Benutzeroberfläche, des übergeordneten Fensters oder der übergeordneten Aktivität

Unter Android müssen Sie vor der interaktiven Authentifizierung die übergeordnete Aktivität übergeben. Wenn Sie unter iOS einen Broker verwenden, müssen Sie ViewController übergeben. Auf dieselbe Weise möchten Sie möglicherweise auf der UWP das übergeordnete Fenster übergeben. Sie übergeben es beim Abrufen des Tokens. Sie können aber beim Erstellen der App außerdem einen Rückruf als Delegat festlegen, der UIParent zurückgibt.

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

Unter Android empfehlen wir, CurrentActivityPlugin zu verwenden. Der resultierende Code des PublicClientApplication-Generators sieht wie in diesem Beispiel aus:

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

Suchen weiterer Parameter für die App-Erstellung

Eine Liste aller Methoden, die in PublicClientApplicationBuilder verfügbar sind, finden Sie in der Methodenliste.

Eine Beschreibung aller Optionen, die in PublicClientApplicationOptions verfügbar gemacht werden, finden Sie in der Referenzdokumentation.

Aufgaben für MSAL für iOS und macOS

Diese Aufgaben sind erforderlich, wenn Sie MSAL für iOS und macOS verwenden:

• Implementieren Sie den openURL-Rückruf.
• Aktivieren Sie Keychainzugriffsgruppen.
• Passen Sie Browser und WebViews an.

Aufgaben für Xamarin.Android

Wenn Sie Xamarin.Android verwenden, führen Sie die folgenden Aufgaben aus:

• Sicherstellen, dass die Steuerung nach dem Ende des interaktiven Teils des Authentifizierungsablaufs wieder an MSAL übergeben wird
• Aktualisieren des Android-Manifests
• Verwenden der eingebetteten Webansicht (optional)
• Problembehandlung nach Bedarf

Weitere Informationen finden Sie unter Überlegungen zu Xamarin.Android.

Überlegungen zu den Browsern unter Android finden Sie unter Spezifische Überlegungen zu Xamarin.Android mit MSAL.NET.

Aufgaben für UWP

Auf der UWP können Sie Unternehmensnetzwerke verwenden. In den folgenden Abschnitten werden die Aufgaben erläutert, die Sie im Unternehmensszenario ausführen sollten.

Weitere Informationen finden Sie unter Für UWP spezifische Überlegungen mit MSAL.NET.

Konfigurieren der Anwendung für die Verwendung des Brokers

Unter Android und iOS ermöglichen Broker Folgendes:

• Einmaliges Anmelden (Single Sign-On, SSO): Sie können SSO für Geräte verwenden, die mit Microsoft Entra ID registriert sind. Wenn Sie SSO verwenden, müssen sich Ihre Benutzer nicht bei jeder Anwendung anmelden.
• Geräteidentifikation: Diese Einstellung ermöglicht bedingte Zugriffsrichtlinien im Zusammenhang mit Microsoft Entra-Geräten. Der Authentifizierungsprozess verwendet das Gerätezertifikat, das beim Hinzufügen des Geräts zum Arbeitsplatz erstellt wurde.
• Überprüfung der Anwendungsidentifikation: Wenn eine Anwendung den Broker aufruft, übergibt sie ihre Umleitungs-URL. Diese wird dann vom Broker überprüft.

Aktivieren des Brokers in Xamarin

Um den Broker in Xamarin zu aktivieren, verwenden Sie den WithBroker()-Parameter, wenn Sie die PublicClientApplicationBuilder.CreateApplication-Methode aufrufen. Standardmäßig ist .WithBroker() auf „true“ festgelegt.

Um die Brokerauthentifizierung für Xamarin.iOS zu aktivieren, führen Sie die Schritte im Xamarin.iOS-Abschnitt in diesem Artikel aus.

Aktivieren des Brokers für MSAL für Android

Informationen zum Aktivieren eines Brokers unter Android finden Sie unter Brokerauthentifizierung in Android.

Aktivieren des Brokers für MSAL für iOS und macOS

Brokerauthentifizierung ist standardmäßig für Microsoft Entra-Szenarien in MSAL für iOS und macOS aktiviert.

In den folgenden Abschnitten finden Sie Anweisungen zum Konfigurieren Ihrer Anwendung für die Unterstützung von Brokerauthentifizierung für MSAL für Xamarin.iOS oder MSAL für iOS und macOS. Einige der Schritte in den beiden Anweisungslisten unterscheiden sich.

Aktivieren von Brokerauthentifizierung für Xamarin iOS

Führen Sie die Schritte in diesem Abschnitt aus, um Ihre Xamarin.iOS-App für die Kommunikation mit der Microsoft Authenticator-App zu aktivieren.

Schritt 1: Aktivieren der Brokerunterstützung

Die Brokerunterstützung ist standardmäßig deaktiviert. Sie aktivieren Sie für eine einzelne PublicClientApplication-Klasse. Verwenden Sie den WithBroker()-Parameter, wenn Sie die PublicClientApplication-Klasse mithilfe von PublicClientApplicationBuilder erstellen. Der WithBroker()-Parameter ist standardmäßig auf „true“ festgelegt.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

Schritt 2: Aktualisieren von AppDelegate zum Verarbeiten des Rückrufs

Wenn MSAL.NET den Broker aufruft, führt der Broker wiederum einen Rückruf an Ihre Anwendung aus. Der Rückruf erfolgt mithilfe der AppDelegate.OpenUrl-Methode. Da MSAL auf die Antwort vom Broker wartet, muss Ihre Anwendung kooperieren, damit der Rückruf von MSAL.NET erfolgen kann. Sie richten dieses Verhalten durch Aktualisieren der Datei AppDelegate.cs zum Überschreiben der Methode ein, wie aus dem folgenden Code zu ersehen.

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

Diese Methode wird jedes Mal aufgerufen, wenn die Anwendung gestartet wird. Sie bietet die Gelegenheit, die Antwort vom Broker zu verarbeiten und den von MSAL.NET eingeleiteten Authentifizierungsprozess abzuschließen.

Schritt 3: Festlegen von „UIViewController()“

Für Xamarin iOS brauchen Sie normalerweise kein Objektfenster festzulegen. In diesem Fall sollten Sie es jedoch festlegen, sodass Sie an einen Broker senden und Antworten von ihm empfangen können. Um ein Objektfenster festzulegen, legen Sie in AppDelegate.cs einen ViewController fest.

Führen Sie die folgenden Schritte aus, um das Objektfenster festzulegen:

1. Legen Sie in der Datei AppDelegate.cs das App.RootViewController-Objekt auf einen neuen UIViewController() fest. Mit dieser Einstellung wird sichergestellt, dass der aufzurufende Broker UIViewControllerenthält. Wenn der Controller nicht ordnungsgemäß festgelegt wird, erhalten Sie möglicherweise folgende Fehlermeldung:

   "uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker."

2. Verwenden Sie für den AcquireTokenInteractive-Aufruf .WithParentActivityOrWindow(App.RootViewController). Übergeben Sie den Verweis an das Objektfenster, das Sie verwenden möchten. Hier sehen Sie ein Beispiel:

   In App.cs:

      public static object RootViewController { get; set; }
   

   In AppDelegate.cs:

      LoadApplication(new App());
      App.RootViewController = new UIViewController();
   

   Im AcquireToken-Aufruf:

   result = await app.AcquireTokenInteractive(scopes)
                .WithParentActivityOrWindow(App.RootViewController)
                .ExecuteAsync();
   

Schritt 4: Registrieren eines URL-Schemas

MSAL.NET verwendet URLs, um den Broker aufzurufen und die Brokerantwort dann an Ihre App zurückzugeben. Um die Rundreise abzuschließen, registrieren Sie in der Datei Info.plist das URL-Schema Ihrer App.

Führen Sie die folgenden Schritte aus, um das URL-Schema Ihrer App zu registrieren:

1. Stellen Sie CFBundleURLSchemesmsauth voran.

2. Fügen Sie CFBundleURLName am Ende hinzu. Folgen Sie diesem Muster:

   $"msauth.(BundleId)"

   Hier identifiziert BundleId Ihr Gerät eindeutig. Wenn BundleId z. B. yourcompany.xforms ist, lautet Ihr URL-Schema msauth.com.yourcompany.xforms.

   Dieses URL-Schema wird Teil des Umleitungs-URI, der Ihre App eindeutig identifiziert, wenn er die Antwort des Brokers empfängt.

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

Schritt 5: Hinzufügen zum Abschnitt LSApplicationQueriesSchemes

MSAL verwendet –canOpenURL:, um zu überprüfen, ob der Broker auf dem Gerät installiert ist. Unter iOS 9 wurden die Schemas, die von einer Anwendung abgefragt werden können, von Apple fest vorgegeben.

Fügen Sie dem Abschnitt LSApplicationQueriesSchemes der Info.plist-Datei msauthv2 hinzu, wie im folgenden Codebeispiel zu sehen:

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

Brokerauthentifizierung für MSAL für iOS und macOS

Brokerauthentifizierung ist für Microsoft Entra-Szenarien standardmäßig aktiviert.

Schritt 1: Aktualisieren von AppDelegate zum Verarbeiten des Rückrufs

Wenn MSAL für iOS und macOS den Broker aufruft, führt der Broker einen Rückruf Ihrer Anwendung mithilfe der openURL-Methode aus. Da MSAL auf die Antwort vom Broker wartet, muss Ihre Anwendung kooperieren, um MSAL zurückzurufen. Sie richten diese Funktionalität durch Aktualisieren der Datei AppDelegate.m zum Überschreiben der Methode ein, wie aus den folgenden Codebeispielen zu ersehen.

- (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)
    }

Wenn Sie UISceneDelegate unter iOS 13 oder höher eingeführt haben, platzieren Sie den MSAL-Rückruf stattdessen in den scene:openURLContexts: von UISceneDelegate. MSAL handleMSALResponse:sourceApplication: darf für jede URL nur ein Mal aufgerufen werden.

Weitere Informationen finden Sie in der Apple-Dokumentation.

Schritt 2: Registrieren eines URL-Schemas

MSAL für iOS und macOS verwendet URLs, um den Broker aufzurufen und die Brokerantwort dann an Ihre App zurückzugeben. Um den Roundtrip abzuschließen, registrieren Sie in der Datei Info.plist ein URL-Schema für Ihre App.

So registrieren Sie ein Schema für Ihre App:

1. Stellen Sie dem benutzerdefinierten URL-Schema msauth als Präfix voran.

2. Fügen Sie Ihren Bundlebezeichner am Ende Ihres Schemas hinzu. Folgen Sie diesem Muster:

   $"msauth.(BundleId)"

   Hier identifiziert BundleId Ihr Gerät eindeutig. Wenn BundleId z. B. yourcompany.xforms ist, lautet Ihr URL-Schema msauth.com.yourcompany.xforms.

   Dieses URL-Schema wird Teil des Umleitungs-URI, der Ihre App eindeutig identifiziert, wenn er die Antwort des Brokers empfängt. Stellen Sie sicher, dass der Umleitungs-URI im Format msauth.(BundleId)://auth für Ihre Anwendung registriert ist.

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>msauth.[BUNDLE_ID]</string>
           </array>
       </dict>
   </array>
   

Schritt 3: Hinzufügen von LSApplicationQueriesSchemes

Fügen Sie LSApplicationQueriesSchemes hinzu, um Aufrufe an die Microsoft Authenticator-App zuzulassen, wenn sie installiert ist.

Hier sehen Sie ein Beispiel für das Hinzufügen von LSApplicationQueriesSchemes:

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

Brokerauthentifizierung für Xamarin.Android

Informationen zum Aktivieren eines Brokers unter Android finden Sie unter Brokerauthentifizierung in Xamarin.Android.

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Abrufen eines Tokens.