Menggunakan kredensial sertifikat dengan Node MSAL

Anda dapat membangun aplikasi klien rahasia dengan MSAL Node (aplikasi web, aplikasi daemon, dll). Kredensial klien wajib untuk klien rahasia.

Prasyarat

Pemahaman yang baik tentang Menginisialisasi aplikasi klien rahasia.

Anda dapat membangun aplikasi klien rahasia dengan MSAL Node (aplikasi web, aplikasi daemon, dll). Kredensial klien wajib untuk klien rahasia. Kredensial klien dapat berupa:

managed identity: ini adalah skenario tanpa sertifikat, di mana kepercayaan ditetapkan melalui infrastruktur Azure. Tidak diperlukan manajemen rahasia/sertifikat. MSAL belum menerapkan fitur ini, tetapi Anda dapat menggunakan Azure Identity SDK sebagai gantinya. Lihat Dokumentasi identitas terkelola untuk sumber daya Azure
clientSecret: string rahasia yang dihasilkan selama pendaftaran aplikasi, atau pendaftaran pasca diperbarui untuk aplikasi yang ada. Ini tidak disarankan untuk lingkungan produksi.
clientCertificate: sertifikat yang ditetapkan selama pendaftaran aplikasi. Sertifikat harus memiliki kunci privat, karena digunakan untuk menandatangani pernyataan yang dihasilkan MSAL. thumbprintSha256 adalah thumbprint sertifikat X.509 SHA-256, dan privateKey adalah kunci privat yang dikodekan PEM.
clientAssertion: alih-alih membiarkan MSAL membuat pernyataan, pengembang aplikasi mengambil kendali. Berguna untuk menambahkan klaim tambahan ke pernyataan atau untuk menggunakan KeyVault untuk penandatanganan, bukan sertifikat lokal. Sertifikat yang digunakan untuk menandatangani pernyataan masih perlu ditetapkan selama pendaftaran aplikasi.

Catatan: Aplikasi 1p mungkin diperlukan untuk juga mengirim x5c. Ini adalah rantai sertifikat X.509 yang digunakan dalam skenario autentikasi nama subjek/penerbit.

Menggunakan rahasia dan sertifikat dengan aman

Rahasia tidak boleh dikodekan secara permanen. Paket npm dotenv dapat digunakan untuk menyimpan rahasia atau sertifikat dalam file .env (terletak di direktori akar proyek) yang harus disertakan dalam .gitignore untuk mencegah unggahan rahasia yang tidak disengaja.

Sertifikat juga dapat dibaca dari file melalui modul fs NodeJS. Namun, mereka tidak boleh disimpan di direktori proyek. Aplikasi produksi harus mengambil sertifikat dari Azure KeyVault, atau brankas kunci aman lainnya.

Silakan lihat sertifikat dan rahasia untuk informasi lebih lanjut.

Lihat sampel MSAL: auth-code-with-certs

Mendaftarkan sertifikat

Jika Anda tidak memiliki sertifikat, Anda dapat membuat sertifikat yang ditandatangani sendiri menggunakan PowerShell atau menggunakan Azure KeyVault.

Anda perlu mengunggah sertifikat Anda ke Microsoft Entra ID.

Navigasi ke portal Azure dan pilih pendaftaran aplikasi Microsoft Entra Anda.
Pilih tab Sertifikat & rahasia di sebelah kiri.
Klik Unggah sertifikat dan pilih file sertifikat yang akan diunggah (misalnya example.crt).
Klik Tambahkan. Setelah sertifikat diunggah, thumbprint (SHA-256), tanggal mulai, dan nilai kedaluwarsa ditampilkan.

Untuk informasi selengkapnya, lihat: Mendaftarkan sertifikat Anda dengan platform identitas Microsoft

Menginisialisasi MSAL Node dengan sertifikat

const msal = require('@azure/msal-node');
require('dotenv').config(); // process.env now has the values defined in a .env file

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: process.env.privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Baik thumbprintSha256 maupun privateKey harus berupa string. privateKey selanjutnya diharapkan berbentuk berikut (PKCS#8):

Note

Atau, kunci privat Anda dapat dimulai dengan -----BEGIN PRIVATE KEY----- ( PKCS#8 yang tidak terenkripsi) atau -----BEGIN RSA PRIVATE KEY----- (PKCS#1). Format ini juga diizinkan. Berikut ini dapat digunakan untuk mengonversi kunci yang kompatibel ke jenis kunci PKCS#8:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in example.key -out example.key

Jika Anda telah mengenkripsi kunci privat Anda (atau jika kunci privat Anda sudah dienkripsi) dengan frasa pass, Anda harus mendekripsinya sebelum meneruskannya ke MSAL Node.

Penting: Jangan pernah menanamkan kata sandi langsung di dalam kode sumber. Baik kunci privat sertifikat maupun kata sandi dekripsi opsional harus diambil dari lokasi yang aman (misalnya Azure KeyVault) dan diterapkan secara aman bersama API web Anda.

Ini dapat dilakukan menggunakan modul kripto Node. Gunakan metode createPrivateKey() untuk mengurai dan mengekspor kunci Anda:

const fs = require('fs');
const crypto = require('crypto');

const privateKeySource = fs.readFileSync('<path_to_key>/example.key')

const privateKeyObject = crypto.createPrivateKey({
    key: privateKeySource,
    passphrase: process.env.YOUR_PASSPHRASE,
    format: 'pem'
});

const privateKey = privateKeyObject.export({
    format: 'pem',
    type: 'pkcs8'
});

(Opsional) Mengonversi pfx ke pem

OpenSSL dapat digunakan untuk mengonversi file sertifikat yang dikodekan pfx ke pem:

    openssl pkcs12 -in certificate.pfx -out certificate.pem

Jika konversi perlu terjadi secara terprogram, maka Anda mungkin harus mengandalkan paket pihak ke-3, karena Node.js tidak menawarkan metode asli untuk ini. Misalnya, menggunakan implementasi TLS populer seperti node-forge, Anda dapat melakukan:

const forge = require('node-forge');

/**
 * @param {string} pfx: certificate + private key combination in pfx format
 * @param {string} passphrase: passphrase used to encrypt pfx file
 * @returns {Object}
 */
function convertPFX(pfx, passphrase = null) {

    const asn = forge.asn1.fromDer(forge.util.decode64(pfx));
    const p12 = forge.pkcs12.pkcs12FromAsn1(asn, true, passphrase);

    // Retrieve key data
    const keyData = p12.getBags({ bagType: forge.pki.oids.pkcs8ShroudedKeyBag })[forge.pki.oids.pkcs8ShroudedKeyBag]
        .concat(p12.getBags({ bagType: forge.pki.oids.keyBag })[forge.pki.oids.keyBag]);

    // Retrieve certificate data
    const certBags = p12.getBags({ bagType: forge.pki.oids.certBag })[forge.pki.oids.certBag];
    const certificate = forge.pki.certificateToPem(certBags[0].cert)

    // Convert a Forge private key to an ASN.1 RSAPrivateKey
    const rsaPrivateKey = forge.pki.privateKeyToAsn1(keyData[0].key);

    // Wrap an RSAPrivateKey ASN.1 object in a PKCS#8 ASN.1 PrivateKeyInfo
    const privateKeyInfo = forge.pki.wrapRsaPrivateKey(rsaPrivateKey);

    // Convert a PKCS#8 ASN.1 PrivateKeyInfo to PEM
    const privateKey = forge.pki.privateKeyInfoToPem(privateKeyInfo);

    console.log("Converted certificate: \n", certificate);
    console.log("Converted key: \n", privateKey);

    return {
        certificate: certificate,
        key: privateKey
    };
}

(Opsional) Membuat server HTTPS

Protokol OAuth 2.0 merekomendasikan penggunaan koneksi HTTPS jika memungkinkan. Sebagian besar layanan cloud seperti Azure App Service akan menyediakan koneksi HTTPS secara default melalui proksi. Jika untuk tujuan pengujian, Anda ingin menyiapkan server HTTPS Anda sendiri, lihat dokumentasi Node.js untuk panduan tentang membuat server HTTPS.

Anda juga harus menambahkan sertifikat yang ditandatangani sendiri kerantai kunci / manajer kredensialOS Anda untuk melewati kebijakan keamanan browser. Anda mungkin masih melihat peringatan di browser setelahnya (misalnya Chrome).

Untuk Windows pengguna, ikuti panduan di sini: Cara: Melihat sertifikat dengan snap-in MMC.
Untuk pengguna Linux dan MacOS, silakan lihat dokumentasi sistem operasi Anda tentang cara menginstal sertifikat.

Warning

Anda mungkin memerlukan hak istimewa administrator untuk menjalankan perintah di atas.

Masalah umum

Dalam beberapa kasus, Anda mungkin menerima kesalahan dari Microsoft Entra ID saat mencoba mengautentikasi menggunakan sertifikat, seperti AADSTS700027: Client assertion contains an invalid signature kesalahan, menunjukkan bahwa sertifikat dan/atau kunci privat yang Anda gunakan untuk menginisialisasi MSAL Node salah bentuk. Salah satu alasan umum untuk hal ini adalah bahwa string sertifikat/kunci privat yang Anda berikan ke MSAL Node mengandung karakter yang tidak diharapkan, seperti carriage return (\r) atau baris baru (\n):

Atau, file sertifikat/kunci Anda mungkin berisi bag attributes:

Bag Attributes
    localKeyID: 28 B5 8E 16 11 88 E9 00 58 D5 76 30 12 B9 59 B8 E4 CE 7C AA
subject=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=alice
issuer=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=Certificate Authority/emailAddress=ca@example.com\n
-----BEGIN CERTIFICATE-----
MIIDDzCCAfegAwIBAgIJAMkyzQVK88NHMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYD
VQQGEwJTRTESMBAGA1UECBMJU3RvY2tob2xtMQ4wDAYDVQQHEwVLaXN0YTEQMA4G
0fbkqbKulrchGbNgkankZtEVg4PGjo+Y8MdMjtfSZB29hwYvfMX09jzJ68ZqmpYQ
njvcVtLbEZN5OGCkaslb/f2OxLbsUNgIbws538WnaaufDvKmQe2kUdWmpl9Wn9Bf
bZq7B+njvcVa7SsWF/WLq5AUbw==
-----END CERTIFICATE-----

Dalam kasus seperti itu, Anda bertanggung jawab untuk membersihkan string sebelum meneruskannya ke konfigurasi MSAL Node. Contohnya:

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

const privateKeySource = fs.readFileSync('<path_to_key>/certs/example.key');
const privateKey = Buffer.from(privateKeySource, 'base64').toString().replace(/\r/g, "").replace(/\n/g, "");

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-02