Tutorial: Memanggil Microsoft Graph API di aplikasi daemon konsol Node.js

  • Artikel

Dalam tutorial ini, Anda membuat aplikasi daemon konsol yang memanggil Microsoft Graph API menggunakan identitasnya sendiri. Aplikasi daemon yang Anda buat menggunakan Microsoft Authentication Library (MSAL) untuk Node.js.

Ikuti langkah-langkah dalam tutorial ini untuk:

  • Mendaftarkan aplikasi di portal Microsoft Azure
  • Membuat proyek aplikasi daemon konsol Node.js
  • Menambahkan logika autentikasi ke aplikasi
  • Menambahkan detail pendaftaran aplikasi
  • Menambahkan metode untuk memanggil API web
  • Menguji aplikasi

Prasyarat

Mendaftarkan aplikasi

Pertama, selesaikan langkah-langkah dalam Mendaftarkan aplikasi dengan platform identitas Microsoft untuk mendaftarkan aplikasi Anda.

Gunakan pengaturan berikut untuk pendaftaran aplikasi Anda:

  • Nama: NodeDaemonApp (disarankan)
  • Jenis akun yang didukung: Hanya akun dalam direktori organisasi ini
  • Izin API: Microsoft API>Microsoft Graph>Izin Aplikasi>User.Read.All
  • Rahasia klien: ********* (catat nilai ini untuk digunakan pada langkah selanjutnya - hanya ditampilkan sekali)

Membuat proyek

  1. Mulailah dengan membuat direktori untuk proyek tutorial Node.js ini. Misalnya, NodeDaemonApp.

  2. Di terminal Anda, ubah ke direktori yang Anda buat (root proyek), lalu jalankan perintah berikut:

    npm init -y
npm install --save dotenv yargs axios @azure/msal-node

  3. Selanjutnya, edit file package.json di root proyek dan awali nilai main dengan bin/, seperti ini:

    "main": "bin/index.js",

  4. Sekarang buat direktori bin, dan di dalam bin, tambahkan kode berikut ke file baru bernama index.js:

    #!/usr/bin/env node

// read in env settings
require('dotenv').config();

const yargs = require('yargs');

const fetch = require('./fetch');
const auth = require('./auth');

const options = yargs
    .usage('Usage: --op <operation_name>')
    .option('op', { alias: 'operation', describe: 'operation name', type: 'string', demandOption: true })
    .argv;

async function main() {
    console.log(`You have selected: ${options.op}`);

    switch (yargs.argv['op']) {
        case 'getUsers':

            try {
                // here we get an access token
                const authResponse = await auth.getToken(auth.tokenRequest);

                // call the web API with the access token
                const users = await fetch.callApi(auth.apiConfig.uri, authResponse.accessToken);

                // display result
                console.log(users);
            } catch (error) {
                console.log(error);
            }

            break;
        default:
            console.log('Select a Graph operation first');
            break;
    }
};

main();

File index.js yang baru saja Anda buat merujuk pada dua modul node lain yang akan Anda buat berikutnya:

  • auth.js - Menggunakan Node MSAL untuk memperoleh token akses dari platform identitas Microsoft.
  • fetch.js - Meminta data dari Microsoft Graph API dengan menyertakan token akses (diperoleh di auth.js) dalam permintaan HTTP ke API.

Di akhir tutorial, struktur file dan direktori proyek Anda akan terlihat seperti ini:

NodeDaemonApp/
├── bin
│   ├── auth.js
│   ├── fetch.js
│   ├── index.js
├── package.json
└── .env

Menambahkan logika autentikasi

Di dalam direktori bin, tambahkan kode berikut ke file baru bernama auth.js. Kode di auth.js memperoleh token akses dari platform identitas Microsoft untuk disertakan dalam permintaan Microsoft Graph API.

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

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + '/' + process.env.TENANT_ID,
        clientSecret: process.env.CLIENT_SECRET,
    }
};

/**
 * With client credentials flows permissions need to be granted in the portal by a tenant administrator.
 * The scope is always in the format '<resource>/.default'. For more, visit:
 * https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
 */
const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '/.default'],
};

const apiConfig = {
    uri: process.env.GRAPH_ENDPOINT + '/v1.0/users',
};

/**
 * Initialize a confidential client application. For more info, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-confidential-client-application.md
 */
const cca = new msal.ConfidentialClientApplication(msalConfig);

/**
 * Acquires token with client credentials.
 * @param {object} tokenRequest
 */
async function getToken(tokenRequest) {
    return await cca.acquireTokenByClientCredential(tokenRequest);
}

module.exports = {
    apiConfig: apiConfig,
    tokenRequest: tokenRequest,
    getToken: getToken
};

Dalam cuplikan kode di atas, kami membuat objek konfigurasi (msalConfig) terlebih dahulu, dan meneruskannya untuk menginisialisasi MSAL ConfidentialClientApplication. Kemudian kami membuat metode untuk memperoleh token melalui info masuk klien dan akhirnya mengekspos modul ini untuk diakses oleh main.js. Parameter konfigurasi dalam modul ini diambil dari file lingkungan, yang akan kami buat pada langkah berikutnya.

Menambahkan detail pendaftaran aplikasi

Buat file lingkungan untuk menyimpan detail pendaftaran aplikasi yang akan digunakan saat memperoleh token. Untuk melakukannya, buat file bernama .env di dalam folder akar sampel (NodeDaemonApp), dan tambahkan kode berikut:

# Credentials
TENANT_ID=Enter_the_Tenant_Id_Here
CLIENT_ID=Enter_the_Application_Id_Here
CLIENT_SECRET=Enter_the_Client_Secret_Here

# Endpoints
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here/
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here/

Isi detail berikut dengan nilai yang diperoleh dari portal pendaftaran aplikasi Azure:

  • Enter_the_Tenant_Id_here harus menjadi salah satu hal berikut:
    • Jika aplikasi Anda mendukung akun di direktori organisasi ini, ganti nilai ini dengan ID Penyewa atau nama Penyewa. Contohnya:contoso.microsoft.com
    • Jika aplikasi Anda mendukung akun di direktori organisasi apa pun, ganti nilai ini dengan organizations.
    • Jika aplikasi Anda mendukung akun di direktori organisasi dan akun Microsoft pribadi apa pun, ganti nilai ini dengan common.
    • Untuk membatasi dukungan hanya untuk akun Microsoft pribadi, ganti nilai ini dengan consumers.
  • Enter_the_Application_Id_Here: ID Aplikasi (klien) dari aplikasi yang Anda daftarkan.
  • Enter_the_Cloud_Instance_Id_Here: Instans cloud Azure tempat aplikasi Anda terdaftar.
    • Untuk cloud Azure utama (atau global),masukkan https://login.microsoftonline.com.
    • Untuk cloud nasional (misalnya, Tiongkok), Anda dapat menemukan nilai yang sesuai di Cloud nasional.
  • Enter_the_Graph_Endpoint_Here adalah instans Microsoft Graph API yang harus dikomunikasikan dengan aplikasi.
    • Untuk titik akhir Microsoft Graph API global, ganti kedua instans string ini dengan https://graph.microsoft.com.
    • Untuk titik akhir dalam penyebaran cloud nasional, lihat Penyebaran cloud nasional dalam dokumentasi Microsoft Graph.

Menambahkan metode untuk memanggil API web

Di dalam folder bin, buat file lain bernama fetch.js dan tambahkan kode berikut untuk melakukan panggilan REST ke Microsoft Graph API:

const axios = require('axios');

/**
 * Calls the endpoint with authorization bearer token.
 * @param {string} endpoint
 * @param {string} accessToken
 */
async function callApi(endpoint, accessToken) {

    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('request made to web API at: ' + new Date().toString());

    try {
        const response = await axios.get(endpoint, options);
        return response.data;
    } catch (error) {
        console.log(error)
        return error;
    }
};

module.exports = {
    callApi: callApi
};

Di sini, metode callApi digunakan untuk membuat permintaan GET HTTP terhadap sumber daya yang dilindungi yang memerlukan token akses. Kemudian, permintaan mengembalikan konten ke penelepon. Metode ini akan menambahkan token yang diperoleh di header Otorisasi HTTP. Sumber daya yang dilindungi di sini adalah titik akhir pengguna Microsoft Graph API yang menampilkan pengguna di penyewa tempat aplikasi ini didaftarkan.

Menguji aplikasi

Anda telah menyelesaikan pembuatan aplikasi dan sekarang Anda siap untuk menguji fungsi aplikasi.

Mulai aplikasi daemon konsol Node.js dengan menjalankan perintah berikut dari dalam akar folder proyek Anda:

node . --op getUsers

Ini akan menghasilkan beberapa respons JSON dari Microsoft Graph API dan Anda akan melihat berbagai objek pengguna di konsol:

You have selected: getUsers
request made to web API at: Fri Jan 22 2021 09:31:52 GMT-0800 (Pacific Standard Time)
{
    '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
    value: [
        {
            displayName: 'Adele Vance'
            givenName: 'Adele',
            jobTitle: 'Retail Manager',
            mail: 'AdeleV@msaltestingjs.onmicrosoft.com',
            mobilePhone: null,
            officeLocation: '18/2111',
            preferredLanguage: 'en-US',
            surname: 'Vance',
            userPrincipalName: 'AdeleV@msaltestingjs.onmicrosoft.com',
            id: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'
        }
    ]
}

Command-line interface displaying Graph response

Cara kerja aplikasi

Aplikasi ini menggunakan Pemberian info masuk klien OAuth 2.0. Jenis pemberian ini umumnya digunakan untuk interaksi server-ke-server yang harus dijalankan di latar belakang, tanpa interaksi langsung dengan pengguna. Alur pemberian info masuk mengizinkan layanan web (klien rahasia) untuk menggunakan info masuknya sendiri, bukan meniru identitas pengguna, untuk mengautentikasi saat memanggil layanan web lain. Jenis aplikasi yang didukung dengan model autentikasi ini biasanya daemon atau akun layanan.

Cakupan untuk meminta aliran info masuk klien adalah nama sumber daya yang diikuti oleh dengan /.default. Notasi ini memberi tahu Microsoft Entra ID untuk menggunakan izin tingkat aplikasi yang dinyatakan secara statis selama pendaftaran aplikasi. Selain itu, izin API ini harus diberikan oleh administrator penyewa.

Langkah berikutnya

Jika Anda ingin mendalami pengembangan aplikasi daemon Node.js di platform identitas Microsoft, lihat seri skenario multi-bagian kami:

Skenario: Aplikasi Daemon