Mulai Cepat: Memperoleh token dan memanggil Microsoft Graph API dari aplikasi desktop

  • Artikel
  • 12 menit untuk membaca

Dalam mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan bagaimana aplikasi Universal Windows Platform (UWP) dapat masuk pengguna dan mendapatkan token akses untuk memanggil Microsoft Graph API.

Lihat Cara kerja sampel untuk melihat ilustrasi.

Prasyarat

Mendaftar dan mengunduh aplikasi mulai cepat Anda

Anda memiliki dua opsi untuk memulai aplikasi mulai cepat Anda:

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

  1. Buka pengalaman mulai cepat portal Microsoft Azure - Pendaftaran aplikasi.
  2. Masukkan nama untuk aplikasi dan pilih Daftar.
  3. Ikuti petunjuk untuk mengunduh dan mengonfigurasi aplikasi baru secara otomatis untuk Anda dalam satu klik.

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

Langkah 1: Daftarkan aplikasi

Untuk mendaftarkan aplikasi Anda dan menambahkan informasi pendaftaran aplikasi ke solusi Anda, ikuti langkah-langkah berikut:

  1. Masuk ke portal Microsoft Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih penyewa aplikasinya ingin Anda daftarkan.
  3. Cari dan pilih Microsoft Azure Active Directory.
  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.
  5. Masukkan Nama untuk aplikasi Anda, misalnya UWP-App-calling-MsGraph. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
  6. Di bagian Tipe akun yang didukung, pilih Akun di direktori organisasi dan akun Microsoft pribadi apa pun (misalnya, Skype, Xbox, Outlook.com) .
  7. Pilih Daftar untuk membuat aplikasi, lalu catat ID Aplikasi (klien) untuk digunakan di langkah selanjutnya.
  8. Di bagian Kelola, pilih Autentikasi.
  9. Pilih Tambahkan platform>Aplikasi seluler dan desktop.
  10. Di bawah URI Pengalihan, pilih https://login.microsoftonline.com/common/oauth2/nativeclient.
  11. Pilih Konfigurasikan.

Langkah 2: Unduh proyek

Unduh aplikasi contoh UWP

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

  1. Ekstrak .zip arsip ke folder lokal yang dekat dengan akar drive Anda. Misalnya, ke dalam C:\Azure-Samples.

  2. Buka proyek di Visual Studio. Instal beban kerjapengembangan Universal Windows Platform dan komponen SDK individu apa pun jika diminta.

  3. Di MainPage.Xaml.cs, ubah nilai ClientId variabel ke ID Aplikasi (Klien) dari aplikasi yang Anda daftarkan sebelumnya.

    private const string ClientId = "Enter_the_Application_Id_here";

    Anda dapat menemukan ID Aplikasi (klien) di panel Gambaran Umum aplikasi di portal Microsoft Azure (pendaftaran Aplikasi>Azure Active Directory>{Pendaftaran aplikasi Anda} ).

  4. Buat lalu pilih sertifikat uji yang ditandatangani sendiri baru untuk paket:

    1. Di Penjelajah Solusi, klik ganda file Package.appxmanifest.
    2. Pilih Kemasan>Pilih Sertifikat...>Buat... .
    3. Masukkan kata sandi lalu pilih OKE. Sebuah sertifikat bernama Native_UWP_V2_TemporaryKey.pfx dibuat.
    4. Pilih OK untuk menutup dialog Pilih sertifikat, lalu verifikasi bahwa Anda melihat Native_UWP_V2_TemporaryKey.pfx di Penjelajah Solusi.
    5. Di Penjelajah Solusi, klik kanan proyek Native_UWP_V2 dan pilih Properti.
    6. Pilih Masuk, lalu pilih .pfx yang Anda buat di daftar turun bawah Pilih file kunci nama yang kuat.

Langkah 4: Jalankan aplikasi

Untuk menjalankan aplikasi sampel pada mesin lokal Anda:

  1. Di toolbar Visual Studio, pilih platform yang tepat (mungkin x64 atau x86, bukan ARM). Perangkat target harus berubah dari Perangkat ke Mesin Lokal.

  2. Pilih Debug>Mulai Tanpa Debugging.

    Jika diminta untuk melakukannya, Anda mungkin harus mengaktifkan terlebih Mode Developer terlebih dahulu, lalu Mulai Tanpa Debugging lagi untuk meluncurkan aplikasi.

Saat jendela aplikasi muncul, Anda dapat memilih tombol Panggil Microsoft Graph API, masukkan kredensial Anda, dan setujui izin yang diminta oleh aplikasi. Jika berhasil, aplikasi menampilkan beberapa informasi token dan data yang diperoleh dari panggilan ke Microsoft Graph API.

Cara kerja sampel

Shows how the sample app generated by this quickstart works

MSAL.NET

MSAL (Microsoft.Identity.Client) adalah pustaka yang digunakan untuk masuk pengguna dan meminta token keamanan. Token keamanan 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

Inisialisasi MSAL

Anda bisa menambahkan referensi untuk MSAL dengan menambahkan kode berikut:

using Microsoft.Identity.Client;

Kemudian, MSAL diinisialisasi menggunakan kode berikut:

public static IPublicClientApplication PublicClientApp;
PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                                                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                                                    .Build();

Nilainya ClientId adalah ID Aplikasi (klien) aplikasi yang Anda daftarkan di portal Microsoft Azure. Anda dapat menemukan nilai ini di halaman Gambaran Umum aplikasi di portal Microsoft Azure.

Meminta token

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

Mendapatkan token pengguna secara interaktif

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

  • Pengguna pertama kali masuk ke aplikasi
  • Ketika pengguna mungkin perlu memasukkan kembali kredensial mereka karena kata sandi telah kedaluwarsa
  • Ketika aplikasi Anda meminta akses ke sumber daya, bahwa pengguna perlu menyetujui
  • Ketika diperlukan otentikasi dua faktor
authResult = await PublicClientApp.AcquireTokenInteractive(scopes)
                      .ExecuteAsync();

scopesParameter berisi cakupan yang diminta, seperti untuk { "user.read" }Microsoft Graph atau untuk { "api://<Application ID>/access_as_user" } API web kustom.

Mendapatkan token pengguna secara diam-diam

Gunakan AcquireTokenSilentmetode untuk mendapatkan token untuk mengakses sumber daya yang dilindungi setelah metode AcquireTokenInteractive awal. Anda tidak ingin mengharuskan pengguna untuk memvalidasi kredensial mereka setiap kali mereka perlu mengakses sumber daya. Sebagian besar waktu Anda ingin melakukan akuisisi dan pembaruan token tanpa interaksi pengguna

var accounts = await PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
  • scopes berisi cakupan yang diminta, seperti untuk { "user.read" } Microsoft Graph atau { "api://<Application ID>/access_as_user" } untuk API web kustom.
  • firstAccount menentukan akun 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 panduan langkah demi langkah lengkap tentang membangun aplikasi dan fitur baru, termasuk penjelasan lengkap dari mulai cepat ini.

UWP - Tutorial Memanggil Graph API

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.

Lihat Cara kerja sampel untuk melihat ilustrasi.

Prasyarat

Mendaftarkan dan mengunduh aplikasi mulai cepat

Anda memiliki dua opsi untuk memulai aplikasi mulai cepat Anda:

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

  1. Buka pengalaman mulai cepat portal Microsoft Azure - Pendaftaran aplikasi.
  2. Masukkan nama aplikasi dan pilih Daftar.
  3. Ikuti petunjuk untuk mengunduh dan mengonfigurasi aplikasi baru secara otomatis hanya dengan satu klik.

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

Langkah 1: Daftarkan aplikasi

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

  1. Masuk ke portal Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih penyewa aplikasinya ingin Anda daftarkan.
  3. Cari dan pilih Microsoft Azure Active Directory.
  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.
  5. Masukkan Nama untuk aplikasi Anda, misalnya Win-App-calling-MsGraph. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
  6. Di bagian Jenis akun yang didukung, pilih Akun di direktori organisasi dan akun Microsoft pribadi apa pun (misalnya, Skype, Xbox, Outlook.com) .
  7. Pilih Daftar untuk membuat aplikasi.
  8. Di bagian Kelola, pilih Autentikasi.
  9. Pilih Tambahkan platform>Aplikasi desktop ponsel dan desktop.
  10. 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).
  11. 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

  1. Ekstrak file zip ke folder lokal yang dekat dengan akar disk, misalnya, C:\Azure-Samples.

  2. Buka proyek di Visual Studio.

  3. 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";

Di 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 portal Microsoft Azure.

  • 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 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 di portal Microsoft Azure.

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 info masuk akun Azure Active Directory (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

Shows 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.NET dengan menjalankan perintah berikut di Package Manager Console Visual 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();
Di mana: Deskripsi
ClientId ID Aplikasi (klien) untuk aplikasi yang terdaftar di portal Microsoft Azure. Anda dapat menemukan nilai ini di halaman Gambaran Umum aplikasi di portal Microsoft Azure.

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 meliputi:

  • 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();
Di 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();
Di 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

Di mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan bagaimana aplikasi desktop Electron dapat memasukkan pengguna dan memperoleh token akses untuk memanggil Microsoft Graph API.

Mulai cepat ini menggunakan Microsoft Authentication Library for Node.js (MSAL Node) dengan alur kode otorisasi dengan PKCE.

Prasyarat

Mendaftar dan mengunduh aplikasi sampel

Ikuti langkah-langkah di bawah ini untuk memulai.

Langkah 1: Daftarkan aplikasi

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

  1. Masuk ke portal Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih penyewa aplikasinya ingin Anda daftarkan.
  3. Cari dan pilih Microsoft Azure Active Directory.
  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.
  5. Masukkan Nama untuk aplikasi Anda, misalnya msal-node-desktop. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
  6. Pilih Daftar untuk membuat aplikasi.
  7. Di bagian Kelola, pilih Autentikasi.
  8. Pilih Tambahkan platform>Aplikasi desktop ponsel dan desktop.
  9. Di bagian URI Pengalihan, masukkan URI pengalihan yang disarankan oleh portal pendaftaran aplikasi, misalnya msalfa29b4c9-7675-4b61-8a0a-bf7b2b4fda91://auth.
  10. Pilih Konfigurasikan.

Langkah 2: Unduh proyek sampel Electron

Unduh sampel kode

Langkah 3: Konfigurasikan proyek sampel Electron

*Ekstrak proyek, buka folder ms-identity-JavaScript-nodejs-desktop-main, kemudian buka file .authConfig.js. Ganti nilai sebagai berikut:

Variabel Deskripsi Misalnya
Enter_the_Cloud_Instance_Id_Here Instans cloud Azure tempat aplikasi Anda terdaftar https://login.microsoftonline.com/ (termasuk garis miring berikutnya)
Enter_the_Tenant_Id_Here ID Penyewa atau Domain primer contoso.microsoft.com atau cbe899ec-5f5c-4efe-b7a0-599505d3d54f
Enter_the_Application_Id_Here ID Klien dari aplikasi yang Anda daftarkan fa29b4c9-7675-4b61-8a0a-bf7b2b4fda91
Enter_the_Redirect_Uri_Here Uri pengalihan dari aplikasi yang Anda daftarkan msalfa29b4c9-7675-4b61-8a0a-bf7b2b4fda91://auth
Enter_the_Graph_Endpoint_Here Instans cloud Microsoft Graph API yang akan dipanggil oleh aplikasi Anda https://graph.microsoft.com/ (termasuk garis miring berikutnya)

File Anda akan terlihat seperti di bawah ini:

const AAD_ENDPOINT_HOST = "https://login.microsoftonline.com/"; // include the trailing slash
const REDIRECT_URI = "msalfa29b4c9-7675-4b61-8a0a-bf7b2b4fda91://auth";
const msalConfig = {
    auth: {
        clientId: "fa29b4c9-7675-4b61-8a0a-bf7b2b4fda91",
        authority: `${AAD_ENDPOINT_HOST}/cbe899ec-5f5c-4efe-b7a0-599505d3d54f`,
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                 console.log(message);
             },
             piiLoggingEnabled: false,
             logLevel: LogLevel.Verbose,
        }
    }
}

const GRAPH_ENDPOINT_HOST = "https://graph.microsoft.com/"; // include the trailing slash
const protectedResources = {
     graphMe: {
         endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me`,
         scopes: ["User.Read"],
     },
     graphMessages: {
         endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me/messages`,
         scopes: ["Mail.Read"],
     }
};

module.exports = {
     msalConfig: msalConfig,
     protectedResources: protectedResources,
 };

Langkah 4: Jalankan aplikasi

  1. Anda harus menginstal dependensi sampel ini sekali:

    cd ms-identity-javascript-nodejs-desktop-main
npm install

  2. Kemudian, jalankan aplikasi melalui prompt perintah atau konsol:

    npm start

  3. Pilih Masuk untuk memulai proses masuk.

    Saat pertama kali masuk, Anda akan diminta untuk memberikan persetujuan untuk mengizinkan aplikasi memasukkan Anda dan mengakses profil Anda. Setelah berhasil masuk, Anda akan dialihkan kembali ke aplikasi.

Informasi selengkapnya

Cara kerja sampel

Saat pengguna memilih tombol Masuk untuk pertama kalinya, dapatkan metode getTokenInteractiveAuthProvider.js dipanggil. Metode ini mengalihkan pengguna untuk masuk dengan titik akhir platform identitas Microsoft dan memvalidasi info masuk pengguna, lalu mendapatkan kode otorisasi. Kode ini kemudian ditukar dengan token akses menggunakan metode acquireTokenByCode MSAL Node.

MSAL Node

MSAL Node adalah pustaka yang digunakan untuk masuk ke pengguna dan meminta token yang digunakan untuk mengakses API yang dilindungi oleh platform identitas Microsoft. Untuk informasi selengkapnya tentang cara menggunakan MSAL Node dengan aplikasi desktop, lihat artikel ini.

Anda dapat menginstal MSAL Node dengan menjalankan perintah npm berikut.

npm install @azure/msal-node --save

Langkah berikutnya

Untuk mempelajari selengkapnya tentang pengembangan aplikasi desktop Electron dengan MSAL Node, lihat tutorial:

Tutorial: Memasukkan pengguna dan memanggil Microsoft Graph API di aplikasi desktop Electron