Mengautentikasi ke sumber daya Azure dari aplikasi JavaScript yang dihosting secara lokal

Aplikasi yang dihosting di luar Azure, seperti lokal atau di pusat data pihak ketiga, harus menggunakan perwakilan layanan aplikasi melalui ID Microsoft Entra untuk mengautentikasi ke layanan Azure. Di bagian depan, Anda mempelajari:

• Cara mendaftarkan aplikasi dengan Microsoft Entra untuk membuat perwakilan layanan
• Cara mengatur peran pada izin cakupan
• Cara melakukan autentikasi menggunakan perwakilan layanan atau service principal dari kode aplikasi Anda

Menggunakan prinsipap layanan aplikasi khusus memungkinkan Anda mematuhi prinsip hak akses minimal saat mengakses sumber daya Azure. Izin terbatas pada persyaratan khusus aplikasi selama pengembangan, mencegah akses yang tidak disengaja ke sumber daya Azure yang ditujukan untuk aplikasi atau layanan lain. Pendekatan ini juga membantu menghindari masalah saat aplikasi dipindahkan ke produksi dengan memastikannya tidak terlalu istimewa di lingkungan pengembangan.

Pendaftaran aplikasi yang berbeda harus dibuat untuk setiap lingkungan tempat aplikasi dihosting. Ini memungkinkan izin sumber daya khusus lingkungan dikonfigurasi untuk setiap perwakilan layanan dan memastikan aplikasi yang disebarkan ke satu lingkungan tidak berbicara dengan sumber daya Azure di lingkungan lain.

Mendaftarkan aplikasi di Azure

Objek principal layanan aplikasi dibuat melalui pendaftaran aplikasi di Azure dengan menggunakan portal Azure atau Azure CLI.

Portal Azure

1. Di portal Microsoft Azure, gunakan bilah pencarian untuk menavigasi ke halaman Pendaftaran aplikasi.

2. Pada halaman Pendaftaran aplikasi, pilih + Pendaftaran baru.

3. Pada halaman Daftarkan aplikasi:

   • Untuk bidang Nama, masukkan nilai deskriptif yang menyertakan nama aplikasi dan lingkungan target.
   • Untuk Jenis akun yang didukung, pilih Akun di direktori organisasi ini saja (Hanya Microsoft Customer Led - Penyewa tunggal), atau opsi mana yang paling sesuai dengan kebutuhan Anda.

4. Pilih Daftarkan untuk mendaftarkan aplikasi Anda dan buat perwakilan layanan.

   

5. Pada halaman Pendaftaran aplikasi untuk aplikasi Anda, salin ID Aplikasi (klien) dan ID Direktori (penyewa) dan tempelkan di lokasi sementara untuk digunakan nanti dalam konfigurasi kode aplikasi Anda.

6. Pilih Tambahkan sertifikat atau rahasia untuk menyiapkan kredensial untuk aplikasi Anda.

7. Pada halaman Sertifikat & rahasia, pilih + Rahasia klien baru.

8. Pada panel pop-up Tambahkan rahasia klien yang terbuka:

   • Untuk Deskripsi, masukkan nilai Current.
   • Untuk nilai Kedaluwarsa, biarkan nilai default yang direkomendasikan 180 days.
   • Pilih Buat untuk menambahkan rahasia.

9. Pada halaman Sertifikat & rahasia, salin properti Nilai rahasia klien untuk digunakan dalam langkah selanjutnya.

   Nota

   Nilai rahasia klien hanya ditampilkan sekali setelah pendaftaran aplikasi dibuat. Anda dapat menambahkan lebih banyak rahasia klien tanpa membatalkan rahasia klien ini, tetapi tidak ada cara untuk menampilkan nilai ini lagi.

Azure CLI

Perintah Azure CLI dapat dijalankan di Azure Cloud Shell atau pada stasiun kerja dengan Azure CLI terpasang.

1. Gunakan perintah az ad sp create-for-rbac untuk membuat pendaftaran aplikasi baru dan prinsipal layanan untuk aplikasi.

   az ad sp create-for-rbac --name <service-principal-name>
   

   Output perintah ini menyerupai JSON seperti berikut:

   {
     "appId": "00000000-0000-0000-0000-000000000000",
     "displayName": "<service-principal-name>",
     "password": "abcdefghijklmnopqrstuvwxyz",
     "tenant": "11111111-1111-1111-1111-111111111111"
   }
   

2. Salin output ini ke dalam file sementara di editor teks, karena Anda akan memerlukan nilai-nilai ini di langkah mendatang.

   Nota

   Nilai rahasia klien hanya ditampilkan sekali setelah pendaftaran aplikasi dibuat. Anda dapat menambahkan lebih banyak rahasia klien tanpa membatalkan rahasia klien ini, tetapi tidak ada cara untuk menampilkan nilai ini lagi.

Menetapkan peran ke perwakilan layanan aplikasi

Selanjutnya, tentukan peran (izin) apa yang dibutuhkan aplikasi Anda pada sumber daya apa dan tetapkan peran tersebut ke perwakilan layanan yang Anda buat. Peran dapat ditetapkan di tingkat sumber daya, grup sumber daya, atau langganan. Contoh ini menunjukkan cara menetapkan peran di cakupan grup sumber daya, karena sebagian besar aplikasi mengelompokkan semua sumber daya Azure mereka ke dalam satu grup sumber daya.

Portal Azure

1. Di portal Microsoft Azure, buka halaman Gambaran Umum grup sumber daya yang berisi aplikasi Anda.

2. Pilih Kontrol akses (IAM) dari navigasi kiri.

3. Pada halaman Kontrol akses (IAM), pilih + Tambahkan lalu pilih Tambahkan penetapan peran dari menu drop-down. Halaman Tambahkan penetapan peran menyediakan beberapa tab untuk mengonfigurasi dan menetapkan peran.

4. Pada tab Peran , gunakan kotak pencarian untuk menemukan peran yang ingin Anda tetapkan. Pilih peran, lalu pilih Berikutnya.

5. Pada tab Anggota :

   • Untuk Menetapkan akses ke nilai, pilih Pengguna, grup, atau perwakilan layanan .
   • Untuk nilai Anggota , pilih + Pilih anggota untuk membuka panel flyout Pilih anggota .
   • Cari prinsipal layanan yang Anda buat sebelumnya dan pilih dari hasil yang telah difilter. Pilih Pilih untuk memilih grup dan menutup panel flyout.
   • Pilih Tinjau + tetapkan di bawah tab Anggota.

   

6. Di tab Tinjau & Tetapkan, pilih Tinjau & Tetapkan di bagian bawah halaman.

Azure CLI

1. Gunakan perintah az role definition list untuk mendapatkan nama peran yang dapat ditetapkan oleh perwakilan layanan:

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

2. Gunakan perintah az role assignment create untuk menetapkan peran ke perwakilan layanan aplikasi:

   az role assignment create \
       --assignee "<app-Id>" \
       --role "<role-name>" \
       --resource-group "<resource-group-name>"
   

   Untuk informasi tentang mengatur izin di tingkat sumber daya atau langganan menggunakan Azure CLI, lihat Menetapkan peran Azure menggunakan Azure CLI.

Mengatur variabel lingkungan aplikasi

Pada runtime, kredensial tertentu dari pustaka Azure Identity, seperti DefaultAzureCredential, EnvironmentCredential, dan ClientSecretCredential, mencari informasi perwakilan layanan berdasarkan konvensi dalam variabel lingkungan. Ada beberapa cara untuk mengonfigurasi variabel lingkungan saat bekerja dengan JavaScript, tergantung pada alat dan lingkungan Anda.

Terlepas dari pendekatan yang Anda pilih, konfigurasikan variabel lingkungan berikut untuk perwakilan layanan:

• AZURE_CLIENT_ID: Digunakan untuk mengidentifikasi aplikasi terdaftar di Azure.
• AZURE_TENANT_ID: ID penyewa dari Microsoft Entra.
• AZURE_CLIENT_SECRET: Kredensial rahasia yang dihasilkan untuk aplikasi.

Visual Studio Code

Di Visual Studio Code, variabel lingkungan dapat diatur dalam file launch.json proyek Anda. Nilai-nilai ini ditarik secara otomatis saat aplikasi dimulai. Namun, konfigurasi ini tidak bepergian dengan aplikasi Anda selama penyebaran, jadi Anda perlu menyiapkan variabel lingkungan pada lingkungan hosting target Anda.

"configurations": [
{
    "env": {
        "NODE_ENV": "development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
    }
}

Windows

Anda dapat mengatur variabel lingkungan untuk Windows dari baris perintah. Namun, nilai dapat diakses oleh semua aplikasi yang berjalan pada sistem operasi tersebut dan dapat menyebabkan konflik, jadi berhati-hatilah dengan pendekatan ini. Variabel lingkungan dapat diatur pada tingkat pengguna atau sistem.

# Set user environment variables
setx NODE_ENV "development"
setx AZURE_CLIENT_ID "<your-client-id>"
setx AZURE_TENANT_ID "<your-tenant-id>"
setx AZURE_CLIENT_SECRET "<your-client-secret>"

# Set system environment variables - requires running as admin
setx NODE_ENV "development" /m
setx AZURE_CLIENT_ID "<your-client-id>" /m
setx AZURE_TENANT_ID "<your-tenant-id>" /m
setx AZURE_CLIENT_SECRET "<your-client-secret>" /m

PowerShell juga dapat digunakan untuk mengatur variabel lingkungan di tingkat pengguna atau sistem:

# Set user environment variables
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "Machine")

File .env

Untuk pengembangan lokal, Anda dapat menggunakan .env file. Node.js 20.6.0 dan versi yang lebih baru mendukung --env-file flag untuk memuat variabel lingkungan secara otomatis dari .env berkas.

1. Buat .env file di akar proyek Anda:

   AZURE_CLIENT_ID=<your-client-id>
   AZURE_TENANT_ID=<your-tenant-id>
   AZURE_CLIENT_SECRET=<your-client-secret>
   

2. Jalankan aplikasi Anda dengan --env-file bendera:

   node --env-file=.env app.js
   

Untuk versi Node.js sebelumnya, Anda dapat menggunakan paket npm dotenv :

1. Instal paket dotenv:

   npm install dotenv
   

2. Muat variabel lingkungan di aplikasi Anda:

   import 'dotenv/config';
   

Perhatian

Jangan pernah menerapkan .env file atau rahasia klien ke kontrol sumber. Tambahkan .env ke file Anda .gitignore .

Mengautentikasi ke layanan Azure dari aplikasi Anda

Pustaka Azure Identity menyediakan berbagai kredensial—implementasi TokenCredential yang disesuaikan untuk mendukung skenario yang berbeda dan alur autentikasi Microsoft Entra. Langkah-langkah di depan menunjukkan cara menggunakan ClientSecretCredential saat bekerja dengan perwakilan layanan secara lokal dan dalam produksi.

Menerapkan kode

Tambahkan paket @azure/identitas dalam proyek Node.js:

npm install @azure/identity

Layanan Azure diakses menggunakan kelas klien khusus dari berbagai pustaka klien Azure SDK. Untuk kode JavaScript apa pun yang membuat objek klien Azure SDK di aplikasi Anda, ikuti langkah-langkah berikut:

1. ClientSecretCredential Impor kelas dari @azure/identity modul.
2. Buat ClientSecretCredential objek dengan tenantId, , clientIddan clientSecret.
3. Teruskan ClientSecretCredential instans ke konstruktor objek klien Azure SDK.

Contoh pendekatan ini ditampilkan di segmen kode berikut:

import { BlobServiceClient } from '@azure/storage-blob';
import { ClientSecretCredential } from '@azure/identity';

// Authentication
const tenantId = process.env.AZURE_TENANT_ID;
const clientId = process.env.AZURE_CLIENT_ID;
const clientSecret = process.env.AZURE_CLIENT_SECRET;

// Azure Storage account name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!tenantId || !clientId || !clientSecret || !accountName) {
  throw Error('Required environment variables not found');
}

const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  credential
);

Pendekatan alternatif adalah meneruskan ClientSecretCredential objek langsung ke konstruktor klien Azure SDK:

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new ClientSecretCredential(tenantId, clientId, clientSecret)
);