Panduan Mulai Cepat: Memasukkan pengguna dan memanggil Microsoft Graph di aplikasi desktop Windows - Microsoft identity platform

Artikel
10/24/2023

Dalam mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan cara aplikasi Windows Presentation Foundation (WPF) dapat memasukkan pengguna dan mendapatkan token akses untuk memanggil API Microsoft Graph. Aplikasi desktop yang Anda buat menggunakan alur kode otorisasi yang dipasangkan dengan standar Proof Key for Code Exchange (PKCE).

Lihat Cara kerja sampel untuk melihat ilustrasi.

Prasyarat

Visual Studio dengan beban kerja pengembangan Universal Windows Platform terinstal

Mendaftar dan mengunduh aplikasi mulai cepat Anda

Anda memiliki dua opsi untuk memulai aplikasi mulai cepat Anda:

[Ekspres] Opsi 1: Mendaftar dan mengonfigurasi aplikasi Anda secara otomatis lalu mengunduh sampel kode Anda
[Manual] Opsi 2: Mendaftarkan dan mengonfigurasi sampel aplikasi dan kode secara manual

Opsi 1: Mendaftarkan dan mengonfigurasi aplikasi secara otomatis lalu mengunduh sampel kode

Buka pusat admin Microsoft Entra - Pendaftaran aplikasi pengalaman mulai cepat.
Masukkan nama untuk aplikasi dan pilih Daftar.
Ikuti petunjuk untuk mengunduh dan mengonfigurasi aplikasi baru secara otomatis hanya dengan satu klik.

Opsi 2: Mendaftarkan dan mengonfigurasi sampel aplikasi dan kode secara manual

Langkah 1: Daftarkan aplikasi 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.
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 ke Aplikasi> Identitas>Pendaftaran aplikasi, pilih Pendaftaran baru.
Masukkan Nama untuk aplikasi Anda, contohnya Win-App-calling-MsGraph. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
Di bagian Tipe akun yang didukung, pilih Akun di direktori organisasi dan akun Microsoft pribadi apa pun (misalnya, Skype, Xbox, Outlook.com).
Pilih Daftar untuk membuat aplikasi.
Di bagian Kelola, pilih Autentikasi.
Pilih Tambahkan platform>Aplikasi seluler dan desktop.
Di bagian URI Pengalihan, pilih https://login.microsoftonline.com/common/oauth2/nativeclient dan di URI pengalihan kustom tambahkan ms-appx-web://microsoft.aad.brokerplugin/{client_id} di mana {client_id} adalah ID aplikasi (klien) dari aplikasi Anda (GUID yang sama yang muncul di kotak centang msal{client_id}://auth).
Pilih Konfigurasikan.

Langkah 2: Unduh proyek

Unduh aplikasi contoh WPF

Tip

Untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows, kami sarankan mengekstrak arsip atau mengkloning repositori ke direktori di dekat akar drive Anda.

Langkah 3: Konfigurasikan proyek

Ekstrak file zip ke folder lokal yang dekat dengan akar disk, misalnya, C:\Azure-Samples.
Buka proyek di Visual Studio.

Edit App.Xaml.cs dan ganti nilai bidang ClientId dan Tenant dengan kode berikut:

private static string ClientId = "Enter_the_Application_Id_here";
private static string Tenant = "Enter_the_Tenant_Info_Here";

Mana:

Enter_the_Application_Id_here - adalah ID aplikasi (klien) untuk aplikasi yang Anda daftarkan.

Untuk menemukan nilai ID Aplikasi (klien), buka halaman Gambaran Umum aplikasi di pusat admin Microsoft Entra.
Enter_the_Tenant_Info_Here - diatur ke salah satu opsi berikut:
- Jika aplikasi mendukung Akun dalam direktori organisasi ini, ganti nilai ini dengan ID penyewa atau Nama penyewa (misalnya, contoso.microsoft.com)
- Jika aplikasi Anda mendukung Akun di direktori organisasi apa pun, ganti nilai ini dengan organizations
- Jika aplikasi mendukung Akun di direktori organisasi dan akun Microsoft pribadi apa pun, ganti nilai ini dengan common.
  
  Untuk menemukan nilai ID Direktori (penyewa) dan Jenis akun yang didukung, buka halaman Gambaran Umum aplikasi di pusat admin Microsoft Entra.

Langkah 4: Jalankan aplikasi

Untuk membangun dan menjalankan aplikasi sampel di Visual Studio, pilih Menu Debug>Mulai Proses Debug, atau tekan tombol F5. MainWindow aplikasi Anda ditampilkan.

Saat jendela utama aplikasi muncul, pilih tombol Panggil Microsoft Graph API. Anda akan diminta untuk masuk menggunakan kredensial akun Microsoft Entra (akun kerja atau sekolah) atau akun Microsoft (live.com, outlook.com).

Jika menjalankan aplikasi untuk pertama kalinya, Anda akan diminta untuk memberikan persetujuan untuk mengizinkan aplikasi mengakses profil pengguna Anda dan memasukkan Anda. Setelah menyetujui izin yang diminta, aplikasi menampilkan bahwa Anda telah berhasil masuk. Anda akan melihat beberapa informasi token dasar dan data pengguna yang diperoleh dari panggilan ke Microsoft Graph API.

Informasi selengkapnya

Cara kerja sampel

Diagram showing how the sample app generated by this quickstart works.

MSAL.NET

MSAL (Microsoft.Identity.Client) adalah pustaka yang digunakan untuk memasukkan pengguna dan meminta token yang digunakan untuk mengakses API yang dilindungi oleh platform identitas Microsoft. Anda dapat menginstal MSAL dengan menjalankan perintah berikut di Konsol Package ManagerVisual Studio:

Install-Package Microsoft.Identity.Client -IncludePrerelease

Inisialisasi MSAL

Anda bisa menambahkan referensi untuk MSAL dengan menambahkan kode berikut:

using Microsoft.Identity.Client;

Lalu, inisialisasi MSAL menggunakan kode berikut:

IPublicClientApplication publicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();

Mana:	Deskripsi
`ClientId`	Adalah ID Aplikasi (klien) untuk aplikasi yang terdaftar di pusat admin Microsoft Entra. Anda dapat menemukan nilai ini di halaman Gambaran Umum aplikasi di pusat admin Microsoft Entra.

Meminta token

MSAL memiliki dua metode untuk memperoleh token: AcquireTokenInteractive dan AcquireTokenSilent.

Mendapatkan token pengguna secara interaktif

Beberapa situasi mengharuskan pengguna berinteraksi dengan platform identitas Microsoft melalui jendela pop-up untuk memvalidasi info masuk mereka atau memberikan persetujuan. Beberapa contoh termasuk:

Pertama kali pengguna masuk ke aplikasi
Ketika pengguna perlu memasukkan kembali kredensial mereka karena kata sandi kedaluwarsa
Ketika aplikasi Anda meminta akses ke sumber daya tambahan yang perlu disetujui pengguna
Ketika Autentikasi dua faktor diperlukan

authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();

Mana:	Deskripsi
`_scopes`	Berisi cakupan yang diminta, seperti `{ "user.read" }` untuk Microsoft Graph atau `{ "api://<Application ID>/access_as_user" }` untuk API web kustom.

Mendapatkan token pengguna secara diam-diam

Anda tidak ingin meminta pengguna memvalidasi kredensial mereka setiap kali mereka perlu mengakses sumber daya. Sebagian besar waktu Anda menginginkan akuisisi dan pembaruan token tanpa interaksi pengguna apa pun. Anda dapat menggunakan metode AcquireTokenSilent ini untuk mendapatkan token untuk mengakses sumber daya yang dilindungi setelah metode AcquireTokenInteractive awal:

var accounts = await app.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();

Mana:	Deskripsi
`scopes`	Berisi cakupan yang diminta, seperti `{ "user.read" }` untuk Microsoft Graph atau `{ "api://<Application ID>/access_as_user" }` untuk API web kustom.
`firstAccount`	Menentukan pengguna pertama dalam cache (MSAL mendukung beberapa pengguna dalam satu aplikasi).

Bantuan dan dukungan

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

Langkah berikutnya

Cobalah tutorial desktop Windows untuk mengetahui panduan langkah demi langkah lengkap tentang membangun aplikasi dan fitur baru, termasuk penjelasan lengkap tentang mulai cepat ini.

Tutorial Memanggil Graph API

Share via