Memanggil API dalam contoh aplikasi daemon Node.js

  • Artikel

Artikel ini menggunakan sampel Node.js aplikasi daemon untuk menunjukkan kepada Anda bagaimana aplikasi daemon memperoleh token untuk memanggil API web. Microsoft Entra ID untuk pelanggan melindungi API Web.

Aplikasi daemon memperoleh token atas nama dirinya sendiri (bukan atas nama pengguna). Pengguna tidak dapat berinteraksi dengan aplikasi daemon karena memerlukan identitasnya sendiri. Jenis aplikasi ini meminta token akses dengan menggunakan identitas aplikasinya dan menyajikan ID aplikasi, kredensial (kata sandi atau sertifikat), dan URI ID aplikasi ke ID Eksternal.

Aplikasi daemon menggunakan pemberian kredensial klien OAuth 2.0 standar. Untuk menyederhanakan proses memperoleh token, sampel yang kami gunakan dalam artikel ini menggunakan Microsoft Authentication Library for Node (MSAL Node).

Prasyarat

Mendaftarkan aplikasi daemon dan API web

Dalam langkah ini, Anda membuat daemon dan pendaftaran aplikasi API web, dan Anda menentukan cakupan API web Anda.

Mendaftarkan aplikasi API web

  1. Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih ke penyewa pelanggan Anda.

  3. TelusuriAplikasi>Identitas>Pendaftaran aplikasi.

  4. Pilih + Pendaftaran baru.

  5. Di halaman Daftarkan aplikasi yang muncul, masukkan informasi pendaftaran aplikasi Anda:

    1. Di bagian Nama, masukkan nama aplikasi yang bermakna yang akan ditampilkan kepada pengguna aplikasi, misalnya ciam-ToDoList-api.

    2. Di bawah Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini.

  6. Pilih Daftar untuk membuat aplikasi.

  7. Panel Gambaran Umum aplikasi ditampilkan saat pendaftaran selesai. Rekam ID Direktori (penyewa) dan ID Aplikasi (klien) yang akan digunakan dalam kode sumber aplikasi Anda.

Mengonfigurasi peran aplikasi

API perlu menerbitkan minimal satu peran aplikasi untuk aplikasi, juga disebut Izin Aplikasi, agar aplikasi klien mendapatkan token akses sebagai diri mereka sendiri. Izin aplikasi adalah jenis izin yang harus diterbitkan API ketika mereka ingin mengaktifkan aplikasi klien untuk berhasil mengautentikasi sebagai diri mereka sendiri dan tidak perlu memasukkan pengguna. Untuk menerbitkan izin aplikasi, ikuti langkah-langkah berikut:

  1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-ToDoList-api) untuk membuka halaman Gambaran Umum.

  2. Di bawah Kelola, pilih Peran aplikasi.

  3. Pilih Buat peran aplikasi, lalu masukkan nilai berikut, lalu pilih Terapkan untuk menyimpan perubahan Anda:

    Properti Nilai
    Nama tampilan ToDoList.Read.All
    Tipe anggota yang diperbolehkan Aplikasi
    Nilai ToDoList.Read.All
    Deskripsi Izinkan aplikasi membaca daftar ToDo setiap pengguna menggunakan 'TodoListApi'

  4. Pilih Buat peran aplikasi lagi, lalu masukkan nilai berikut untuk peran aplikasi kedua, lalu pilih Terapkan untuk menyimpan perubahan Anda:

    Properti Nilai
    Nama tampilan ToDoList.ReadWrite.All
    Tipe anggota yang diperbolehkan Aplikasi
    Nilai ToDoList.ReadWrite.All
    Deskripsi Izinkan aplikasi membaca dan menulis daftar ToDo setiap pengguna menggunakan 'ToDoListApi'

Konfigurasikan klaim opsional

Token yang dikembalikan oleh identitas Microsoft tetap lebih kecil untuk memastikan performa optimal oleh klien yang memintanya. Akibatnya, beberapa klaim tidak lagi ada dalam token secara default dan harus diminta secara khusus per aplikasi. Untuk aplikasi ini, Anda menyertakan klaim opsional idtyp untuk membantu API web menentukan apakah token adalah token aplikasi atau token aplikasi+pengguna. Meskipun kombinasi klaim scp dan peran dapat digunakan untuk tujuan yang sama, penggunaan klaim idtyp adalah cara termampu untuk memberi tahu token aplikasi dan token aplikasi +pengguna terpisah. Misalnya, nilai klaim ini adalah aplikasi ketika token adalah token khusus aplikasi.

Gunakan langkah-langkah berikut untuk mengonfigurasi klaim opsional idtyp :

  1. Di bagian Kelola, pilih Konfigurasi token.

  2. Pilih Tambahkan klaim opsional.

  3. Di bawah Jenis token, pilih Akses.

  4. Pilih idtyp klaim opsional.

  5. Pilih Tambahkan untuk menyimpan perubahan Anda.

Mendaftarkan aplikasi daemon

Untuk memungkinkan aplikasi Anda memasukkan pengguna dengan Microsoft Entra, ID Microsoft Entra untuk pelanggan harus mengetahui aplikasi yang Anda buat. Pendaftaran aplikasi membangun hubungan kepercayaan antara aplikasi dan Microsoft Entra. Saat Anda mendaftarkan aplikasi, ID Eksternal menghasilkan pengidentifikasi unik yang dikenal sebagai ID Aplikasi (klien), nilai yang digunakan untuk mengidentifikasi aplikasi Anda saat membuat permintaan autentikasi.

Langkah-langkah berikut menunjukkan cara mendaftarkan aplikasi Anda di pusat admin Microsoft Entra:

  1. Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan di menu atas untuk beralih ke penyewa pelanggan Anda.

  3. TelusuriAplikasi>Identitas>Pendaftaran aplikasi.

  4. Pilih + Pendaftaran baru.

  5. Di halaman Daftarkan aplikasi yang muncul;

    1. Masukkan Nama aplikasi yang bermakna yang ditampilkan kepada pengguna aplikasi, misalnya ciam-client-app.
    2. Di bawah Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini.

  6. Pilih Daftar.

  7. Panel Gambaran Umum aplikasi ditampilkan setelah pendaftaran berhasil. Catat ID Aplikasi (klien) yang akan digunakan dalam kode sumber aplikasi Anda.

Membuat rahasia klien

Buat rahasia klien untuk aplikasi terdaftar. Aplikasi ini menggunakan rahasia klien untuk membuktikan identitasnya ketika meminta token.

  1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-client-app) untuk membuka halaman Gambaran Umum.
  2. Di bagian Kelola, pilih Sertifikat & rahasia.
  3. Pilih Rahasia klien baru.
  4. Dalam kotak Deskripsi , masukkan deskripsi untuk rahasia klien (misalnya, rahasia klien aplikasi ciam).
  5. Di bawah Kedaluwarsa, pilih durasi yang rahasianya valid (sesuai aturan keamanan organisasi Anda), lalu pilih Tambahkan.
  6. Rekam Nilai rahasia. Anda akan menggunakan nilai ini untuk konfigurasi pada langkah selanjutnya.

Catatan

Nilai rahasia tidak akan ditampilkan lagi, dan tidak dapat diambil dengan cara apa pun, setelah Anda menavigasi jauh dari halaman Sertifikat dan rahasia , jadi pastikan Anda merekamnya.
Untuk keamanan yang ditingkatkan, pertimbangkan untuk menggunakan sertifikat alih-alih rahasia klien.

Memberikan izin API ke aplikasi daemon

  1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat, seperti ciam-client-app.

  2. Di bagian Kelola, pilih Izin API.

  3. Di bagian Izin yang dikonfigurasi, pilih Tambahkan izin.

  4. Pilih tab API Saya.

  5. Dalam daftar API, pilih API seperti ciam-ToDoList-api.

  6. Pilih opsi Izin aplikasi . Kami memilih opsi ini saat aplikasi masuk sebagai dirinya sendiri, bukan pengguna.

  7. Dari daftar izin, pilih TodoList.Read.All, ToDoList.ReadWrite.All (gunakan kotak pencarian jika perlu).

  8. Pilih tombol Tambahkan izin akses.

  9. Pada titik ini, Anda telah menetapkan izin dengan benar. Namun, karena aplikasi daemon tidak memungkinkan pengguna untuk berinteraksi dengannya, pengguna itu sendiri tidak dapat menyetujui izin ini. Untuk mengatasi masalah ini, Anda sebagai admin harus menyetujui izin ini atas nama semua pengguna di penyewa:

    1. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda, lalu pilih Ya.
    2. Pilih Refresh, lalu verifikasi bahwa Diberikan untuk <nama> penyewa Anda muncul di bawah Status untuk kedua izin.

Mengkloning atau mengunduh sampel aplikasi daemon dan API web

Untuk mendapatkan kode sampel aplikasi web, Anda bisa melakukan salah satu tugas berikut:

  • Unduh file .zip atau klon aplikasi web sampel dari GitHub dengan menjalankan perintah berikut:

        git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

Jika Anda memilih untuk mengunduh file .zip , ekstrak file aplikasi sampel ke folder di mana total panjang jalur adalah 260 karakter atau lebih sedikit.

Menginstal dependensi proyek

  1. Buka jendela konsol, dan ubah ke direktori yang berisi aplikasi sampel Node.js:

        cd 2-Authorization\3-call-api-node-daemon\App

  2. Jalankan perintah berikut untuk menginstal dependensi aplikasi:

        npm install && npm update

Mengonfigurasi sampel aplikasi daemon dan API

Untuk menggunakan pendaftaran aplikasi Anda di sampel aplikasi web klien:

  1. Di editor kode Anda, buka App\authConfig.js file.

  2. Temukan tempat penampung:

    • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) dari aplikasi daemon yang Anda daftarkan sebelumnya.

    • Enter_the_Tenant_Subdomain_Here dan ganti dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda adalah contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.

    • Enter_the_Client_Secret_Here dan ganti dengan nilai rahasia aplikasi daemon yang Anda salin sebelumnya.

    • Enter_the_Web_Api_Application_Id_Here dan ganti dengan ID Aplikasi (klien) api web yang Anda salin sebelumnya.

Untuk menggunakan pendaftaran aplikasi Anda di sampel API web:

  1. Di editor kode Anda, buka API\ToDoListAPI\appsettings.json file.

  2. Temukan tempat penampung:

    • Enter_the_Application_Id_Here dan ganti dengan ID Aplikasi (klien) API web yang Anda salin.

    • Enter_the_Tenant_Id_Here dan ganti dengan ID Direktori (penyewa) yang Anda salin sebelumnya.

    • Enter_the_Tenant_Subdomain_Here dan ganti dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda adalah contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.

Menjalankan dan menguji sampel aplikasi daemon dan API

  1. Buka jendela konsol, lalu jalankan API web dengan menggunakan perintah berikut:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. Jalankan klien aplikasi web dengan menggunakan perintah berikut:

        2-Authorization\3-call-api-node-daemon\App
     node . --op getToDos

Jika aplikasi daemon dan API web Anda berhasil berjalan, Anda akan melihat sesuatu yang mirip dengan array JSON berikut di jendela konsol Anda

{
    id: 1,
    owner: '3e8....-db63-43a2-a767-5d7db...',
    description: 'Pick up grocery'
},
{
    id: 2,
    owner: 'c3cc....-c4ec-4531-a197-cb919ed.....',
    description: 'Finish invoice report'
},
{
    id: 3,
    owner: 'a35e....-3b8a-4632-8c4f-ffb840d.....',
    description: 'Water plants'
}

Cara kerjanya

Aplikasi Node.js menggunakan kredensial klien OAuth 2.0 yang diberikan untuk memperoleh token akses untuk dirinya sendiri dan bukan untuk pengguna. Token akses yang diminta aplikasi berisi izin yang diwakili sebagai peran. Alur kredensial klien menggunakan sekumpulan izin ini sebagai pengganti cakupan pengguna untuk token aplikasi. Anda mengekspos izin aplikasi ini di API web sebelumnya, lalu memberikannya ke aplikasi daemon.

Di sisi API, API web harus memverifikasi bahwa token akses memiliki izin yang diperlukan (izin aplikasi). API web tidak dapat menerima token akses yang tidak memiliki izin yang diperlukan.

Akses ke data

Titik akhir API Web harus disiapkan untuk menerima panggilan dari pengguna dan aplikasi. Oleh karena itu, harus memiliki cara untuk menanggapi setiap permintaan yang sesuai. Misalnya, panggilan dari pengguna melalui izin/cakupan yang didelegasikan menerima data pengguna yang harus dilakukan. Di sisi lain, panggilan dari aplikasi melalui izin/peran aplikasi mungkin menerima seluruh daftar tugas. Namun, dalam artikel ini, kami hanya melakukan panggilan aplikasi, jadi kami tidak perlu mengonfigurasi izin/cakupan yang didelegasikan.

Langkah berikutnya