Mengonfigurasi aplikasi seluler yang memanggil API web

Artikel
10/24/2023

Setelah membuat aplikasi, Anda akan mempelajari cara mengonfigurasi kode menggunakan parameter pendaftaran aplikasi. Aplikasi seluler menyajikan beberapa kompleksitas yang terkait dengan pencocokan ke dalam kerangka pembuatannya.

Pustaka Microsoft yang mendukung aplikasi seluler

Pustaka Microsoft berikut ini mendukung aplikasi seluler:

Platform	Proyek di GitHub	Paket	Persiapan memulai	Tersedia secara umum (GA) atau Pratinjau umum¹
Android (Java)	MSAL Android	MSAL	Mulai Cepat	GA
Android (Kotlin)	MSAL Android	MSAL	—	GA
iOS (Swift/Obj-C)	MSAL untuk iOS dan macOS	MSAL	Tutorial	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹Ketentuan Lisensi Universal untuk Layanan Online berlaku untuk pustaka di Pratinjau publik.

Menginstantiasi aplikasi

Android

Aplikasi seluler menggunakan kelas PublicClientApplication. Berikut cara membuat instansnya:

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

iOS

Aplikasi seluler di iOS perlu membuat instan kelas MSALPublicClientApplication. Untuk membuat instantiate class, gunakan kode berikut.

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

Properti MSALPublicClientApplicationConfig tambahan dapat menimpa otoritas default, menspesifikasikan URI pengalihan, atau mengubah perilaku cache token MSAL.

Xamarin atau UWP

Bagian ini menjelaskan cara membuat instan aplikasi untuk aplikasi Xamarin.iOS, Xamarin.Android, dan UWP.

Menginstantiasi aplikasi

Dalam Xamarin atau UWP, cara paling sederhana untuk membuat instans aplikasi adalah menggunakan kode berikut. Dalam kode ini, ClientId adalah GUID dari aplikasi terdaftar Anda.

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

Metode With<Parameter> tambahan mengatur induk UI, mengganti otoritas default, menspesifikasikan nama klien dan versi untuk telemetri, menentukan URI pengalihan, dan menentukan pabrik HTTP yang akan digunakan. Pabrik HTTP dapat digunakan, misalnya, untuk menangani proksi dan menentukan telemetri dan pencatatan.

Bagian berikut ini menyediakan informasi selengkapnya tentang membuat instans aplikasi.

Tentukan UI, jendela, atau aktivitas induk

Di Android, teruskan aktivitas induk sebelum Anda melakukan autentikasi interaktif. Di iOS, saat Anda menggunakan broker, teruskan ViewController. Dengan cara yang sama pada UWP, Anda mungkin ingin meneruskan ke jendela induk. Anda meneruskannya ketika Anda memperoleh token. Tetapi saat membuat aplikasi, Anda juga dapat menentukan callback sebagai delegasi yang mengembalikan UIParent.

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

Di Android, kami sarankan Anda menggunakan CurrentActivityPlugin. Kode pembuat PublicClientApplication yang dihasilkan terlihat seperti contoh ini:

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

Menemukan parameter pembangun aplikasi lainnya

Untuk daftar semua metode yang tersedia di PublicClientApplicationBuilder, lihat Daftar metode.

Untuk deskripsi semua opsi yang diekspos pada PublicClientApplicationOptions, lihat dokumentasi referensi.

Tugas untuk Xamarin iOS

Jika Anda menggunakan MSAL.NET di Xamarin iOS, lakukan tugas berikut.

Untuk informasi selengkapnya, lihat Pertimbangan Xamarin iOS.

Tugas untuk MSAL untuk iOS dan macOS

Tugas-tugas ini diperlukan saat Anda menggunakan MSAL untuk iOS dan macOS:

Tugas untuk Xamarin.Android

Jika Anda menggunakan Xamarin.Android, lakukan tugas berikut:

Untuk informasi selengkapnya, lihat Pertimbangan Xamarin.Android.

Untuk pertimbangan tentang browser di Android, lihat pertimbangan spesifik Xamarin.Android dengan MSAL.NET.

Tugas untuk UWP

Di UWP, Anda dapat menggunakan jaringan perusahaan. Bagian berikut menjelaskan tugas yang harus Anda selesaikan dalam skenario korporat.

Untuk informasi selengkapnya, lihat pertimbangan spesifik UWP dengan MSAL.NET.

Mengonfigurasi aplikasi untuk menggunakan broker

Di Android dan iOS, broker mengaktifkan:

Akses menyeluruh (SSO): Anda dapat menggunakan SSO untuk perangkat yang terdaftar di Microsoft Entra ID. Saat Anda menggunakan SSO, pengguna Anda tidak perlu masuk ke setiap aplikasi.
Identifikasi perangkat: Pengaturan ini memungkinkan kebijakan akses bersyarkat yang terkait dengan perangkat Microsoft Entra. Proses autentikasi menggunakan sertifikat perangkat yang dibuat ketika perangkat bergabung ke tempat kerja.
Verifikasi identifikasi aplikasi: Ketika aplikasi memanggil broker, aplikasi melewati URL pengalihannya. Lalu, broker memverifikasinya.

Mengaktifkan broker di Xamarin

Untuk mengaktifkan broker di Xamarin, gunakan parameter WithBroker() ketika Anda memanggil metode PublicClientApplicationBuilder.CreateApplication. Secara default, .WithBroker() diatur ke true.

Untuk mengaktifkan autentikasi broker untuk Xamarin.iOS, ikuti langkah-langkah di bagian Xamarin.iOS dalam artikel ini.

Mengaktifkan broker untuk MSAL untuk Android

Untuk informasi tentang mengaktifkan broker di Android, lihat Autentikasi broker di Android.

Mengaktifkan broker untuk MSAL untuk iOS dan macOS

Autentikasi broker diaktifkan secara default untuk skenario Microsoft Entra di MSAL untuk iOS dan macOS.

Bagian berikut ini menyediakan instruksi untuk mengonfigurasi aplikasi Anda untuk dukungan autentikasi broker untuk MSAL untuk Xamarin.iOS atau MSAL untuk iOS dan macOS. Dalam kedua set instruksi, ada beberapa langkah berbeda.

Mengaktifkan autentikasi broker untuk Xamarin iOS

Ikuti langkah-langkah di bagian ini untuk mengaktifkan aplikasi Xamarin.iOS Anda untuk berbicara dengan aplikasi Microsoft Authenticator.

Langkah 1: Aktifkan dukungan broker

Dukungan broker dinonaktifkan secara default. Anda mengaktifkannya untuk kelas PublicClientApplication individu. Gunakan parameter WithBroker() saat Anda membuat kelas PublicClientApplication melalui PublicClientApplicationBuilder. Parameter WithBroker() diatur ke true secara default.

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

Langkah 2: Perbarui AppDelegate untuk menangani callback

Ketika MSAL.NET memanggil broker, broker kemudian memanggil kembali ke aplikasi Anda. Ini memanggil kembali menggunakan metode AppDelegate.OpenUrl. Karena MSAL menunggu respons dari broker, aplikasi Anda harus bekerja sama untuk memanggil MSAL.NET. Anda mengatur perilaku ini dengan memperbarui file AppDelegate.cs untuk menimpa metode, seperti yang ditunjukkan oleh kode berikut.

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

Metode ini dipanggil setiap kali aplikasi dijalankan. Ini digunakan sebagai kesempatan untuk memproses respons dari broker dan menyelesaikan proses autentikasi yang telah dimulai oleh MSAL.NET.

Langkah 3: Atur UIViewController()

Untuk Xamarin iOS, Anda biasanya tidak perlu mengatur jendela objek. Tetapi dalam hal ini Anda harus mengaturnya sehingga Anda dapat mengirim dan menerima tanggapan dari broker. Untuk mengatur jendela objek, di AppDelegate.cs, Anda mengatur ViewController.

Untuk mengatur jendela objek, ikuti langkah-langkah berikut:

Dalam AppDelegate.cs, atur App.RootViewController ke UIViewController() yang baru. Pengaturan ini memastikan bahwa panggilan ke broker mencakup UIViewController. Jika tidak diatur dengan benar, Anda mungkin mendapatkan kesalahan ini:

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

Pada panggilan AcquireTokenInteractive, gunakan .WithParentActivityOrWindow(App.RootViewController). Teruskan referensi ke jendela objek yang akan Anda gunakan. Berikut contohnya:

Di App.cs:

   public static object RootViewController { get; set; }

Di AppDelegate.cs:

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

Dalam panggilan AcquireToken:

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

Langkah 4: Daftarkan skema URL

MSAL.NET menggunakan URL untuk memanggil broker, lalu mengembalikan respons broker ke aplikasi Anda. Untuk menyelesaikan perjalanan pulang pergi, daftarkan skema URL aplikasi Anda dalam file Info.plist.

Untuk mendaftarkan skema URL aplikasi Anda, ikuti langkah-langkah berikut:

Awalan CFBundleURLSchemes dengan msauth.

Tambahkan CFBundleURLName ke akhir. Ikuti pola ini:

$"msauth.(BundleId)"

Di sini, BundleId secara unik mengidentifikasi perangkat Anda. Misalnya, jika BundleId adalah yourcompany.xforms, skema URL Anda adalah msauth.com.yourcompany.xforms.

Skema URL ini menjadi bagian dari URI pengalihan, yang secara unik mengidentifikasi aplikasi ketika menerima respons dari broker.

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

Langkah 5: Tambahkan ke bagian LSApplicationQueriesSchemes

MSAL menggunakan –canOpenURL: untuk memeriksa apakah broker diinstal pada perangkat. Di iOS 9, Apple mengunci skema yang dapat dikueri oleh aplikasi.

Tambahkan msauthv2 ke bagianLSApplicationQueriesSchemes dari file Info.plist, seperti dalam contoh kode berikut:

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

Autentikasi broker untuk MSAL untuk iOS dan macOS

Autentikasi broker diaktifkan secara default untuk skenario Microsoft Entra.

Langkah 1: Perbarui AppDelegate untuk menangani callback

Saat MSAL untuk iOS dan macOS memanggil broker, broker akan memanggil balik ke aplikasi Anda menggunakan metode openURL. Karena MSAL menunggu respons dari broker, aplikasi Anda harus bekerja sama untuk memanggil balik MSAL. Atur perilaku ini dengan memperbarui file AppDelegate.m untuk menimpa metode, seperti yang ditunjukkan oleh kode berikut.

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

Jika Anda mengadopsi UISceneDelegate di iOS 13 atau versi lebih baru, lalu menempatkan callback MSAL ke scene:openURLContexts: dari UISceneDelegate sebagai gantinya. MSAL handleMSALResponse:sourceApplication: harus dipanggil hanya sekali untuk setiap URL.

Untuk informasi selengkapnya, lihat dokumentasi Apple.

Langkah 2: Daftarkan skema URL

MSAL untuk iOS dan macOS menggunakan URL untuk memanggil broker, lalu mengembalikan respons broker ke aplikasi Anda. Untuk menyelesaikan perjalanan pulang pergi, daftarkan skema URL untuk aplikasi Anda dalam file Info.plist.

Untuk mendaftarkan skema untuk aplikasi Anda:

Awali skema URL kustom Anda dengan msauth.
Tambahkan pengidentifikasi bundel Anda ke akhir skema Anda. Ikuti pola ini:

$"msauth.(BundleId)"

Di sini, BundleId secara unik mengidentifikasi perangkat Anda. Misalnya, jika BundleId adalah yourcompany.xforms, skema URL Anda adalah msauth.com.yourcompany.xforms.

Skema URL ini menjadi bagian dari URI pengalihan, yang secara unik mengidentifikasi aplikasi ketika menerima respons dari broker. Pastikan bahwa URI pengalihan dalam format msauth.(BundleId)://auth terdaftar untuk aplikasi Anda.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Langkah 3: Tambahkan LSApplicationQueriesSchemes

Tambahkan LSApplicationQueriesSchemes untuk mengizinkan panggilan ke aplikasi Microsoft Authenticator, jika diinstal.

Catatan

Skema msauthv3 ini diperlukan saat aplikasi Anda dikompilasi menggunakan Xcode 11 dan yang lebih baru.

Berikut adalah contoh cara menambahkan LSApplicationQueriesSchemes:

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

Autentikasi broker untuk Xamarin.Android

Untuk informasi tentang mengaktifkan broker di Android, lihat Autentikasi broker di Xamarin.Android.

Langkah berikutnya

Lanjutkan ke artikel berikutnya dalam skenario ini, yaitu Mendapatkan token.

Mengonfigurasi aplikasi seluler yang memanggil API web

Pustaka Microsoft yang mendukung aplikasi seluler

Menginstantiasi aplikasi

Android

iOS

Xamarin atau UWP

Menginstantiasi aplikasi

Tentukan UI, jendela, atau aktivitas induk

Menemukan parameter pembangun aplikasi lainnya

Tugas untuk Xamarin iOS

Tugas untuk MSAL untuk iOS dan macOS

Tugas untuk Xamarin.Android

Tugas untuk UWP

Mengonfigurasi aplikasi untuk menggunakan broker

Mengaktifkan broker di Xamarin

Mengaktifkan broker untuk MSAL untuk Android

Mengaktifkan broker untuk MSAL untuk iOS dan macOS

Mengaktifkan autentikasi broker untuk Xamarin iOS

Langkah 1: Aktifkan dukungan broker

Langkah 2: Perbarui AppDelegate untuk menangani callback

Langkah 3: Atur UIViewController()

Langkah 4: Daftarkan skema URL

Langkah 5: Tambahkan ke bagian LSApplicationQueriesSchemes

Autentikasi broker untuk MSAL untuk iOS dan macOS

Langkah 1: Perbarui AppDelegate untuk menangani callback

Langkah 2: Daftarkan skema URL

Langkah 3: Tambahkan LSApplicationQueriesSchemes

Autentikasi broker untuk Xamarin.Android

Langkah berikutnya

Sumber Daya Tambahan: