Pustaka klien Azure Key Vault Certificates untuk JavaScript - versi 4.8.0

  • Artikel

Azure Key Vault adalah layanan cloud yang menyediakan penyimpanan aman dan manajemen sertifikat otomatis yang digunakan di seluruh aplikasi cloud. Beberapa sertifikat, dan beberapa versi sertifikat yang sama, dapat disimpan di Key Vault Azure. Setiap sertifikat dalam brankas memiliki kebijakan yang terkait dengannya yang mengontrol penerbitan dan masa pakai sertifikat, bersama dengan tindakan yang akan diambil sebagai sertifikat mendekati kedaluwarsa.

Jika Anda ingin mengetahui selengkapnya tentang Azure Key Vault, Anda mungkin ingin meninjau: Apa itu Azure Key Vault?

Gunakan pustaka klien untuk Sertifikat Key Vault Azure di aplikasi Node.js Anda untuk:

  • Mendapatkan, mengatur, dan menghapus sertifikat.
  • Memperbarui sertifikat, atribut, penerbit, kebijakan, operasi, dan kontaknya.
  • Cadangkan dan pulihkan sertifikat.
  • Dapatkan, hapus menyeluruh, atau pulihkan sertifikat yang dihapus.
  • Dapatkan semua versi sertifikat.
  • Dapatkan semua sertifikat.
  • Dapatkan semua sertifikat yang dihapus.

Catatan: Paket ini tidak dapat digunakan di browser karena keterbatasan layanan Azure Key Vault, silakan lihat dokumen ini untuk panduan.

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Instal paketnya

Menginstal pustaka klien Azure Key Vault Certificates menggunakan npm

npm install @azure/keyvault-certificates

Menginstal pustaka identitas

Key Vault klien mengautentikasi menggunakan Pustaka Identitas Azure. Instal juga menggunakan npm

npm install @azure/identity

Mengonfigurasi TypeScript

Pengguna TypeScript harus menginstal definisi jenis Node:

npm install @types/node

Anda juga perlu mengaktifkan compilerOptions.allowSyntheticDefaultImports di tsconfig.json Anda. Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default. Lihat buku pegangan opsi pengkompilasi TypeScript untuk informasi selengkapnya.

Mengautentikasi dengan Azure Active Directory

Layanan Key Vault bergantung pada Azure Active Directory untuk mengautentikasi permintaan ke API-nya. Paket ini @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. README untuk @azure/identity memberikan detail dan sampel lebih lanjut untuk memulai.

Untuk berinteraksi dengan layanan Azure Key Vault, Anda harus membuat instans CertificateClient kelas, url vault, dan objek kredensial. Contoh yang ditunjukkan dalam dokumen ini menggunakan objek kredensial bernama DefaultAzureCredential, yang sesuai untuk sebagian besar skenario, termasuk lingkungan pengembangan dan produksi lokal. Selain itu, sebaiknya gunakan identitas terkelola untuk autentikasi di lingkungan produksi.

Anda dapat menemukan informasi selengkapnya tentang berbagai cara mengautentikasi dan jenis kredensial terkait dalam dokumentasi Azure Identity.

Berikut adalah contoh singkatnya. Pertama, impor DefaultAzureCredential dan CertificateClient:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

Setelah ini diimpor, kita selanjutnya dapat terhubung ke layanan brankas kunci:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our certificates client and connect to the service
const client = new CertificateClient(url, credential);

Konsep utama

  • Klien Sertifikat adalah antarmuka utama untuk berinteraksi dengan metode API yang terkait dengan sertifikat di Azure Key Vault API dari aplikasi JavaScript. Setelah diinisialisasi, ini menyediakan serangkaian metode dasar yang dapat digunakan untuk membuat, membaca, memperbarui, dan menghapus sertifikat.
  • Versi Sertifikat adalah versi sertifikat dalam Key Vault. Setiap kali pengguna menetapkan nilai ke nama sertifikat unik, versi baru sertifikat tersebut dibuat. Mengambil sertifikat dengan nama akan selalu mengembalikan nilai terbaru yang ditetapkan, kecuali versi tertentu disediakan untuk kueri.
  • Penghapusan sementara memungkinkan Key Vault mendukung penghapusan dan pembersihan sebagai dua langkah terpisah, sehingga sertifikat yang dihapus tidak segera hilang. Ini hanya terjadi jika Key Vault mengaktifkan penghapusan sementara.
  • Cadangan Sertifikat dapat dihasilkan dari sertifikat yang dibuat. Cadangan ini datang sebagai data biner, dan hanya dapat digunakan untuk meregenerasi sertifikat yang dihapus sebelumnya.

Menentukan versi API layanan Azure Key Vault

Secara default, paket ini menggunakan versi layanan Azure Key Vault terbaru yaitu 7.1. Satu-satunya versi lain yang didukung adalah 7.0. Anda dapat mengubah versi layanan yang digunakan dengan mengatur opsi serviceVersion di konstruktor klien seperti yang ditunjukkan di bawah ini:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

Contoh

Bagian berikut ini menyediakan cuplikan kode yang mencakup beberapa tugas umum menggunakan Sertifikat azure Key Vault. Skenario yang dibahas di sini terdiri dari:

Membuat dan mengatur sertifikat

beginCreateCertificatemembuat sertifikat untuk disimpan di Key Vault Azure. Jika sertifikat dengan nama yang sama sudah ada, versi baru sertifikat akan dibuat.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Selain nama sertifikat dan kebijakan, Anda juga bisa meneruskan properti berikut dalam argumen ketiga dengan nilai opsional:

  • enabled: Nilai boolean yang menentukan apakah sertifikat dapat digunakan atau tidak.
  • tags: Setiap set nilai kunci yang dapat digunakan untuk mencari dan memfilter sertifikat.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

Memanggil ke beginCreateCertificate dengan nama yang sama akan membuat versi baru dari sertifikat yang sama, yang akan memiliki atribut terbaru yang disediakan.

Karena Sertifikat membutuhkan waktu untuk sepenuhnya dibuat, beginCreateCertificate mengembalikan objek poller yang melacak Operasi Jangka Panjang yang mendasar sesuai dengan pedoman kami: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Poller yang diterima akan memungkinkan Anda untuk mendapatkan sertifikat yang dibuat dengan memanggil ke poller.getResult(). Anda juga dapat menunggu hingga penghapusan selesai, baik dengan menjalankan panggilan layanan individual hingga sertifikat dibuat, atau dengan menunggu hingga proses selesai:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

Cara lain untuk menunggu hingga sertifikat ditandatangani adalah dengan melakukan panggilan individual, sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const { delay } = require("@azure/core-util");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

Mendapatkan sertifikat Key Vault

Cara paling sederhana untuk membaca sertifikat kembali dari vault adalah dengan mendapatkan sertifikat berdasarkan nama. getCertificate akan mengambil versi terbaru sertifikat, bersama dengan kebijakan sertifikat. Anda bisa secara opsional mendapatkan versi sertifikat yang berbeda dengan memanggil getCertificateVersion jika Anda menentukan versinya. getCertificateVersion tidak mengembalikan kebijakan sertifikat.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

Mendapatkan informasi lengkap sertifikat

Desain Azure Key Vault membuat perbedaan yang tajam antara Kunci, Rahasia, dan Sertifikat. Fitur Sertifikat layanan Key Vault dirancang untuk memanfaatkan kemampuan Kunci dan Rahasianya. Mari kita evaluasi komposisi Sertifikat Key Vault:

Ketika sertifikat Vault Kunci dibuat, kunci dan rahasia yang dapat diatasi juga dibuat dengan nama yang sama. Kunci Key Vault memungkinkan operasi kunci, dan rahasia Key Vault memungkinkan pengambilan nilai sertifikat sebagai rahasia. Sertifikat Key Vault juga berisi metadata sertifikat x509 publik. Sumber: Komposisi Sertifikat.

Mengetahui bahwa kunci privat disimpan dalam Rahasia Key Vault, dengan sertifikat publik disertakan, kita dapat mengambilnya dengan menggunakan klien rahasia Key Vault.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

Perhatikan bahwa, secara default, jenis konten sertifikat adalah PKCS 12. Dengan menentukan jenis konten sertifikat Anda, Anda akan dapat mengambilnya dalam format PEM. Sebelum menunjukkan cara membuat sertifikat PEM, mari kita jelajahi terlebih dahulu cara mengambil kunci rahasia PEM dari sertifikat PKCS 12 terlebih dahulu.

Menggunakan openssl, Anda dapat mengambil sertifikat publik dalam format PEM dengan menggunakan perintah berikut:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

Anda juga dapat menggunakan openssl untuk mengambil kunci privat, sebagai berikut:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Perhatikan bahwa dalam kedua kasus, openssl akan meminta kata sandi yang digunakan untuk membuat sertifikat. Kode sampel yang kami gunakan sejauh ini belum menentukan kata sandi, sehingga Anda dapat menambahkan -passin 'pass:' ke akhir setiap perintah.

Sertifikat dalam format PEM

Jika Anda ingin bekerja dengan sertifikat dalam format PEM, Anda dapat memberi tahu layanan Key Vault Azure untuk membuat dan mengelola sertifikat Anda dalam format PEM dengan menyediakan contentType properti pada saat membuat sertifikat.

Contoh berikut menunjukkan cara membuat dan mengambil bagian publik dan privat dari sertifikat berformat PEM menggunakan klien Key Vault untuk Sertifikat dan Rahasia:

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Perlu diingat bahwa sertifikat publik Anda akan berada dalam blob konten yang sama dengan kunci privat Anda. Anda dapat menggunakan header PEM untuk mengekstraknya dengan sesuai.

Mencantumkan semua sertifikat

listPropertiesOfCertificatesakan mencantumkan semua sertifikat dalam Key Vault.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Memperbarui sertifikat

Atribut sertifikat dapat diperbarui ke versi sertifikat yang ada dengan updateCertificate, sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

Kebijakan sertifikat juga dapat diperbarui satu per satu dengan updateCertificatePolicy, sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Menghapus sertifikat

Metode beginDeleteCertificate ini mengatur sertifikat untuk dihapus. Proses ini akan terjadi di latar belakang segera setelah sumber daya yang diperlukan tersedia.

Jika penghapusan sementara diaktifkan untuk Key Vault, operasi ini hanya akan memberi label sertifikat sebagai sertifikat yang dihapus. Sertifikat yang dihapus tidak dapat diperbarui. Mereka hanya dapat dibaca, dipulihkan, atau dibersihkan.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

  // You can use the deleted certificate immediately:
  const deletedCertificate = poller.getResult();

  // The certificate is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

Karena penghapusan sertifikat tidak akan terjadi secara instan, beberapa waktu diperlukan setelah beginDeleteCertificate metode dipanggil sebelum sertifikat yang dihapus tersedia untuk dibaca, dipulihkan, atau dihapus menyeluruh.

Iterasi daftar sertifikat

Dengan menggunakan CertificateClient, Anda dapat mengambil dan melakukan iterasi melalui semua sertifikat di Vault Sertifikat, serta melalui semua sertifikat yang dihapus dan versi sertifikat tertentu. Metode API berikut tersedia:

  • listPropertiesOfCertificates akan mencantumkan semua sertifikat Anda yang tidak dihapus berdasarkan namanya, hanya pada versi terbarunya.
  • listDeletedCertificates akan mencantumkan semua sertifikat Anda yang dihapus berdasarkan namanya, hanya pada versi terbarunya.
  • listPropertiesOfCertificateVersions akan mencantumkan semua versi sertifikat berdasarkan nama sertifikat.

Yang dapat digunakan sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Semua metode ini akan mengembalikan semua hasil yang tersedia sekaligus. Untuk mengambilnya berdasarkan halaman, tambahkan .byPage() tepat setelah memanggil metode API yang ingin Anda gunakan, sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

Pemecahan Masalah

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Lihat panduan pemecahan masalah kami untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Langkah berikutnya

Anda dapat menemukan lebih banyak sampel kode melalui tautan berikut:

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Tayangan