Konfigurowanie aplikacji mobilnej wywołującej internetowe interfejsy API

Artykuł
10/24/2023

Po utworzeniu aplikacji dowiesz się, jak skonfigurować kod przy użyciu parametrów rejestracji aplikacji. Aplikacje mobilne przedstawiają pewne złożoności związane z dopasowaniem ich struktury tworzenia.

Biblioteki firmy Microsoft obsługujące aplikacje mobilne

Następujące biblioteki firmy Microsoft obsługują aplikacje mobilne:

Platforma	Projekt w dniu GitHub	Pakiet	Coraz pracę	Ogólnie dostępne (ogólna dostępność) lub Publiczna wersja zapoznawcza¹
Android (Java)	MSAL Android	BIBLIOTEKA MSAL	Szybki start	Ogólna dostępność
Android (Kotlin)	MSAL Android	BIBLIOTEKA MSAL	—	Ogólna dostępność
iOS (Swift/Obj-C)	Biblioteka MSAL dla systemów iOS i macOS	BIBLIOTEKA MSAL	Samouczek	Ogólna dostępność
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	Ogólna dostępność

¹ Uniwersalne postanowienia licencyjne dotyczące usług online mają zastosowanie do bibliotek w publicznej wersji zapoznawczej.

Tworzenie wystąpienia aplikacji

Android

Aplikacje mobilne używają PublicClientApplication klasy . Oto jak utworzyć wystąpienie:

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

iOS

Aplikacje mobilne w systemie iOS muszą utworzyć wystąpienie MSALPublicClientApplication klasy. Aby utworzyć wystąpienie klasy, użyj następującego kodu.

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

Dodatkowe właściwości MSALPublicClientApplicationConfig mogą zastąpić domyślny urząd, określić identyfikator URI przekierowania lub zmienić zachowanie buforowania tokenu biblioteki MSAL.

Xamarin lub UWP

W tej sekcji wyjaśniono, jak utworzyć wystąpienie aplikacji dla aplikacji platformY Xamarin.iOS, Xamarin.Android i platformy UWP.

Uwaga

MSAL.NET w wersji 4.61.0 lub nowszej nie zapewniają obsługi platforma uniwersalna systemu Windows (UWP), Xamarin Android i Xamarin iOS. Zalecamy migrację aplikacji platformy Xamarin do nowoczesnych struktur, takich jak MAUI. Przeczytaj więcej o wycofaniu w temacie Ogłaszanie nadchodzącego wycofania MSAL.NET dla platform Xamarin i platformy UWP.

Tworzenie wystąpienia aplikacji

W środowisku Xamarin lub uwP najprostszym sposobem utworzenia wystąpienia aplikacji jest użycie następującego kodu. W tym kodzie ClientId jest identyfikator GUID zarejestrowanej aplikacji.

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

Dodatkowe With<Parameter> metody ustawiają nadrzędny interfejs użytkownika, przesłaniają domyślny urząd, określają nazwę klienta i wersję telemetrii, określ identyfikator URI przekierowania i określ fabrykę HTTP do użycia. Fabryka HTTP może służyć na przykład do obsługi serwerów proxy i określania telemetrii i rejestrowania.

Poniższe sekcje zawierają więcej informacji na temat tworzenia wystąpienia aplikacji.

Określanie nadrzędnego interfejsu użytkownika, okna lub działania

W systemie Android przekaż działanie nadrzędne przed wykonaniem uwierzytelniania interakcyjnego. W systemie iOS, gdy używasz brokera, przekaż wartość ViewController. W ten sam sposób w systemie UWP możesz przekazać okno nadrzędne. Przekazujesz go podczas uzyskiwania tokenu. Jednak podczas tworzenia aplikacji można również określić wywołanie zwrotne jako delegat, który zwraca wartość UIParent.

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

W systemie Android zalecamy użycie polecenia CurrentActivityPlugin. Wynikowy PublicClientApplication kod konstruktora wygląda następująco:

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

Znajdowanie dodatkowych parametrów tworzenia aplikacji

Aby uzyskać listę wszystkich metod dostępnych w PublicClientApplicationBuilderwitrynie , zobacz listę Metod.

Opis wszystkich opcji uwidocznionych w programie można znaleźć w PublicClientApplicationOptionsdokumentacji referencyjnej.

Zadania dotyczące biblioteki MSAL dla systemów iOS i macOS

Te zadania są niezbędne w przypadku korzystania z biblioteki MSAL dla systemów iOS i macOS:

Zadania dla platformy Xamarin.Android

Jeśli używasz platformy Xamarin.Android, wykonaj następujące zadania:

Aby uzyskać więcej informacji, zobacz Zagadnienia dotyczące platformy Xamarin.Android.

Aby zapoznać się z zagadnieniami dotyczącymi przeglądarek w systemie Android, zobacz Zagadnienia specyficzne dla platformy Xamarin.Android dotyczące MSAL.NET.

Zadania dla platformy UWP

W systemie UWP można używać sieci firmowych. W poniższych sekcjach opisano zadania, które należy wykonać w scenariuszu firmowym.

Aby uzyskać więcej informacji, zobacz Zagadnienia specyficzne dla platformy UNIWERSALNEJ systemu Windows dotyczące MSAL.NET.

Konfigurowanie aplikacji do korzystania z brokera

W systemach Android i iOS brokerzy włączają:

Logowanie jednokrotne (SSO): możesz użyć logowania jednokrotnego dla urządzeń zarejestrowanych w usłudze Microsoft Entra ID. W przypadku korzystania z logowania jednokrotnego użytkownicy nie muszą logować się do każdej aplikacji.
Identyfikacja urządzenia: to ustawienie umożliwia zasady dostępu warunkowego powiązane z urządzeniami firmy Microsoft Entra. Proces uwierzytelniania używa certyfikatu urządzenia utworzonego podczas dołączania urządzenia do miejsca pracy.
Weryfikacja identyfikacji aplikacji: gdy aplikacja wywołuje brokera, przekazuje adres URL przekierowania. Następnie broker weryfikuje go.

Włączanie brokera na platformie Xamarin

Aby włączyć brokera na platformie Xamarin, użyj parametru WithBroker() podczas wywoływania PublicClientApplicationBuilder.CreateApplication metody. Domyślnie .WithBroker() jest ustawiona wartość true.

Aby włączyć uwierzytelnianie obsługiwane przez brokera dla platformy Xamarin.iOS, wykonaj kroki opisane w sekcji Xamarin.iOS w tym artykule.

Włączanie brokera dla biblioteki MSAL dla systemu Android

Aby uzyskać informacje na temat włączania brokera w systemie Android, zobacz Brokered authentication on Android (Uwierzytelnianie obsługiwane przez brokera w systemie Android).

Włączanie brokera dla biblioteki MSAL dla systemów iOS i macOS

Uwierzytelnianie obsługiwane przez brokera jest domyślnie włączone dla scenariuszy firmy Microsoft Entra w usłudze MSAL dla systemów iOS i macOS.

Poniższe sekcje zawierają instrukcje dotyczące konfigurowania aplikacji na potrzeby obsługi uwierzytelniania obsługiwanego przez brokera dla biblioteki MSAL dla platformY Xamarin.iOS lub MSAL dla systemów iOS i macOS. W dwóch zestawach instrukcji niektóre kroki różnią się.

Włączanie uwierzytelniania obsługiwanego przez brokera dla platformy Xamarin dla systemu iOS

Wykonaj kroki opisane w tej sekcji, aby umożliwić aplikacji Xamarin.iOS rozmowę z aplikacją Microsoft Authenticator .

Krok 1. Włączanie obsługi brokera

Obsługa brokera jest domyślnie wyłączona. Można ją włączyć dla pojedynczej PublicClientApplication klasy. Użyj parametru WithBroker() PublicClientApplication podczas tworzenia klasy za pomocą PublicClientApplicationBuildermetody . Parametr WithBroker() jest domyślnie ustawiony na wartość true.

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

Krok 2. Aktualizowanie elementu AppDelegate w celu obsługi wywołania zwrotnego

Gdy MSAL.NET wywołuje brokera, broker wywołuje go z powrotem do aplikacji. Wywołuje ją z powrotem przy użyciu AppDelegate.OpenUrl metody . Ponieważ biblioteka MSAL czeka na odpowiedź od brokera, aplikacja musi współpracować, aby wywołać MSAL.NET z powrotem. To zachowanie można skonfigurować, aktualizując AppDelegate.cs plik w celu zastąpienia metody, jak pokazano w poniższym kodzie.

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

Ta metoda jest wywoływana za każdym razem, gdy aplikacja jest uruchamiana. Jest to możliwość przetworzenia odpowiedzi od brokera i ukończenia procesu uwierzytelniania, który MSAL.NET rozpoczęty.

Krok 3. Ustawianie kontrolki UIViewController()

W przypadku systemu IOS platformy Xamarin zwykle nie trzeba ustawiać okna obiektu. Jednak w tym przypadku należy ustawić ją tak, aby można było wysyłać i odbierać odpowiedzi od brokera. Aby ustawić okno obiektu, w AppDelegate.cspliku należy ustawić ViewControllerwartość .

Aby ustawić okno obiektu, wykonaj następujące kroki:

W AppDelegate.cspliku ustaw App.RootViewController wartość na nową UIViewController(). To ustawienie zapewnia, że wywołanie brokera obejmuje UIViewControllerelement . Jeśli nie jest poprawnie ustawiona, może zostać wyświetlony następujący błąd:

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

Na wywołaniu AcquireTokenInteractive użyj polecenia .WithParentActivityOrWindow(App.RootViewController). Przekaż odwołanie do okna obiektu, którego użyjesz. Oto przykład:

W pliku App.cs:

   public static object RootViewController { get; set; }

W pliku AppDelegate.cs:

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

W wywołaniu AcquireToken :

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

Krok 4. Rejestrowanie schematu adresów URL

MSAL.NET używa adresów URL, aby wywołać brokera, a następnie zwrócić odpowiedź brokera z powrotem do aplikacji. Aby zakończyć rundę, zarejestruj schemat adresu URL aplikacji w Info.plist pliku.

Aby zarejestrować schemat adresów URL aplikacji, wykonaj następujące kroki:

Prefiks CFBundleURLSchemes z .msauth
Dodaj CFBundleURLName do końca. Postępuj zgodnie z tym wzorcem:

$"msauth.(BundleId)"

BundleId W tym miejscu unikatowo identyfikuje urządzenie. Jeśli na przykład BundleId to yourcompany.xforms, schemat adresu URL to msauth.com.yourcompany.xforms.

Ten schemat adresów URL stanie się częścią identyfikatora URI przekierowania, który jednoznacznie identyfikuje aplikację po odebraniu odpowiedzi brokera.
```
 <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>
```

Krok 5. Dodawanie do sekcji LSApplicationQueriesSchemes

Biblioteka MSAL używa –canOpenURL: narzędzia do sprawdzania, czy broker jest zainstalowany na urządzeniu. W systemie iOS 9 firma Apple zablokowała schematy, dla których aplikacja może wykonywać zapytania.

Dodaj msauthv2 do LSApplicationQueriesSchemes sekcji Info.plist pliku, jak w poniższym przykładzie kodu:

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

Uwierzytelnianie obsługiwane przez brokera dla biblioteki MSAL dla systemów iOS i macOS

Uwierzytelnianie obsługiwane przez brokera jest domyślnie włączone dla scenariuszy firmy Microsoft Entra.

Krok 1. Aktualizowanie elementu AppDelegate w celu obsługi wywołania zwrotnego

Gdy biblioteka MSAL dla systemów iOS i macOS wywołuje brokera, broker wywołuje aplikację przy użyciu openURL metody . Ponieważ biblioteka MSAL czeka na odpowiedź od brokera, aplikacja musi współpracować w celu wywołania biblioteki MSAL. Skonfiguruj tę funkcję, aktualizując AppDelegate.m plik w celu zastąpienia metody, jak pokazano w poniższych przykładach kodu.

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

Jeśli przyjęto w UISceneDelegate systemie iOS 13 lub nowszym, należy umieścić wywołanie zwrotne biblioteki MSAL w scene:openURLContexts: UISceneDelegate zamiast. Biblioteka MSAL handleMSALResponse:sourceApplication: musi być wywoływana tylko raz dla każdego adresu URL.

Aby uzyskać więcej informacji, zobacz dokumentację firmy Apple.

Krok 2. Rejestrowanie schematu adresów URL

Biblioteka MSAL dla systemów iOS i macOS używa adresów URL do wywoływania brokera, a następnie zwraca odpowiedź brokera do aplikacji. Aby zakończyć rundę, zarejestruj schemat adresów URL aplikacji w Info.plist pliku.

Aby zarejestrować schemat dla aplikacji:

Prefiks niestandardowego schematu adresów URL za pomocą polecenia msauth.
Dodaj identyfikator pakietu na końcu schematu. Postępuj zgodnie z tym wzorcem:

$"msauth.(BundleId)"

BundleId W tym miejscu unikatowo identyfikuje urządzenie. Jeśli na przykład BundleId to yourcompany.xforms, schemat adresu URL to msauth.com.yourcompany.xforms.

Ten schemat adresów URL stanie się częścią identyfikatora URI przekierowania, który jednoznacznie identyfikuje aplikację po odebraniu odpowiedzi brokera. Upewnij się, że identyfikator URI przekierowania w formacie msauth.(BundleId)://auth jest zarejestrowany dla aplikacji.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Krok 3. Dodawanie LSApplicationQueriesSchemes

Dodaj LSApplicationQueriesSchemes , aby zezwolić na wywołania aplikacji Microsoft Authenticator, jeśli jest zainstalowana.

Uwaga

Schemat msauthv3 jest wymagany, gdy aplikacja jest kompilowana przy użyciu środowiska Xcode 11 lub nowszego.

Oto przykład dodawania LSApplicationQueriesSchemeselementu :

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

Uwierzytelnianie obsługiwane przez brokera dla platformy Xamarin.Android

Aby uzyskać informacje na temat włączania brokera w systemie Android, zobacz Brokered authentication on Xamarin.Android (Uwierzytelnianie obsługiwane przez brokera na platformie Xamarin.Android).

Następne kroki

Przejdź do następnego artykułu w tym scenariuszu Uzyskiwanie tokenu.

Udostępnij za pośrednictwem

Konfigurowanie aplikacji mobilnej wywołującej internetowe interfejsy API

Biblioteki firmy Microsoft obsługujące aplikacje mobilne

Tworzenie wystąpienia aplikacji

Android

iOS

Xamarin lub UWP

Tworzenie wystąpienia aplikacji

Określanie nadrzędnego interfejsu użytkownika, okna lub działania

Znajdowanie dodatkowych parametrów tworzenia aplikacji

Zadania dotyczące biblioteki MSAL dla systemów iOS i macOS

Zadania dla platformy Xamarin.Android

Zadania dla platformy UWP

Konfigurowanie aplikacji do korzystania z brokera

Włączanie brokera na platformie Xamarin

Włączanie brokera dla biblioteki MSAL dla systemu Android

Włączanie brokera dla biblioteki MSAL dla systemów iOS i macOS

Włączanie uwierzytelniania obsługiwanego przez brokera dla platformy Xamarin dla systemu iOS

Krok 1. Włączanie obsługi brokera

Krok 2. Aktualizowanie elementu AppDelegate w celu obsługi wywołania zwrotnego

Krok 3. Ustawianie kontrolki UIViewController()

Krok 4. Rejestrowanie schematu adresów URL

Krok 5. Dodawanie do sekcji LSApplicationQueriesSchemes

Uwierzytelnianie obsługiwane przez brokera dla biblioteki MSAL dla systemów iOS i macOS

Krok 1. Aktualizowanie elementu AppDelegate w celu obsługi wywołania zwrotnego

Krok 2. Rejestrowanie schematu adresów URL

Krok 3. Dodawanie LSApplicationQueriesSchemes

Uwierzytelnianie obsługiwane przez brokera dla platformy Xamarin.Android

Następne kroki

Opinia

Dodatkowe zasoby