Pustaka klien Rahasia Azure Key Vault untuk JavaScript - versi 4.8.0

Artikel
02/16/2024

Azure Key Vault adalah layanan yang memungkinkan Anda mengenkripsi kunci autentikasi, kunci akun penyimpanan, kunci enkripsi data, file .pfx, dan kata sandi dengan menggunakan kunci aman. Jika Anda ingin mengetahui selengkapnya tentang Azure Key Vault, Anda mungkin ingin meninjau: Apa itu Azure Key Vault?

Manajemen Rahasia Azure Key Vault memungkinkan Anda menyimpan dan mengontrol akses ke token, kata sandi, sertifikat, kunci API, dan rahasia lainnya dengan aman.

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

Dapatkan, atur, dan hapus rahasia.
Perbarui rahasia dan atributnya.
Cadangkan dan pulihkan rahasia.
Dapatkan, hapus menyeluruh, atau pulihkan rahasia yang dihapus.
Dapatkan semua versi rahasia.
Dapatkan semua rahasia.
Dapatkan semua rahasia 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

Versi LTS dari Node.js

Prasyarat

Langganan Azure
Sumber daya Key Vault
Azure Key Vault yang sudah ada. Jika Anda perlu membuat brankas kunci, Anda dapat melakukannya di Portal Microsoft Azure dengan mengikuti langkah-langkah dalam dokumen ini. Atau, Anda dapat menggunakan Azure CLI dengan mengikuti langkah-langkah dalam dokumen ini.

Instal paketnya

Instal pustaka klien Rahasia Azure Key Vault menggunakan npm:

npm install @azure/keyvault-secrets

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.

Konsep utama

Klien Rahasia adalah antarmuka utama untuk berinteraksi dengan metode API yang terkait dengan rahasia di Azure Key Vault API dari aplikasi JavaScript. Setelah diinisialisasi, ini menyediakan serangkaian metode dasar yang dapat digunakan untuk membuat, membaca, memperbarui, dan menghapus rahasia.
Versi Rahasia adalah versi rahasia dalam Key Vault. Setiap kali pengguna menetapkan nilai ke nama rahasia unik, versi baru rahasia tersebut dibuat. Mengambil rahasia 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 rahasia yang dihapus tidak segera hilang. Ini hanya terjadi jika Key Vault mengaktifkan penghapusan sementara.
Cadangan Rahasia dapat dihasilkan dari rahasia apa pun yang dibuat. Cadangan ini datang sebagai data biner, dan hanya dapat digunakan untuk meregenerasi rahasia yang dihapus sebelumnya.

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 Anda.

Untuk berinteraksi dengan layanan Azure Key Vault, Anda harus membuat instans SecretClient 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 SecretClient:

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

Setelah ini diimpor, kita selanjutnya dapat terhubung ke layanan Key Vault:

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

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 secrets client and connect to the service
const client = new SecretClient(url, credential);

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 { SecretClient } = require("@azure/keyvault-secrets");

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 SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Contoh

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

Membuat dan mengatur rahasia.
Mendapatkan rahasia.
Membuat dan memperbarui rahasia dengan atribut.
Menghapus rahasia.
Iterasi daftar rahasia.

Membuat dan mengatur rahasia

setSecret menetapkan nilai yang disediakan ke nama rahasia yang ditentukan. Jika rahasia dengan nama yang sama sudah ada, maka versi baru rahasia akan dibuat.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Mendapatkan rahasia

Cara paling sederhana untuk membaca rahasia kembali dari brankas adalah dengan mendapatkan rahasia berdasarkan nama. Ini akan mengambil versi terbaru dari rahasia. Anda bisa secara opsional mendapatkan versi kunci yang berbeda jika Anda menentukannya sebagai bagian dari parameter opsional.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Membuat dan memperbarui rahasia dengan atribut

Rahasia dapat memiliki lebih banyak informasi daripada namanya dan nilainya. Mereka juga dapat menyertakan atribut berikut:

tags: Setiap set kunci-nilai yang dapat digunakan untuk mencari dan memfilter rahasia.
contentType: String apa pun yang dapat digunakan untuk membantu penerima rahasia memahami cara menggunakan nilai rahasia.
enabled: Nilai boolean yang menentukan apakah nilai rahasia dapat dibaca atau tidak.
notBefore: Tanggal tertentu setelah nilai rahasia dapat diambil.
expiresOn: Tanggal tertentu setelah itu nilai rahasia tidak dapat diambil.

Objek dengan atribut ini dapat dikirim sebagai parameter ketiga dari setSecret, tepat setelah nama dan nilai rahasia, sebagai berikut:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

Ini akan membuat versi baru dari rahasia yang sama, yang akan memiliki atribut terbaru yang disediakan.

Atribut juga dapat diperbarui ke versi rahasia yang ada dengan updateSecretProperties, sebagai berikut:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Menghapus rahasia

Metode beginDeleteSecret memulai penghapusan Rahasia. Proses ini akan terjadi di latar belakang segera setelah sumber daya yang diperlukan tersedia.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

  // The secret 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 secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Karena Rahasia membutuhkan waktu untuk dihapus sepenuhnya, beginDeleteSecret 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 rahasia yang dihapus dengan memanggil ke poller.getResult(). Anda juga dapat menunggu hingga penghapusan selesai, baik dengan menjalankan panggilan layanan individual hingga rahasia dihapus, atau dengan menunggu hingga proses selesai:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Cara lain untuk menunggu sampai rahasia sepenuhnya dihapus adalah dengan melakukan panggilan individual, sebagai berikut:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
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 SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Iterasi daftar rahasia

Dengan menggunakan SecretClient, Anda dapat mengambil dan melakukan iterasi melalui semua rahasia dalam Key Vault, serta melalui semua rahasia yang dihapus dan versi rahasia tertentu. Metode API berikut tersedia:

listPropertiesOfSecrets akan mencantumkan semua rahasia Anda yang tidak dihapus berdasarkan namanya, hanya pada versi terbarunya.
listDeletedSecrets akan mencantumkan semua rahasia Anda yang dihapus berdasarkan namanya, hanya pada versi terbarunya.
listPropertiesOfSecretVersions akan mencantumkan semua versi rahasia berdasarkan nama rahasia.

Yang dapat digunakan sebagai berikut:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

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 { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Pemecahan Masalah

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

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");

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