Mulai cepat: Memperoleh token dan memanggil Microsoft Graph dari aplikasi konsol Node.js

  • Artikel

Dalam mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan bagaimana aplikasi konsol Node.js bisa mendapatkan token akses menggunakan identitas aplikasi untuk memanggil Microsoft Graph API dan menampilkan daftar pengguna di direktori. Sampel kode juga menunjukkan bagaimana pekerjaan tanpa pengawasan atau layanan Windows dapat berjalan dengan identitas aplikasi, bukan identitas pengguna.

Mulai cepat ini menggunakan Microsoft Authentication Library for Node.js (MSAL Node) dengan pemberian kredensial klien.

Prasyarat

Mendaftar dan mengunduh aplikasi sampel

Ikuti langkah-langkah di bawah ini untuk memulai.

Langkah 1: Daftarkan aplikasi

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:

  1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi.
  2. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
  3. Pilih Pendaftaran baru.
  4. Masukkan Nama untuk aplikasi Anda, contohnya msal-node-cli. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
  5. Pilih Daftarkan.
  6. Di bagian Kelola, pilih Sertifikat & rahasia.
  7. Di bagian Rahasia klien, pilih Rahasia klien baru, masukkan nama, lalu pilih Tambahkan. Catat nilai rahasia di lokasi aman untuk digunakan di langkah selanjutnya.
  8. Di bawah Kelola, pilih Izin API>Tambahkan izin. Pilih Microsoft Graph.
  9. Pilih Izin aplikasi.
  10. Di bagian simpul Pengguna, pilih User.Read.All, lalu pilih Tambahkan izin.

Langkah 2: Unduh proyek contoh Node.js

Unduh sampel kode

Langkah 3: Konfigurasikan proyek contoh Node.js

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

  2. Edit .env dan ganti nilai bidang TENANT_ID, CLIENT_ID, dan CLIENT_SECRET dengan cuplikan berikut:

    "TENANT_ID": "Enter_the_Tenant_Id_Here",
"CLIENT_ID": "Enter_the_Application_Id_Here",
"CLIENT_SECRET": "Enter_the_Client_Secret_Here"

    Mana:

    • Enter_the_Application_Id_Here - adalah ID Aplikasi (klien) dari aplikasi yang Anda daftarkan sebelumnya. Temukan ID ini di Gambaran Umum pendaftaran aplikasi.
    • Enter_the_Tenant_Id_Here - ganti nilai ini dengan ID Penyewa atau Nama penyewa (misalnya, contoso.microsoft.com). Temukan nilai-nilai ini pada Gambaran Umum pendaftaran aplikasi.
    • Enter_the_Client_Secret_Here - ganti nilai ini dengan rahasia klien yang Anda buat sebelumnya. Untuk menghasilkan kunci baru, gunakan Sertifikat & rahasia di pengaturan pendaftaran aplikasi.

    Menggunakan rahasia teks biasa dalam kode sumber menyebabkan peningkatan risiko keamanan untuk aplikasi Anda. Meskipun sampel dalam mulai cepat menggunakan rahasia klien teks biasa, hal ini hanyalah untuk kesederhanaan. Sebaiknya gunakan kredensial sertifikat, bukan rahasia klien dalam aplikasi klien rahasia Anda, terutama aplikasi yang ingin Anda sebarkan ke produksi.

  3. Edit .env dan ganti ID Microsoft Entra dan titik akhir Microsoft Graph dengan nilai berikut:

    • Untuk titik akhir Microsoft Entra, ganti Enter_the_Cloud_Instance_Id_Here dengan https://login.microsoftonline.com.
    • Untuk titik akhir Microsoft Graph, ganti Enter_the_Graph_Endpoint_Here dengan https://graph.microsoft.com/.

Jika Anda mencoba menjalankan aplikasi pada saat ini, Anda akan menerima HTTP 403 - Kesalahan terlarang: Insufficient privileges to complete the operation. Kesalahan ini terjadi karena izin khusus aplikasi memerlukan persetujuan admin: Administrator Aplikasi atau Administrator Global harus memberikan persetujuan untuk aplikasi Anda. Memilih salah satu opsi di bawah ini bergantung pada peran Anda:

Administrator

Jika Anda diberi peran Administrator Aplikasi atau Administrator Global, buka halaman Izin API di Pendaftaran Aplikasi portal Azure dan pilih Berikan persetujuan admin untuk {Tenant Name} (di mana {Tenant Name} adalah nama direktori Anda).

Pengguna standar

Jika Anda adalah pengguna standar penyewa Anda, maka Anda perlu meminta Administrator Global untuk memberikan persetujuan admin untuk aplikasi Anda. Untuk melakukannya, berikan URL berikut kepada administrator:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

Mana:

  • Enter_the_Tenant_Id_Here - ganti nilai ini dengan Id Penyewa atau Nama penyewa (misalnya, contoso.microsoft.com)
  • Enter_the_Application_Id_Here - adalah ID aplikasi (klien) untuk aplikasi yang Anda daftarkan.

Langkah 5: Menjalankan aplikasi

Temukan folder root sampel (jika package.json berada) di prompt perintah atau konsol. Anda harus menginstal dependensi yang diperlukan aplikasi sampel Anda sebelum menjalankannya untuk pertama kali:

npm install

Kemudian, jalankan aplikasi melalui prompt perintah atau konsol:

node . --op getUsers

Anda akan melihat pada output konsol beberapa fragmen JSON yang mewakili daftar pengguna di direktori Microsoft Entra Anda.

Tentang kode

Di bawah ini, beberapa aspek penting dari aplikasi sampel yang dibahas.

Simpul MSAL

MSAL Node adalah lpustaka yang digunakan untuk memasukkan pengguna dan meminta token yang digunakan untuk mengakses API yang dilindungi oleh platform identitas Microsoft. Seperti yang dijelaskan, mulai cepat ini meminta token berdasarkan izin aplikasi (menggunakan identitas aplikasi sendiri) alih-alih izin yang didelegasikan. Alur otentikasi yang digunakan dalam kasus ini dikenal sebagai aliran kredensial klien OAuth 2.0. Untuk informasi selengkapnya tentang cara menggunakan MSAL Node dengan aplikasi daemon, lihat Skenario: Aplikasi Daemon.

Anda dapat menginstal Node MSAL dengan menjalankan perintah npm berikut.

npm install @azure/msal-node --save

Inisialisasi MSAL

Anda bisa menambahkan referensi untuk MSAL dengan menambahkan kode berikut:

const msal = require('@azure/msal-node');

Lalu, inisialisasi MSAL menggunakan kode berikut:

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
        clientSecret: "Enter_the_Client_Secret_Here",
   }
};
const cca = new msal.ConfidentialClientApplication(msalConfig);
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.
authority Titik akhir STS untuk diautentikasi oleh pengguna. Biasanya https://login.microsoftonline.com/{tenant} untuk cloud publik, di mana {tenant} merupakan nama penyewa atau ID penyewa Anda.
clientSecret Adalah rahasia klien yang dibuat untuk aplikasi di portal Microsoft Azure.

Untuk informasi lebih lanjut, silakan lihat dokumentasi referensi untuk ConfidentialClientApplication

Meminta token

Untuk meminta token menggunakan identitas aplikasi, gunakan metode acquireTokenByClientCredential:

const tokenRequest = {
    scopes: [ 'https://graph.microsoft.com/.default' ],
};

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);
Mana: Deskripsi
tokenRequest Berisi cakupan yang diminta. Untuk klien rahasia, ini harus menggunakan format yang mirip dengan {Application ID URI}/.default untuk menunjukkan bahwa cakupan yang diminta adalah yang didefinisikan secara statis dalam objek aplikasi yang diatur di portal Microsoft Azure (untuk Microsoft Graph, {Application ID URI} mengarah ke https://graph.microsoft.com). Untuk API web kustom, {Application ID URI} ditentukan pada bagian Mengekspos API di Pendaftaran Aplikasi portal Microsoft Azure.
tokenResponse Respons berisi token akses untuk cakupan yang diminta.

Bantuan dan dukungan

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

Langkah berikutnya

Untuk mempelajari lebih lanjut tentang pengembangan aplikasi daemon/konsol dengan MSAL Node, lihat tutorial:

Aplikasi daemon yang memanggil API web