Mulai cepat: Pustaka klien kunci Azure Key Vault untuk JavaScript

Artikel
10/05/2024

Mulailah dengan pustaka klien kunci Azure Key Vault untuk JavaScript. Azure Key Vault adalah layanan awan yang menyediakan penyimpanan aman untuk menyimpan rahasia. Anda dapat menyimpan kunci, kata sandi, sertifikat, dan rahasia lainnya dengan aman. Brankas kunci Azure dapat dibuat dan dikelola melalui portal Microsoft Azure. Dalam mulai cepat ini, Anda mempelajari cara membuat, mengambil, dan menghapus kunci dari brankas kunci Azure menggunakan pustaka klien kunci JavaScript.

Sumber daya pustaka klien Key Vault:

Dokumentasi referensi API | Kode sumber pustaka | Paket (npm)

Untuk informasi lebih lanjut tentang Key Vault dan kunci, lihat:

Prasyarat

Langganan Azure - membuat secara gratis.
Node.js LTS saat ini.
Azure CLI
Key Vault yang ada - Anda dapat membuatnya menggunakan:

Langganan Azure - membuat secara gratis.
Node.js LTS saat ini.
TypeScript 5+
Azure CLI.
Key Vault yang ada - Anda dapat membuatnya menggunakan:

Mulai cepat ini mengasumsikan Anda menjalankan Azure CLI.

Jalankan perintah login.
```
az login
```
Jika CLI dapat membuka browser default Anda, CLI akan melakukannya dan memuat halaman masuk Azure.

Jika tidak, buka halaman browser di https://aka.ms/devicelogin dan masukkan kode otorisasi yang ditampilkan di terminal Anda.
Masuk menggunakan kredensial akun Anda di browser.

Membuat aplikasi Node.js baru

Buat aplikasi Node.js yang menggunakan brankas kunci Anda.

Di terminal, buat folder bernama key-vault-node-app dan ubah ke folder itu:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Buat proyek Node.js baru:
```
npm init -y
```

Instal paket Key Vault

Menggunakan terminal, instal pustaka klien rahasia Azure Key Vault, @azure/keyvault-keys untuk Node.js.
```
npm install @azure/keyvault-keys
```
Instal pustaka klien Azure Identity, @azure/paket identitas untuk mengautentikasi ke Key Vault.
```
npm install @azure/identity
```

Memberikan akses ke brankas kunci Anda

Untuk mendapatkan izin ke brankas kunci Anda melalui Kontrol Akses Berbasis Peran (RBAC), tetapkan peran ke "Nama Prinsipal Pengguna" (UPN) Anda menggunakan perintah Azure CLI az role assignment create.

az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Ganti <upn>, <subscription-id>, <resource-group-name> , dan <your-unique-keyvault-name> dengan nilai aktual Anda. UPN Anda biasanya akan dalam format alamat email (misalnya, username@domain.com).

Atur variabel lingkungan

Aplikasi ini menggunakan titik akhir brankas kunci sebagai variabel lingkungan yang disebut KEY_VAULT_URL.

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

Mengautentikasi dan membuat klien

Permintaan aplikasi ke sebagian besar layanan Azure harus diotorisasi. Menggunakan metode DefaultAzureCredential yang disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan.

Dalam mulai cepat ini, DefaultAzureCredential autentikasi ke brankas kunci menggunakan kredensial pengguna pengembangan lokal yang masuk ke Azure CLI. Saat aplikasi disebarkan ke Azure, kode yang sama DefaultAzureCredential dapat secara otomatis menemukan dan menggunakan identitas terkelola yang ditetapkan ke App Service, Komputer Virtual, atau layanan lainnya. Untuk informasi selengkapnya, lihat Gambaran Umum Identitas Terkelola.

Dalam kode ini, titik akhir brankas kunci Anda digunakan untuk membuat klien brankas kunci. Format titik akhir terlihat seperti https://<your-key-vault-name>.vault.azure.net tetapi dapat berubah untuk sovereign cloud. Untuk informasi selengkapnya tentang mengautentikasi ke brankas kunci, lihat Panduan Pengembang.

Contoh kode

Sampel kode di bawah ini akan memperlihatkan cara membuat klien, mengatur rahasia, menampilkan rahasia, dan menghapus rahasia.

Kode ini menggunakan kelas dan metode Rahasia Key Vault berikut:

Menyiapkan kerangka kerja aplikasi

Buat file teks baru dan tempel kode berikut ke file index.js.

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

async function main() {

    // DefaultAzureCredential expects the following three environment variables:
    // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
    // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
    // - AZURE_CLIENT_SECRET: The client secret for the registered application
    const credential = new DefaultAzureCredential();

    const keyVaultUrl = process.env["KEY_VAULT_URL"];
    if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

    const client = new KeyClient(keyVaultUrl, credential);

    const uniqueString = Date.now();
    const keyName = `sample-key-${uniqueString}`;
    const ecKeyName = `sample-ec-key-${uniqueString}`;
    const rsaKeyName = `sample-rsa-key-${uniqueString}`;

    // Create key using the general method
    const result = await client.createKey(keyName, "EC");
    console.log("key: ", result);

    // Create key using specialized key creation methods
    const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
    const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
    console.log("Elliptic curve key: ", ecResult);
    console.log("RSA Key: ", rsaResult);

    // Get a specific key
    const key = await client.getKey(keyName);
    console.log("key: ", key);

    // Or list the keys we have
    for await (const keyProperties of client.listPropertiesOfKeys()) {
    const key = await client.getKey(keyProperties.name);
    console.log("key: ", key);
    }

    // Update the key
    const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
    enabled: false
    });
    console.log("updated key: ", updatedKey);

    // Delete the key - the key is soft-deleted but not yet purged
    const deletePoller = await client.beginDeleteKey(keyName);
    await deletePoller.pollUntilDone();

    const deletedKey = await client.getDeletedKey(keyName);
    console.log("deleted key: ", deletedKey);

    // Purge the key - the key is permanently deleted
    // This operation could take some time to complete
    console.time("purge a single key");
    await client.purgeDeletedKey(keyName);
    console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Jalankan aplikasi sampel

Jalankan aplikasi:
```
node index.js
```

Metode buat dan dapatkan menghasilkan objek JSON lengkap untuk kunci:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

Buat file teks baru dan tempelkan kode berikut ke dalam file index.ts .

import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
} from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printKey(keyVaultKey: KeyVaultKey): void {
  const { name, key, id, keyType, keyOperations, properties } = keyVaultKey;
  console.log("Key: ", { name, key, id, keyType });

  const { vaultUrl, version, enabled, expiresOn }: KeyProperties = properties;
  console.log("Key Properties: ", { vaultUrl, version, enabled, expiresOn });

  console.log("Key Operations: ", keyOperations.join(", "));
}

async function main(): Promise<void> {
  // Create a new KeyClient
  const client = new KeyClient(keyVaultUrl, credential);

  // Create unique key names
  const uniqueString = Date.now().toString();
  const keyName = `sample-key-${uniqueString}`;
  const ecKeyName = `sample-ec-key-${uniqueString}`;
  const rsaKeyName = `sample-rsa-key-${uniqueString}`;

  // Create a EC key
  const ecKey = await client.createKey(keyName, "EC");
  printKey(ecKey);

  // Elliptic curve key
  const ec256Key = await client.createEcKey(ecKeyName, {
    curve: "P-256",
  });
  printKey(ec256Key);

  // RSA key
  const rsa2048Key = await client.createRsaKey(rsaKeyName, {
    keySize: 2048,
  });
  printKey(rsa2048Key);

  // Get a key
  const key = await client.getKey(keyName);
  printKey(key);

  // Get properties of all keys
  for await (const keyProperties of client.listPropertiesOfKeys()) {
    const iteratedKey = await client.getKey(keyProperties.name);
    printKey(iteratedKey);
  }

  // Update key properties - disable key
  const updatedKey = await client.updateKeyProperties(
    keyName,
    ecKey.properties.version,
    {
      enabled: false,
    }
  );
  printKey(updatedKey);

  // Delete key (without immediate purge)
  const deletePoller = await client.beginDeleteKey(keyName);
  await deletePoller.pollUntilDone();

  // Get a deleted key
  const deletedKey = await client.getDeletedKey(keyName);
  console.log("deleted key: ", deletedKey.name);

  // Purge a deleted key
  console.time("purge a single key");
  await client.purgeDeletedKey(keyName);
  console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Jalankan aplikasi sampel

Buat aplikasi TypeScript:
```
tsc
```
Jalankan aplikasi:
```
node index.js
```

Metode buat dan dapatkan menghasilkan objek JSON lengkap untuk kunci:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

Mengintegrasikan dengan App Configuration

SDK Azure menyediakan metode pembantu, parseKeyVaultKeyIdentifier, untuk mengurai ID Kunci Key Vault yang diberikan. Ini diperlukan jika Anda menggunakan referensi App Configuration ke Key Vault. App Configuration menyimpan ID Kunci Key Vault. Anda memerlukan metode parseKeyVaultKeyIdentifier untuk menguraikan ID tersebut agar mendapatkan nama kunci. Setelah mendapatkan nama kunci, Anda dapat memperoleh nilai kunci saat ini menggunakan kode dari mulai cepat ini.

Langkah berikutnya

Dalam mulai cepat ini, Anda akan membuat brankas kunci, menyimpan rahasia, dan menampilkan rahasia tersebut. Untuk mempelajari lebih lanjut tentang Key Vault dan cara mengintegrasikannya dengan aplikasi Anda, lanjutkan ke artikel ini.

Baca Gambaran Umum Azure Key Vault
Baca Gambaran Umum Kunci Azure Key Vault
Cara Mengamankan akses ke brankas kunci
Lihat Panduan pengembang Azure Key Vault
Tinjau Ringkasan keamanan Azure Key Vault

Bagikan melalui

Mulai cepat: Pustaka klien kunci Azure Key Vault untuk JavaScript

Prasyarat

Membuat aplikasi Node.js baru

Instal paket Key Vault

Memberikan akses ke brankas kunci Anda

Atur variabel lingkungan

Mengautentikasi dan membuat klien

Contoh kode

Menyiapkan kerangka kerja aplikasi

Jalankan aplikasi sampel

Jalankan aplikasi sampel

Mengintegrasikan dengan App Configuration

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mulai cepat: Pustaka klien kunci Azure Key Vault untuk JavaScript

Prasyarat

Masuk ke Azure

Membuat aplikasi Node.js baru

Instal paket Key Vault

Memberikan akses ke brankas kunci Anda

Atur variabel lingkungan

Mengautentikasi dan membuat klien

Contoh kode

Menyiapkan kerangka kerja aplikasi

Jalankan aplikasi sampel

Jalankan aplikasi sampel

Mengintegrasikan dengan App Configuration

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: