Mulai cepat: Memasukkan pengguna dan memanggil Microsoft Graph dari aplikasi iOS atau macOS

Artikel
10/24/2023

Di mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan bagaimana aplikasi iOS atau macOS asli dapat masuk pengguna dan mendapatkan token akses untuk memanggil Microsoft Graph API.

Mulai cepat berlaku untuk app iOS dan macOS. Beberapa langkah hanya diperlukan untuk aplikasi iOS dan akan ditunjukkan seperti itu.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
XCode 10+
iOS 10+
macOS 10.12+

Cara kerja sampel

Diagram memperlihatkan cara kerja aplikasi sampel yang dihasilkan oleh mulai cepat ini.

Mendaftarkan aplikasi mulai cepat Anda

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Untuk mendaftarkan aplikasi Anda dan menambahkan informasi pendaftaran aplikasi ke solusi Anda secara manual, ikuti langkah-langkah ini:

Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.
Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa tempat Anda ingin mendaftarkan aplikasi dari menu Direktori + langganan.
Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
Pilih Pendaftaran baru.
Masukkan Nama untuk aplikasi Anda. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
Pilih Daftarkan.
Di bawah Kelola, pilih Autentikasi >Tambahkan Platform>iOS.
Masukkan Pengidentifikasi Bundel untuk aplikasi Anda. Pengidentifikasi bundel adalah string unik yang secara unik mengidentifikasi aplikasi Anda, misalnya com.<yourname>.identitysample.MSALMacOS. Catat nilai yang Anda gunakan. Perhatikan konfigurasi iOS juga berlaku untuk aplikasi macOS.
Pilih Konfigurasi dan simpan detail Konfigurasi MSAL untuk mulai cepat nanti.
Pilih Selesai.

Langkah 2: Unduh contoh proyek

Langkah 3: Instal dependensi

Ekstrak file zip.
Di jendela terminal, navigasi ke folder dengan sampel kode yang diunduh dan jalankan pod install untuk menginstal pustaka MSAL terbaru.

Langkah 4: Konfigurasi proyek Anda

Jika Anda memilih Opsi 1 di atas, Anda dapat melewati langkah-langkah ini.

Buka proyek di XCode.
Edit ViewController.swift dan ganti baris yang dimulai dengan 'let kClientID' dengan cuplikan kode berikut. Ingatlah untuk memperbarui nilai dengan kClientID clientID yang Anda simpan saat mendaftarkan aplikasi sebelumnya dalam mulai cepat ini:
```
let kClientID = "Enter_the_Application_Id_Here"
```
Jika Anda membangun aplikasi untuk cloud nasional Microsoft Entra, ganti baris yang dimulai dengan 'let kGraphEndpoint' dan 'let kAuthority' dengan titik akhir yang benar. Untuk akses global, gunakan nilai default:
```
let kGraphEndpoint = "https://graph.microsoft.com/"
let kAuthority = "https://login.microsoftonline.com/common"
```
Titik akhir lainnya didokumentasikan di sini. Misalnya, untuk menjalankan mulai cepat dengan Microsoft Entra Jerman, gunakan hal berikut:
```
let kGraphEndpoint = "https://graph.microsoft.de/"
let kAuthority = "https://login.microsoftonline.de/common"
```
Buka pengaturan proyek. Di bagian Identitas , masukkan Pengidentifikasi Bundel.
Klik kanan Info.plist dan pilih Buka Sebagai>Kode Sumber.

Di bawah dict root node, ganti Enter_the_bundle_Id_Here dengan Id Bundel yang Anda gunakan di portal. Perhatikan prefiks msauth. pada string.

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

Membuat dan menjalankan aplikasi!

Informasi Selengkapnya

Baca bagian ini untuk mempelajari lebih lanjut tentang mulai cepat ini.

Mendapatkan MSAL

MSAL (MSAL.framework) adalah pustaka yang digunakan untuk masuk pengguna dan meminta token yang digunakan untuk mengakses API yang dilindungi oleh platform identitas Microsoft. Anda dapat menambahkan MSAL ke aplikasi Anda menggunakan proses berikut:

$ vi Podfile

Tambahkan yang berikut ke podfile ini (dengan target proyek Anda):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Jalankan perintah instalasi CocoaPods:

pod install

Menginisialisasi MSAL

Anda bisa menambahkan referensi untuk MSAL dengan menambahkan kode berikut:

import MSAL

Lalu, inisialisasi MSAL menggunakan kode berikut:

let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

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

Mana:	Deskripsi
`clientId`	ID Aplikasi dari aplikasi yang terdaftar di portal.azure.com
`authority`	Platform identitas Microsoft. Di kebanyakan kasus, hal ini akan `https://login.microsoftonline.com/common`
`redirectUri`	URI pengalihan aplikasi. Anda dapat meneruskan 'nihil' untuk menggunakan nilai default, atau URI pengalihan kustom Anda.

Hanya untuk iOS, persyaratan aplikasi tambahan

Aplikasi Anda juga harus memiliki hal berikut di aplikasi AndaAppDelegate. Yang memungkinkan MSAL SDK menangani respons token dari aplikasi broker Auth ketika Anda melakukan autentikasi.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Catatan

Di iOS 13+, jika Anda mengadopsi UISceneDelegate alih-alih UIApplicationDelegate, meletakkan kode ini scene:openURLContexts: ke dalam callback sebagai gantinya (Lihat dokumentasi Apple). Jika Anda mendukung UISceneDelegate dan UIApplicationDelegate untuk kompatibilitas dengan iOS yang lebih lama, callback MSAL perlu ditempatkan ke kedua tempat.

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

   guard let urlContext = URLContexts.first else {
      return
   }

   let url = urlContext.url
   let sourceApp = urlContext.options.sourceApplication

   MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
}

Akhirnya, aplikasi Anda harus memiliki LSApplicationQueriesSchemes entri di Info.plist Anda bersama CFBundleURLTypes. Sampel datang dengan disertai entri.

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

MSAL memiliki dua metode yang digunakan untuk memperoleh token: acquireToken dan acquireTokenSilent.

acquireToken: Mendapatkan token secara interaktif

Beberapa situasi mengharuskan pengguna untuk berinteraksi dengan platform identitas Microsoft. Dalam kasus ini, pengguna akhir mungkin diharuskan untuk memilih akun mereka, memasukkan kredensial mereka, atau menyetujui izin aplikasi Anda. Contohnya,

Pertama kali pengguna masuk ke aplikasi
Jika pengguna mengatur ulang kata sandi, mereka harus memasukkan kredensial mereka
Ketika aplikasi Anda meminta akses ke sumber daya untuk pertama kalinya
Ketika MFA atau kebijakan Akses Bersyarat lainnya diperlukan

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}

Mana:	Deskripsi
`scopes`	Berisi cakupan yang diminta (yaitu, `[ "user.read" ]` untuk Microsoft Graph atau `[ "<Application ID URL>/scope" ]` untuk API web kustom (`api://<Application ID>/access_as_user`))

acquireTokenSilent: Mendapatkan token akses secara diam-diam

Aplikasi seharusnya tidak mengharuskan pengguna mereka untuk masuk setiap kali mereka meminta token. Jika pengguna sudah masuk, metode ini memungkinkan aplikasi untuk meminta token secara diam-diam.

self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

   guard let account = currentAccount else {
      return
   }

   let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
   self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}

Mana:	Deskripsi
`scopes`	Berisi cakupan yang diminta (yaitu, `[ "user.read" ]` untuk Microsoft Graph atau `[ "<Application ID URL>/scope" ]` untuk API web kustom (`api://<Application ID>/access_as_user`))
`account`	Akun yang diminta oleh token. Mulai cepat ini diperuntukkan untuk satu aplikasi akun. Jika ingin membuat aplikasi multi-akun, Anda harus menentukan logika untuk mengidentifikasi akun mana yang digunakan untuk permintaan token menggunakan `accountsFromDeviceForParameters:completionBlock:` dan meneruskan dengan benar `accountIdentifier`

Bantuan dan dukungan

Jika Anda memerlukan bantuan, ingin melaporkan masalah, atau ingin mempelajari opsi dukungan, lihat Bantuan dan dukungan bagi pengembang.

Langkah berikutnya

Beralih ke tutorial langkah demi langkah di mana Anda membangun aplikasi iOS atau macOS yang mendapatkan token akses dari platform identitas Microsoft dan menggunakannya untuk memanggil Microsoft Graph API.

Tutorial: Masuk pengguna dan memanggil Microsoft Graph dari aplikasi iOS atau macOS