Bagikan melalui

Tutorial: Menyiapkan aplikasi iOS (Swift) Anda untuk autentikasi

  • Artikel

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa tenaga kerja Lingkaran hijau dengan simbol tanda centang putih. Penyewa eksternal (pelajari selengkapnya)

Ini adalah tutorial kedua dalam seri tutorial yang menunjukkan cara menambahkan Microsoft Authentication Library (MSAL) untuk iOS dan macOS ke aplikasi iOS Swift Anda.

Sebelum memulai, gunakan pemilih Pilih jenis penyewa di bagian atas halaman ini untuk memilih jenis penyewa. Microsoft Entra ID menyediakan dua konfigurasi penyewa, internal dan eksternal. Konfigurasi pengguna untuk karyawan, aplikasi internal, dan sumber daya organisasi lainnya. Penyewa eksternal adalah untuk aplikasi yang digunakan oleh pelanggan Anda.

Dalam tutorial ini, Anda:

  • Tambahkan kerangka kerja MSAL ke aplikasi iOS (Swift).
  • Buat instans SDK.
  • Mengonfigurasi pengaturan proyek Xcode.

Prasyarat

  • Daftarkan aplikasi web klien baru di pusat admin Microsoft Entra, dikonfigurasi untuk Akun di direktori organisasi dan akun Microsoft pribadi apa pun. Lihat Mendaftarkan aplikasi untuk detail selengkapnya. Rekam nilai berikut dari halaman Gambaran Umum aplikasi untuk digunakan nanti:
    • ID Aplikasi (klien)
    • ID Direktori (Penyewa)
  • Kode X.
  • Proyek iOS (Swift).

Tambahkan URL pengalihan platform

Untuk menentukan jenis aplikasi ke pendaftaran aplikasi Anda, ikuti langkah-langkah berikut:

  1. Di bawah Kelola, pilih Autentikasi >Tambahkan platform>iOS/macOS.
  2. Masukkan ID Bundel proyek Anda. Jika Anda mengunduh sampel kode tersebut, ID Bundel adalah com.microsoft.identitysample.MSALiOS. Jika Anda membuat proyek Anda sendiri, pilih proyek Anda di Xcode dan buka tab Umum. Pengidentifikasi bundel muncul di bagian Identitas.
  3. Pilih Konfigurasikan dan simpan Konfigurasi MSAL yang muncul di halaman konfigurasi MSAL sehingga Anda dapat memasukkannya saat mengonfigurasi aplikasi nanti.
  4. Pilih Selesai.

Menambahkan kerangka kerja MSAL ke aplikasi iOS (Swift)

Pilih salah satu cara berikut untuk menginstal pustaka MSAL di aplikasi Anda:

CocoaPods

  1. Jika Anda menggunakan CocoaPods, instal MSAL dengan terlebih dahulu membuat file kosong yang disebut podfile di folder yang sama dengan file .xcodeproj proyek Anda. Tambahkan hal berikut ke podfile:

    use_frameworks!

target '<your-target-here>' do
   pod 'MSAL'
end

  2. Ganti <your-target-here> dengan nama proyek Anda.

  3. Di jendela terminal, navigasikan ke folder yang berisi podfile Anda buat dan jalankan pod install untuk menginstal pustaka MSAL.

  4. Tutup Xcode dan buka <your project name>.xcworkspace untuk memuat ulang proyek di Xcode.

Carthage

Jika Anda menggunakan Carthage, instal MSAL dengan menambahkannya ke CartfileAnda.

github "AzureAD/microsoft-authentication-library-for-objc" "master"

Dari jendela terminal, di direktori yang sama dengan Cartfileyang diperbarui , jalankan perintah berikut agar Carthage memperbarui dependensi dalam proyek Anda.

Ios:

carthage update --platform iOS

macOS:

carthage update --platform macOS

Secara manual

Anda juga dapat menggunakan Git Submodule, atau melihat rilis terbaru untuk digunakan sebagai kerangka kerja dalam aplikasi Anda.

Menambahkan pendaftaran aplikasi

Selanjutnya, kami menambahkan pendaftaran aplikasi Anda ke kode Anda.

Pertama, tambahkan pernyataan impor berikut ke bagian atas file ViewController.swift dan AppDelegate.swift atau SceneDelegate.swift:

import MSAL

Selanjutnya, tambahkan kode berikut ke ViewController.swift sebelumnya ke viewDidLoad():

// Update the below to your client ID. The below is for running the demo only
let kClientID = "Your_Application_Id_Here"
let kGraphEndpoint = "https://graph.microsoft.com/" // the Microsoft Graph endpoint
let kAuthority = "https://login.microsoftonline.com/common" // this authority allows a personal Microsoft account and a work or school account in any organization's Azure AD tenant to sign in

let kScopes: [String] = ["user.read"] // request permission to read the profile of the signed-in user

var accessToken = String()
var applicationContext : MSALPublicClientApplication?
var webViewParameters : MSALWebviewParameters?
var currentAccount: MSALAccount?

Satu-satunya nilai yang Anda ubah adalah nilai yang ditetapkan untuk kClientID agar menjadi ID Aplikasi Anda. Nilai ini adalah bagian dari data Konfigurasi MSAL yang Anda simpan selama langkah di awal tutorial ini untuk mendaftarkan aplikasi.

Membuat instans SDK

Untuk membuat instans MSAL di proyek Anda, ikuti langkah-langkah berikut:

Ke kelas ViewController, tambahkan metode initMSAL:

    func initMSAL() throws {

        guard let authorityURL = URL(string: kAuthority) else {
            self.updateLogging(text: "Unable to create authority URL")
            return
        }

        let authority = try MSALAADAuthority(url: authorityURL)

        let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
        self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
        self.initWebViewParams()
    }

Masih di kelas ViewController dan setelah metode initMSAL, tambahkan metode initWebViewParams:

Kode iOS:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    }

Kode macOS:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters()
    }

Mengonfigurasi pengaturan proyek Xcode

Tambahkan grup keychain baru ke proyek Anda Penandatanganan & Kemampuan. Grup rantai kunci harus com.microsoft.adalcache di iOS dan com.microsoft.identity.universalstorage di macOS.

Xcode UI yang menampilkan cara grup rantai kunci sebaiknya diatur.

Hanya untuk iOS, konfigurasikan skema URL

Dalam langkah ini, Anda akan mendaftarkan CFBundleURLSchemes sehingga pengguna dapat dialihkan kembali ke aplikasi setelah masuk. Ngomong-ngomong, LSApplicationQueriesSchemes juga memungkinkan aplikasi Anda untuk menggunakan Microsoft Authenticator.

Di Xcode, buka Info.plist sebagai file kode sumber, dan tambahkan yang berikut di dalam bagian <dict>. Ganti [BUNDLE_ID] dengan nilai yang sebelumnya Anda gunakan. Jika Anda mengunduh kode tersebut, pengidentifikasi bundelnya adalah com.microsoft.identitysample.MSALiOS. Jika Anda membuat proyek Anda sendiri, pilih proyek Anda di Xcode dan buka tab Umum. Pengidentifikasi bundel muncul di bagian Identitas.

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

Hanya untuk macOS, konfigurasikan App Sandbox

  1. Buka tab Xcode Project Settings >Capabilities>App Sandbox
  2. Pilih kotak centang Koneksi Keluar (Klien).

Langkah berikutnya

Tutorial : Memasukkan pengguna di aplikasi seluler iOS (Swift)

Ini adalah tutorial kedua dalam seri tutorial yang menunjukkan cara menambahkan Microsoft Authentication Library (MSAL) untuk iOS dan macOS ke aplikasi iOS Swift Anda.

Sebelum memulai, gunakan pemilih Pilih jenis penyewa di bagian atas halaman ini untuk memilih jenis penyewa. Microsoft Entra ID menyediakan dua konfigurasi penyewa, internal dan eksternal. Konfigurasi pengguna untuk karyawan, aplikasi internal, dan sumber daya organisasi lainnya. Penyewa eksternal adalah untuk aplikasi yang digunakan oleh pelanggan Anda.

Dalam tutorial ini, Anda;

  • Tambahkan kerangka kerja MSAL ke aplikasi iOS (Swift).
  • Buat instans SDK.

Prasyarat

  • Daftarkan aplikasi web klien baru di pusat admin Microsoft Entra, dikonfigurasi untuk Akun di direktori organisasi dan akun Microsoft pribadi apa pun. Lihat Mendaftarkan aplikasi untuk detail selengkapnya. Rekam nilai berikut dari halaman Gambaran Umum aplikasi untuk digunakan nanti:
    • ID Aplikasi (klien)
    • ID Direktori (Penyewa)
  • Kode X.
  • Proyek iOS (Swift).

Tambahkan URL pengalihan platform

Untuk menentukan jenis aplikasi ke pendaftaran aplikasi Anda, ikuti langkah-langkah berikut:

  1. Di bawah Kelola, pilih Autentikasi >Tambahkan platform>iOS/macOS.
  2. Masukkan ID Bundel proyek Anda. Jika Anda mengunduh sampel kode tersebut, ID Bundel adalah com.microsoft.identitysample.MSALiOS. Jika Anda membuat proyek Anda sendiri, pilih proyek Anda di Xcode dan buka tab Umum. Pengidentifikasi bundel muncul di bagian Identitas.
  3. Pilih Konfigurasikan dan simpan Konfigurasi MSAL yang muncul di halaman konfigurasi MSAL sehingga Anda dapat memasukkannya saat mengonfigurasi aplikasi nanti.
  4. Pilih Selesai.

Mengaktifkan alur klien publik

Untuk mengidentifikasi aplikasi Anda sebagai klien publik, ikuti langkah-langkah berikut:

  1. Di bagian Kelola, pilih Autentikasi.

  2. Di bawah Pengaturan tingkat lanjut, untuk Izinkan alur klien publik, pilih Ya.

  3. Pilih Simpan untuk menyimpan perubahan Anda.

Menambahkan kerangka kerja MSAL ke aplikasi iOS (Swift)

SDK autentikasi MSAL digunakan untuk mengintegrasikan autentikasi ke dalam aplikasi Anda menggunakan OAuth2 standar dan OpenID Connect. Ini memungkinkan Anda untuk memasukkan pengguna atau aplikasi dengan identitas Microsoft. Untuk menambahkan MSAL ke proyek iOS (Swift), ikuti langkah-langkah berikut:

  1. Buka proyek iOS Anda di Xcode.
  2. Pilih Tambahkan Dependensi Paket... dari menu File.
  3. Masukkan https://github.com/AzureAD/microsoft-authentication-library-for-objc sebagai URL Paket dan pilih Tambahkan Paket

Memperbarui Pengidentifikasi Paket

Di ekosistem Apple, Pengidentifikasi Bundel adalah pengidentifikasi unik untuk aplikasi. Untuk memperbarui Pengidentifikasi Bundel di proyek Anda, ikuti langkah-langkah berikut:

  1. Buka pengaturan proyek. Di bagian Identitas , masukkan Pengidentifikasi Bundel .

  2. Klik kanan Info.plist dan pilih Buka Sebagai Kode Sumber>.

  3. Di bawah simpul akar dict, ganti Enter_the_bundle_Id_Here denganId Bundelyang Anda gunakan di portal. Perhatikan awalan msauth. dalam string.

    <key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>msauth.Enter_the_Bundle_Id_Here</string>
      </array>
   </dict>
</array>

Membuat instansi SDK

Untuk membuat instans MSAL di proyek Anda, ikuti langkah-langkah berikut:

  1. Impor pustaka MSAL ke pengontrol tampilan Anda dengan menambahkan import MSAL di bagian atas kelas ViewController Anda.

  2. Tambahkan variabel anggota applicationContext ke kelas ViewController Anda dengan menambahkan kode berikut tepat sebelum fungsi viewDidLoad():

    var applicationContext : MSALPublicClientApplication?
var webViewParameters : MSALWebviewParameters?

    Kode mendeklarasikan dua variabel: applicationContext, yang menyimpan instans MSALPublicClientApplication, dan webViewParameters, yang menyimpan instans MSALWebviewParameters. MSALPublicClientApplication adalah kelas yang disediakan oleh MSAL untuk menangani aplikasi klien publik. MSALWebviewParameters adalah kelas yang disediakan oleh MSAL yang menentukan parameter untuk mengonfigurasi tampilan web yang digunakan selama proses autentikasi.

  3. Tambahkan kode berikut ke fungsi tampilan viewDidLoad():

     do {
        try self.initMSAL()
    } catch let error {
        self.updateLogging(text: "Unable to create Application Context \(error)")
    }

    Kode mencoba menginisialisasi MSAL, menangani kesalahan apa pun yang terjadi selama proses. Jika terjadi kesalahan, sistem akan memperbarui catatan log dengan detail kesalahan.

  4. Tambahkan kode berikut yang membuat fungsi initMSAL(), yang menginisialisasi MSAL:

        func initMSAL() throws {

    guard let authorityURL = URL(string: Configuration.kAuthority) else {
        self.updateLogging(text: "Unable to create authority URL")
        return
    }

    let authority = try MSALCIAMAuthority(url: authorityURL)

    let msalConfiguration = MSALPublicClientApplicationConfig(clientId: Configuration.kClientID,
                                                              redirectUri: Configuration.kRedirectUri,
                                                              authority: authority)
    self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
}

    Kode ini menginisialisasi MSAL untuk iOS. Ini pertama-tama mencoba membuat URL untuk otoritas menggunakan string Configuration.kAuthority yang disediakan. Jika berhasil, ia membuat objek otoritas MSAL berdasarkan URL tersebut. Kemudian, konfigurasikan MSALPublicClientApplication dengan ID klien, URI pengalihan, dan otoritas yang diberikan. Jika semua konfigurasi disiapkan dengan benar, maka akan menginisialisasi konteks aplikasi dengan MSALPublicClientApplicationyang telah dikonfigurasi. Jika terjadi kesalahan selama proses, pesan kesalahan akan muncul.

  5. Buat file Configuration.swift dan tambahkan konfigurasi berikut:

    import Foundation

@objcMembers
class Configuration {
    static let kTenantSubdomain = "Enter_the_Tenant_Subdomain_Here"

    // Update the below to your client ID you received in the portal.
    static let kClientID = "Enter_the_Application_Id_Here"
    static let kRedirectUri = "Enter_the_Redirect_URI_Here"
    static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
    static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]

    static let kAuthority = "https://\(kTenantSubdomain).ciamlogin.com"

}

    Kode konfigurasi Swift ini mendefinisikan kelas bernama Configuration dan ditandai dengan @objcMembers. Ini termasuk konstanta statis untuk berbagai parameter konfigurasi yang terkait dengan penyiapan autentikasi. Parameter ini termasuk subdomain penyewa , ID klien , redirect URI , titik akhir API yang dilindungi , dan lingkup . Konstanta konfigurasi ini harus diperbarui dengan nilai yang sesuai khusus untuk penyiapan aplikasi.

    Temukan tanda tempat.

    • Enter_the_Application_Id_Here dan gantikan dengan ID Aplikasi (klien) dari aplikasi yang Anda daftarkan sebelumnya.
    • Enter_the_Redirect_URI_Here dan ganti dengan nilai kRedirectUri dalam file konfigurasi MSAL yang Anda unduh sebelumnya saat menambahkan URL pengalihan platform.
    • Enter_the_Protected_API_Scopes_Here dan ganti dengan ruang lingkup yang direkam sebelumnya. Jika Anda belum merekam cakupan apa pun, Anda dapat membiarkan daftar cakupan ini kosong.
    • Enter_the_Tenant_Subdomain_Here dan gantikan dengan subdomain Direktori (tenant). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak mengetahui subdomain penyewa Anda, belajarlah cara membaca detail penyewa Anda.

Menggunakan domain URL kustom (Opsional)

Gunakan domain kustom untuk sepenuhnya memberi merek URL autentikasi. Dari perspektif pengguna, pengguna tetap berada di domain Anda selama proses autentikasi, daripada dialihkan ke nama domain ciamlogin.com.

Gunakan langkah-langkah berikut untuk menggunakan domain kustom:

  1. Gunakan langkah-langkah dalam Mengaktifkan domain URL kustom untuk aplikasi di penyewa eksternal untuk mengaktifkan domain URL kustom untuk penyewa eksternal Anda.

  2. Buka file Configuration.swift:

    1. Perbarui nilai properti kAuthority ke https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Ganti Enter_the_Custom_Domain_Here dengan domain URL kustom Anda dan Enter_the_Tenant_ID_Here dengan ID penyewa Anda. Jika Anda tidak memiliki ID penyewa, pelajari lebih lanjut tentang bagaimana cara membaca detail penyewa Anda.

Setelah Anda membuat perubahan pada file Configuration.swift, jika domain URL kustom Anda login.contoso.com, dan ID penyewa Anda aaaabbbb-0000-cc-1111-dddd2222eeee, maka file Anda akan terlihat mirip dengan cuplikan berikut:

    import Foundation

    @objcMembers
    class Configuration {
        static let kTenantSubdomain = "login.contoso.com"
        
        // Update the below to your client ID you received in the portal.
        static let kClientID = "Enter_the_Application_Id_Here"
        static let kRedirectUri = "Enter_the_Redirect_URI_Here"
        static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
        static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]
        
        static let kAuthority = "https://\(kTenantSubdomain)/aaaabbbb-0000-cccc-1111-dddd2222eeee"
    
    }

Langkah berikutnya

Tutorial : Memasukkan pengguna di aplikasi seluler iOS (Swift)