Aktifkan opsi otentikasi di aplikasi iOS Swift dengan menggunakan Azure AD B2C

Artikel
01/11/2024

Artikel ini menjelaskan cara Anda dapat mengaktifkan, menyesuaikan, dan meningkatkan pengalaman otentikasi Azure Active Directory B2C (Azure AD B2C) untuk aplikasi iOS Swift Anda.

Sebelum Anda mulai, biasakan diri Anda dengan artikel berikut:

Konfigurasikan autentikasi dalam contoh aplikasi iOS Swift menggunakan Azure AD B2C
Aktifkan autentikasi di aplikasi Swift iOS Anda sendiri dengan menggunakan Azure AD B2C

Menggunakan domain kustom

Dengan menggunakan domain kustom, Anda dapat sepenuhnya menandai URL autentikasi. Dari perspektif pengguna, pengguna tetap berada di domain Anda selama proses autentikasi, bukan dialihkan ke nama domain b2clogin.com Azure Active Directory B2C.

Untuk menghapus semua referensi “b2c” pada URL, Anda dapat mengganti nama penyewa B2C Anda, contoso.onmicrosoft.com, pada URL permintaan autentikasi dengan pengidentifikasi unik ID penyewa Anda. Misalnya, Anda dapat mengubah https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ menjadi https://account.contosobank.co.uk/<tenant ID GUID>/.

Untuk menggunakan domain kustom dan ID penyewa Anda di URL autentikasi, lakukan hal berikut:

Ikuti panduan di Mengaktifkan domain kustom.
Perbarui anggota kelas kAuthorityHostName dengan domain kustom Anda.
Perbarui anggota kelas kTenantName dengan ID penyewa Anda.

Kode Swift berikut menunjukkan pengaturan aplikasi sebelum perubahan:

let kTenantName = "contoso.onmicrosoft.com" 
let kAuthorityHostName = "contoso.b2clogin.com"

Kode Swift berikut menunjukkan pengaturan aplikasi setelah perubahan:

let kTenantName = "00000000-0000-0000-0000-000000000000" 
let kAuthorityHostName = "login.contoso.com"

Selama perjalanan pengguna masuk, aplikasi Anda mungkin menargetkan pengguna tertentu. Saat aplikasi menargetkan pengguna, aplikasi dapat menentukan permintaan otorisasi login_hint parameter kueri dengan nama rincian masuk pengguna. Azure Active Directory B2C secara otomatis mengisi nama rincian masuk, dan pengguna hanya perlu memberikan kata sandi.

Untuk mengisi nama rincian masuk terlebih dahulu, lakukan hal berikut:

Jika Anda menggunakan kebijakan kustom, tambahkan klaim input yang diperlukan, seperti yang dijelaskan dalam Menyiapkan masuk langsung.
Cari objek konfigurasi Microsoft Authentication Library (MSAL) Anda, lalu tambahkan metode withLoginHint() dengan petunjuk masuk.

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.loginHint = "bob@contoso.com"
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Memilih sebelumnya penyedia identitas

Jika Anda mengonfigurasi perjalanan rincian masuk untuk aplikasi Anda untuk menyertakan akun sosial, seperti Facebook, LinkedIn, atau Google, Anda dapat menentukan parameter domain_hint. Parameter kueri ini memberikan petunjuk untuk Azure AD B2C tentang IdP sosial yang harus digunakan untuk rincian masuk. Misalnya, jika aplikasi menentukan domain_hint=facebook.com, alur masuk langsung menuju ke halaman masuk Facebook.

Untuk mengalihkan pengguna ke penyedia identitas eksternal, lakukan tindakan berikut:

Periksa nama domain penyedia identitas eksternal Anda. Untuk informasi selengkapnya, lihat Mengalihkan rincian masuk ke penyedia sosial.
Buat atau Gunakan objek daftar yang sudah ada untuk menyimpan parameter kueri tambahan.
Tambahkan parameter domain_hint dengan nama domain yang sesuai ke daftar (misalnya, facebook.com).
Teruskan daftar parameter kueri tambahan ke dalam atribut extraQueryParameters objek konfigurasi MSAL.

let extraQueryParameters: [String: String] = ["domain_hint": "facebook.com"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Tentukan bahasa UI

Kustomisasi bahasa pemrogram di Microsoft Azure AD B2C memungkinkan alur pengguna Anda untuk mengakomodasi berbagai bahasa yang sesuai dengan kebutuhan pelanggan Anda. Untuk informasi selengkapnya, lihat Kustomisasi bahasa.

Untuk mengatur bahasa pilihan, lakukan hal berikut:

Mengonfigurasi penyesuaian bahasa.
Buat atau Gunakan objek daftar yang sudah ada untuk menyimpan parameter kueri tambahan.
Tambahkan parameter ui_locales dengan kode bahasa yang sesuai ke daftar (misalnya, en-us).
Teruskan daftar parameter kueri tambahan ke dalam atribut extraQueryParameters objek konfigurasi MSAL.

let extraQueryParameters: [String: String] = ["ui_locales": "en-us"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Meneruskan parameter string kueri kustom

Dengan kebijakan kustom, Anda dapat meneruskan parameter string kueri kustom. Contoh kasus penggunaan yang tepat adalah saat Anda ingin mengubah konten halaman secara dinamis.

Untuk meneruskan parameter string kueri kustom, lakukan tindakan berikut:

Konfigurasi elemen ContentDefinitionParameters.
Buat atau Gunakan objek daftar yang sudah ada untuk menyimpan parameter kueri tambahan.
Tambahkan parameter string kueri kustom, seperti campaignId. Tetapkan nilai parameter (misalnya, germany-promotion).
Teruskan daftar parameter kueri tambahan ke dalam atribut extraQueryParameters objek konfigurasi MSAL.

let extraQueryParameters: [String: String] = ["campaignId": "germany-promotion"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Meneruskan petunjuk token ID

Aplikasi pihak yang mengandalkan dapat mengirim JSON Web Token (JWT) masuk sebagai bagian dari permintaan otorisasi OAuth2. Token masuk adalah petunjuk tentang pengguna atau permintaan otorisasi. Azure AD B2C memvalidasi token, lalu mengekstrak klaim.

Untuk memasukkan petunjuk token ID dalam permintaan autentikasi, lakukan tindakan berikut:

Dalam kebijakan kustom Anda, tetapkan profil teknis petunjuk token ID.
Dalam kode Anda, buat atau dapatkan token ID, lalu setel token ke variabel (misalnya, idToken).
Buat atau Gunakan objek daftar yang sudah ada untuk menyimpan parameter kueri tambahan.
Tambahkan parameter id_token_hint dengan variabel yang sesuai yang menyimpan token ID.
Teruskan daftar parameter kueri tambahan ke dalam atribut extraQueryParameters objek konfigurasi MSAL.

let extraQueryParameters: [String: String] = ["id_token_hint": idToken]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Mengonfigurasi pengelogan

Pustaka MSAL menghasilkan pesan log yang dapat membantu mendiagnosis masalah. Aplikasi ini dapat mengonfigurasi pengelogan. Aplikasi juga dapat memberikan Anda kontrol khusus atas tingkat detail serta apakah data pribadi dan organisasi dicatat atau tidak.

Kami menyarankan Anda membuat panggilan balik pengelogan MSAL dan menyediakan cara bagi pengguna untuk mengirimkan log ketika mereka memiliki masalah autentikasi. MSAL menyediakan beberapa tingkat detail pengelogan:

Kesalahan: Menunjukkan ada sesuatu yang salah, dan kesalahan dibuat. Tingkat ini digunakan untuk penelusuran kesalahan dan mengidentifikasi masalah.
Peringatan: Belum tentu ada kesalahan atau kegagalan, tetapi ditujukan untuk diagnostik dan menentukan masalah.
Info: MSAL akan mencatat peristiwa yang ditujukan untuk tujuan informasi yang tidak selalu dimaksudkan untuk penelusuran kesalahan.
Verbose: Ini adalah tingkat default. MSAL mencatat detail lengkap perilaku pustaka.

Secara default, pencatat MSAL tidak menangkap data pribadi atau organisasi apa pun. Pustaka memberi Anda opsi untuk mengaktifkan pengelogan data pribadi dan organisasi jika Anda memutuskan untuk melakukannya.

Pencatat MSAL harus disetel sedini mungkin dalam urutan peluncuran aplikasi, sebelum permintaan MSAL dibuat. Konfigurasikan pengelogan MSAL dalam metode AppDelegate.swiftapplication.

Cuplikan kode berikut menunjukkan cara mengonfigurasi pengelogan MSAL:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        MSALGlobalConfig.loggerConfig.logLevel = .verbose
        MSALGlobalConfig.loggerConfig.setLogCallback { (logLevel, message, containsPII) in
            
            // If PiiLoggingEnabled is set YES, this block will potentially contain sensitive information (Personally Identifiable Information), but not all messages will contain it.
            // containsPII == YES indicates if a particular message contains PII.
            // You might want to capture PII only in debug builds, or only if you take necessary actions to handle PII properly according to legal requirements of the region
            if let displayableMessage = message {
                if (!containsPII) {
                    #if DEBUG
                    // NB! This sample uses print just for testing purposes
                    // You should only ever log to NSLog in debug mode to prevent leaking potentially sensitive information
                    print(displayableMessage)
                    #endif
                }
            }
        }
        return true
    }

Pengalaman tampilan web tersemat

Browser web diperlukan untuk autentikasi interaktif. Secara default, perpustakaan MSAL menggunakan tampilan web sistem. Selama masuk, perpustakaan MSAL memunculkan tampilan web sistem iOS dengan antarmuka pengguna Azure AD B2C.

Untuk informasi lebih lanjut, lihat artikel Mengkustomisasi browser dan WebViews untuk iOS/macOS.

Tergantung pada kebutuhan Anda, Anda dapat menggunakan tampilan web tertanam. Ada perbedaan perilaku visual dan masuk tunggal antara tampilan web yang disematkan dan tampilan web sistem di MSAL.

Tangkapan layar yang menunjukkan perbedaan antara pengalaman tampilan web sistem dan pengalaman tampilan web tertanam.

Penting

Kami menyarankan Anda menggunakan platform default, yang biasanya adalah browser sistem. Browser sistem lebih baik mengingat pengguna yang telah masuk sebelumnya. Beberapa penyedia identitas, seperti Google, tidak mendukung pengalaman tampilan tersemat.

Untuk mengubah perilaku ini, ubah atribut webviewType dari MSALWebviewParameters menjadi wkWebView. Contoh berikut menunjukkan cara mengubah tipe tampilan web ke tampilan tersemat:

func initWebViewParams() {
    self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    
    // Use embedded view experience
    self.webViewParameters?.webviewType = .wkWebView
}

Langkah berikutnya

Untuk mempelajari lebih lanjut, lihat Opsi konfigurasi MSAL untuk iOS Swift.

Bagikan melalui

Aktifkan opsi otentikasi di aplikasi iOS Swift dengan menggunakan Azure AD B2C

Menggunakan domain kustom

Memilih sebelumnya penyedia identitas

Tentukan bahasa UI

Meneruskan parameter string kueri kustom

Meneruskan petunjuk token ID

Mengonfigurasi pengelogan

Pengalaman tampilan web tersemat

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Aktifkan opsi otentikasi di aplikasi iOS Swift dengan menggunakan Azure AD B2C

Menggunakan domain kustom

Prepopulasi nama rincian masuk

Memilih sebelumnya penyedia identitas

Tentukan bahasa UI

Meneruskan parameter string kueri kustom

Meneruskan petunjuk token ID

Mengonfigurasi pengelogan

Pengalaman tampilan web tersemat

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: