Bagikan melalui

Pustaka klien Azure Key Vault Secret untuk JavaScript - versi 4.10.0

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 Rahasia Azure Key Vault 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 kunci:

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Prasyarat

Pasang paketnya

Instal pustaka klien Rahasia Azure Key Vault menggunakan npm:

npm install @azure/keyvault-secrets

Menginstal pustaka identitas

Klien Key Vault mengautentikasi menggunakan Azure Identity Library. 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.jsonAnda. Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default. Lihat opsi kompilator TypeScript untuk informasi selengkapnya.

Konsep utama

  • Klien Secret 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 di 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 penghapusan menyeluruh 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 yang dibuat. Cadangan ini berasal 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 @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. README untuk @azure/identity menyediakan detail dan sampel selengkapnya untuk memulai Anda.

Untuk berinteraksi dengan layanan Azure Key Vault, Anda harus membuat instans kelas SecretClient, 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 untuk mengautentikasi dan jenis kredensial yang sesuai dalam dokumentasi Azure Identity.

Berikut adalah contoh singkatnya. Pertama, impor DefaultAzureCredential dan SecretClient. Setelah ini diimpor, kita selanjutnya dapat terhubung ke layanan Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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 keys 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 yang 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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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`;

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

Contoh

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

Mendapatkan rahasia

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Membuat dan memperbarui rahasia dengan atribut

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

  • tags: Sekumpulan 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 nilai rahasia tidak dapat diambil.

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Menghapus rahasia

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

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.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

Iterasi daftar rahasia

Dengan menggunakan SecretClient, Anda dapat mengambil dan melakukan iterasi melalui semua rahasia di 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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Penyelesaian 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 selanjutnya

Anda dapat menemukan lebih banyak sampel kode melalui tautan berikut:

Berpartisipasi

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

  • Last updated on