Tutorial: Menambahkan masuk dan keluar di aplikasi iOS/macOS dengan menggunakan autentikasi asli

Berlaku untuk: Penyewa eksternal (pelajari selengkapnya)

Tutorial ini menunjukkan cara masuk dan keluar dari pengguna dengan kode sandi satu kali email atau nama pengguna dan kata sandi di aplikasi iOS/macOS Anda dengan menggunakan autentikasi asli.

Di tutorial ini, Anda akan:

• Masuk ke akun pengguna menggunakan kode sekali pakai untuk email atau nama pengguna (email) dan kata sandi.
• Keluarkan pengguna.
• Menangani kesalahan masuk

Prasyarat

• Tutorial: Siapkan aplikasi iOS/macOS Anda untuk autentikasi bawaan.
• Jika Anda ingin masuk menggunakan Email dengan kata sandi, konfigurasikan alur pengguna Anda untuk menggunakan Email dengan kata sandi saat Anda membuat alur pendaftaran dan masuk pengguna.

Masuk sebagai pengguna

Untuk mengautentikasi pengguna menggunakan alur kode sandi satu kali email, dapatkan alamat email dan kirim email yang berisi kode sandi satu kali agar pengguna dapat memastikan email mereka. Saat pengguna memasukkan kode sandi satu kali yang valid, aplikasi akan mendaftarkan mereka masuk.

Untuk masuk sebagai pengguna menggunakan alur email dengan kata sandi, catat email dan kata sandi. Jika nama pengguna dan kata sandi valid, aplikasi akan mengautentikasi pengguna.

Untuk masuk sebagai pengguna, Anda perlu:

1. Buat antarmuka pengguna (UI) untuk:

   • Kumpulkan email dari pengguna. Tambahkan validasi ke input Anda untuk memastikan pengguna memasukkan alamat email yang valid.
   • Kumpulkan kata sandi jika Anda masuk dengan nama pengguna (email) dan kata sandi.
   • Kumpulkan kode akses sekali pakai dari pengguna jika Anda masuk menggunakan email dengan kode akses sekali pakai.
   • Tambahkan tombol untuk memungkinkan pengguna mengirim ulang kode akses satu kali jika Anda masuk dengan kode akses satu kali email.

2. Di antarmuka pengguna Anda, tambahkan tombol, di mana acara pemilihannya memulai proses masuk seperti yang ditunjukkan dalam cuplikan kode berikut:

       @IBAction func signInPressed(_: Any) {
       guard let email = emailTextField.text else {
           resultTextView.text = "email not set"
           return
       }
   
       let parameters = MSALNativeAuthSignInParameters(username: email)
       nativeAuth.signIn(parameters: parameters, delegate: self)
   }
   

   Untuk masuk ke akun pengguna menggunakan proses Email kode akses satu kali, kami menggunakan cuplikan kode berikut:

   nativeAuth.signIn(parameters: parameters, delegate: self)
   

   Metode signIn(parameters:delegate), yang merespons secara asinkron dengan memanggil salah satu metode pada objek delegasi yang diteruskan, harus menerapkan protokol SignInStartDelegate. Kami mengirimkan instance MSALNativeAuthSignInParameters yang berisi alamat email yang disediakan oleh pengguna dalam formulir untuk pengiriman email kemudian meneruskan self sebagai delegasi.

   Untuk masuk ke pengguna menggunakan Email dengan aliran kata sandi, kami menggunakan cuplikan kode berikut:

   let parameters = MSALNativeAuthSignInParameters(username: email)
   parameters.password = password
   nativeAuth.signIn(parameters: parameters, delegate: self)
   

   Dalam metode signIn(parameters:delegate), Anda meneruskan instans MSALNativeAuthSignInParameters yang berisi alamat email yang disediakan pengguna kepada kami dan kata sandi mereka, bersama dengan objek delegasi yang sesuai dengan protokol SignInStartDelegate. Untuk contoh ini, kami mengirimkan self.

3. Untuk menerapkan protokol SignInStartDelegate saat Anda menggunakan alur kode sandi satu kali email , gunakan cuplikan kode berikut:

   extension ViewController: SignInStartDelegate {
       func onSignInStartError(error: MSAL.SignInStartError) {
           resultTextView.text = "Error signing in: \(error.errorDescription ?? "no description")"
       }
   
       func onSignInCodeRequired(
           newState: MSAL.SignInCodeRequiredState,
           sentTo: String,
           channelTargetType: MSAL.MSALNativeAuthChannelType,
           codeLength: Int
       ) {
           resultTextView.text = "Verification code sent to \(sentTo)"
       }
   }
   

   signIn(parameters:delegate) menghasilkan panggilan untuk mendelegasikan metode. Dalam skenario yang paling umum, onSignInCodeRequired(newState:sentTo:channelTargetType:codeLength) dipanggil untuk menunjukkan bahwa kode telah dikirim untuk memverifikasi alamat email pengguna. Seiring dengan beberapa detail di mana kode telah dikirim, dan berapa banyak digit yang dikandungnya, metode delegasi ini juga memiliki parameter newState jenis SignInCodeRequiredState, yang memberi kami akses ke dua metode baru berikut:

   • submitCode(code:delegate)
   • resendCode(delegate)

   Gunakan submitCode(code:delegate) untuk mengirimkan kode sandi satu kali yang disediakan pengguna dalam formulir kode sandi satu kali, gunakan cuplikan kode berikut:

   newState.submitCode(code: userSuppliedCode, delegate: self)
   

   submitCode(code:delegate) menerima kode akses satu kali dan mendelegasikan parameter. Setelah mengirimkan kode, Anda harus memverifikasi kode akses satu kali dengan menerapkan protokol SignInVerifyCodeDelegate.

   Untuk menerapkan protokol SignInVerifyCodeDelegate sebagai ekstensi ke kelas Anda, gunakan cuplikan kode berikut:

   extension ViewController: SignInVerifyCodeDelegate {
       func onSignInVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignInCodeRequiredState?) {
           resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
       }
   
       func onSignInCompleted(result: MSALNativeAuthUserAccountResult) {
           resultTextView.text = "Signed in successfully."
           let parameters = MSALNativeAuthGetAccessTokenParameters()
           result.getAccessToken(parameters: parameters, delegate: self)
       }
   }
   

   Dalam skenario yang paling umum, kami menerima panggilan ke onSignInCompleted(result) menunjukkan bahwa pengguna telah masuk. Hasilnya dapat digunakan untuk mengakses access token.

   getAccessToken(parameters:delegate) menerima instans MSALNativeAuthGetAccessTokenParameters dan parameter delegasi dan kita harus menerapkan metode yang diperlukan dalam protokol CredentialsDelegate.

   Dalam skenario yang paling umum, kami menerima panggilan ke onAccessTokenRetrieveCompleted(result) yang menunjukkan bahwa pengguna memperoleh access token.

   extension ViewController: CredentialsDelegate {
       func onAccessTokenRetrieveError(error: MSAL.RetrieveAccessTokenError) {
           resultTextView.text = "Error retrieving access token"
       }
   
       func onAccessTokenRetrieveCompleted(result: MSALNativeAuthTokenResult) {
           resultTextView.text = "Signed in. Access Token: \(result.accessToken)"
       }
   }
   
   

4. Untuk menerapkan protokol SignInStartDelegate saat Anda menggunakan Email dengan alur kata sandi, gunakan cuplikan kode berikut:

   extension ViewController: SignInStartDelegate {
       func onSignInStartError(error: MSAL.SignInStartError) {
           resultTextView.text = "Error signing in: \(error.errorDescription ?? "no description")"
       }
   
       func onSignInCompleted(result: MSAL.MSALNativeAuthUserAccountResult) {
           // User successfully signed in
       }
   }
   

   Dalam skenario yang paling umum, kami menerima panggilan ke onSignInCompleted(result) menunjukkan bahwa pengguna telah masuk. Hasilnya dapat digunakan untuk mengakses access token.

   getAccessToken(parameters:delegate) menerima instans MSALNativeAuthGetAccessTokenParameters dan parameter delegasi dan kita harus menerapkan metode yang diperlukan dalam protokol CredentialsDelegate.

   Dalam skenario yang paling umum, kami menerima panggilan ke onAccessTokenRetrieveCompleted(result) yang menunjukkan bahwa pengguna memperoleh access token.

   extension ViewController: CredentialsDelegate {
       func onAccessTokenRetrieveError(error: MSAL.RetrieveAccessTokenError) {
           resultTextView.text = "Error retrieving access token"
       }
   
       func onAccessTokenRetrieveCompleted(result: MSALNativeAuthTokenResult) {
           resultTextView.text = "Signed in. Access Token: \(result.accessToken)"
       }
   }
   
   

Menangani kesalahan login

Saat masuk, tidak semua tindakan berhasil. Misalnya, pengguna mungkin mencoba masuk dengan alamat email yang tidak ada, atau mengirimkan kode yang tidak valid.

1. Untuk menangani kesalahan dalam metode signIn(parameters:delegate), gunakan cuplikan kode berikut:

   func onSignInStartError(error: MSAL.SignInStartError) {
       if error.isUserNotFound || error.isInvalidUsername {
           resultTextView.text = "Invalid username"
       } else {
           resultTextView.text = "Error signing in: \(error.errorDescription ?? "no description")"
       }
   }
   

2. Untuk menangani kesalahan dalam metode submitCode(), gunakan cuplikan kode berikut:

   func onSignInVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignInCodeRequiredState?) {
       if error.isInvalidCode {
           // Inform the user that the submitted code was incorrect and ask for a new code to be supplied
           let userSuppliedCode = retrieveNewCode()
           newState?.submitCode(code: userSuppliedCode, delegate: self)
       } else {
           resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
       }
   }
   

   Jika pengguna memasukkan kode verifikasi email yang salah, penanganan kesalahan menyertakan referensi ke SignInCodeRequiredState yang dapat digunakan untuk mengirimkan kode yang diperbarui. Dalam implementasi protokol SignInVerifyCodeDelegate sebelumnya, kami hanya menampilkan kesalahan ketika kami menangani fungsi delegasi onSignInVerifyCodeError(error:newState).

Membaca klaim token ID

Setelah aplikasi memperoleh token ID, Anda dapat mengambil klaim yang terkait dengan akun saat ini. Untuk melakukannya, gunakan cuplikan kode berikut:

func onSignInCompleted(result: MSAL.MSALNativeAuthUserAccountResult) {
   let claims = result.account.accountClaims
   let preferredUsername = claims?["preferred_username"] as? String
}

Kunci yang Anda gunakan untuk mengakses nilai klaim adalah nama yang Anda tentukan saat menambahkan atribut pengguna sebagai klaim token.

Pelajari cara menambahkan atribut bawaan dan kustom sebagai klaim token di artikel Menambahkan atribut pengguna ke klaim token.

Keluar dari pengguna

Untuk mengeluarkan pengguna, gunakan referensi ke MSALNativeAuthUserAccountResult yang Anda terima dalam panggilan balik onSignInCompleted, atau gunakan getNativeAuthUserAccount() untuk mendapatkan akun masuk apa pun dari cache dan menyimpan referensi dalam variabel anggota accountResult.

1. Konfigurasikan grup rantai kunci untuk proyek Anda seperti yang dijelaskan di sini.

2. Tambahkan variabel anggota baru ke kelas ViewController Anda: var accountResult: MSALNativeAuthUserAccountResult?.

3. Perbarui viewDidLoad untuk mengambil akun yang di-cache dengan menambahkan baris ini setelah nativeAuth berhasil diinisialisasi: accountResult = nativeAuth.getNativeAuthUserAccount().

4. Perbarui handler signInCompleted untuk menyimpan hasil akun:

   func onSignInCompleted(result: MSALNativeAuthUserAccountResult) {
       resultTextView.text = "Signed in successfully"
   
       accountResult = result
   }
   

5. Tambahkan tombol Keluar dan gunakan kode berikut untuk mengeluarkan pengguna:

   @IBAction func signOutPressed(_: Any) {
       guard let accountResult = accountResult else {
           print("Not currently signed in")
           return
       }
   
       accountResult.signOut()
   
       self.accountResult = nil
   
       resultTextView.text = "Signed out"
   }
   

Anda telah berhasil menyelesaikan semua langkah yang diperlukan untuk mengeluarkan pengguna di aplikasi Anda. Buat dan jalankan aplikasi Anda. Jika semuanya berjalan lancar, Anda harus dapat memilih tombol keluar untuk berhasil log out.

Mengaktifkan masuk dengan alias atau nama pengguna

Anda dapat mengizinkan pengguna yang masuk dengan alamat email dan kata sandi untuk juga masuk dengan nama pengguna dan kata sandi. Nama pengguna juga disebut pengidentifikasi masuk alternatif, dapat berupa ID pelanggan, nomor akun, atau pengidentifikasi lain yang Anda pilih untuk digunakan sebagai nama pengguna.

Anda dapat menetapkan nama pengguna ke akun pengguna secara manual melalui pusat admin Microsoft Entra atau mengotomatiskannya di aplikasi Anda melalui Microsoft Graph API.

Gunakan langkah-langkah dalam artikel Masuk dengan alias atau nama pengguna untuk memungkinkan pengguna Anda masuk menggunakan nama pengguna di aplikasi Anda:

1. Aktifkan nama pengguna pada masuk.
2. Buat pengguna dengan nama pengguna di pusat admin atau perbarui pengguna yang sudah ada dengan menambahkan nama pengguna. Atau, Anda juga dapat mengotomatiskan pembuatan dan pembaruan pengguna di aplikasi Anda dengan menggunakan Microsoft Graph API.

Mengonfigurasi penyedia klaim kustom

Jika Anda ingin menambahkan klaim dari sistem eksternal ke dalam token yang dikeluarkan untuk aplikasi Anda, gunakan penyedia klaim kustom . Penyedia klaim kustom terdiri dari ekstensi autentikasi kustom yang memanggil REST API eksternal untuk mengambil klaim dari sistem eksternal.

Ikuti langkah-langkah dalam Mengonfigurasi penyedia klaim kustom untuk menambahkan klaim dari sistem eksternal ke dalam token keamanan Anda.

Konten terkait

• Mengonfigurasi penyedia klaim kustom.