Aracılığıyla paylaş

JavaScript için Azure Key Vault Gizli istemci kitaplığı - sürüm 4.8.0

  • Makale

Azure Key Vault, güvenli anahtarları kullanarak kimlik doğrulama anahtarlarını, depolama hesabı anahtarlarını, veri şifreleme anahtarlarını, .pfx dosyalarını ve parolaları şifrelemenize olanak tanıyan bir hizmettir. Azure Key Vault hakkında daha fazla bilgi edinmek isterseniz şunları gözden geçirebilirsiniz: Azure Key Vault nedir?

Azure Key Vault Gizli Dizileri yönetimi belirteçleri, parolaları, sertifikaları, API anahtarlarını ve diğer gizli dizileri güvenli bir şekilde depolamanıza ve erişimi sıkı bir şekilde denetlemenize olanak tanır.

Node.js uygulamanızda Azure Key Vault Gizli Dizileri için istemci kitaplığını kullanarak:

  • Gizli dizileri alın, ayarlayın ve silin.
  • Gizli diziyi ve özniteliklerini güncelleştirin.
  • Gizli diziyi yedekleme ve geri yükleme.
  • Silinen bir gizli diziyi alın, silin veya kurtarın.
  • Bir gizli dizinin tüm sürümlerini alın.
  • Tüm sırları al.
  • Silinen tüm gizli dizileri alın.

Not: Azure Key Vault hizmet sınırlamaları nedeniyle bu paket tarayıcıda kullanılamıyor, rehberlik için lütfen bu belgeye bakın.

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

Paketi yükleme

npm kullanarak Azure Key Vault Gizli anahtarı istemci kitaplığını yükleyin:

npm install @azure/keyvault-secrets

Kimlik kitaplığını yükleme

Key Vault istemcileri Azure Kimlik Kitaplığı'nı kullanarak kimlik doğrulaması yapar. Npm kullanarak da yükleyin

npm install @azure/identity

TypeScript'i yapılandırma

TypeScript kullanıcılarının Düğüm türü tanımlarının yüklü olması gerekir:

npm install @types/node

ayrıca tsconfig.json etkinleştirmeniz compilerOptions.allowSyntheticDefaultImports gerekir. seçeneğini etkinleştirdiyseniz compilerOptions.esModuleInteropallowSyntheticDefaultImports varsayılan olarak etkin olduğunu unutmayın. Daha fazla bilgi için bkz. TypeScript'in derleyici seçenekleri el kitabı .

Önemli kavramlar

  • Gizli dizi istemcisi, JavaScript uygulamasından Azure Key Vault API'sindeki gizli dizilerle ilgili API yöntemleriyle etkileşime geçmek için kullanılan birincil arabirimdir. Başlatıldıktan sonra, gizli dizileri oluşturmak, okumak, güncelleştirmek ve silmek için kullanılabilecek temel bir yöntem kümesi sağlar.
  • Gizli dizi sürümü, Key Vault bir gizli dizinin sürümüdür. Kullanıcı benzersiz bir gizli dizi adına her değer atayışında, bu gizli dizinin yeni bir sürümü oluşturulur. Sorguya belirli bir sürüm sağlanmadığı sürece, gizli diziyi bir adla almak her zaman atanan en son değeri döndürür.
  • Geçici silme , Key Vault'ların silmeyi ve temizlemeyi iki ayrı adım olarak desteklemesini sağlar, bu nedenle silinen gizli diziler hemen kaybolmaz. Bu yalnızca Key Vault geçici silme etkinleştirildiğinde gerçekleşir.
  • Oluşturulan herhangi bir gizli diziden gizli dizi yedeklemesi oluşturulabilir. Bu yedeklemeler ikili veri olarak gelir ve yalnızca önceden silinmiş bir gizli diziyi yeniden oluşturmak için kullanılabilir.

Azure Active Directory ile kimlik doğrulaması

Key Vault hizmeti, API'lerinde isteklerin kimliğini doğrulamak için Azure Active Directory'ye dayanır. Paket, @azure/identity uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgileri türleri sağlar. için README, başlamanız için @azure/identity daha fazla ayrıntı ve örnek sağlar.

Azure Key Vault hizmetiyle etkileşim kurmak için sınıfının bir örneğini, bir kasa URL'siniSecretClient ve kimlik bilgisi nesnesini oluşturmanız gerekir. Bu belgede gösterilen örneklerde, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan adlı DefaultAzureCredentialbir kimlik bilgisi nesnesi kullanılır. Ayrıca, üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz.

Farklı kimlik doğrulama yöntemleri ve bunların ilgili kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimliği belgelerinde bulabilirsiniz.

Aşağıda hızlı bir örnek verilmiştir. İlk olarak, içeri aktar DefaultAzureCredential ve SecretClient:

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

Bunlar içeri aktarıldıktan sonra Key Vault hizmetine bağlanabiliriz:

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

Azure Key Vault hizmet API'sinin sürümünü belirtme

Varsayılan olarak, bu paket en son Azure Key Vault hizmeti sürümünü kullanır.7.1 Desteklenen diğer sürüm yalnızca sürümüdür 7.0. Aşağıda gösterildiği gibi istemci oluşturucusunda seçeneğini serviceVersion ayarlayarak kullanılan hizmet sürümünü değiştirebilirsiniz:

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

Örnekler

Aşağıdaki bölümler, Azure Key Vault Gizli Dizileri'ni kullanarak bazı yaygın görevleri kapsayan kod parçacıkları sağlar. Burada ele alınan senaryolar şunlardan oluşur:

Gizli dizi oluşturma ve ayarlama

setSecret belirtilen gizli dizi adına sağlanan bir değer atar. Aynı ada sahip bir gizli dizi zaten varsa, gizli dizinin yeni bir sürümü oluşturulur.

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

Gizli dizi alma

Kasadan gizli dizileri okumanın en basit yolu, adıyla gizli dizi almaktır. Bu işlem gizli dizinin en son sürümünü alır. İsteğe bağlı parametrelerin bir parçası olarak belirtirseniz isteğe bağlı olarak anahtarın farklı bir sürümünü alabilirsiniz.

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

Özniteliklerle gizli dizi oluşturma ve güncelleştirme

Gizli dizi, adından ve değerinden daha fazla bilgiye sahip olabilir. Ayrıca aşağıdaki öznitelikleri de içerebilir:

  • tags: Gizli dizileri aramak ve filtrelemek için kullanılabilecek herhangi bir anahtar-değer kümesi.
  • contentType: Gizli dizi alıcısının gizli dizi değerinin nasıl kullanılacağını anlamasına yardımcı olmak için kullanılabilecek herhangi bir dize.
  • enabled: Gizli dizi değerinin okunup okunamayacağını belirleyen boole değeri.
  • notBefore: Gizli dizi değerinin alınabildiği belirli bir tarih.
  • expiresOn: Gizli dizi değerinin alınamadığı belirli bir tarih.

Bu özniteliklere sahip bir nesne, gizli dizinin adından ve değerinden hemen sonra üçüncü parametresi setSecretolarak aşağıdaki gibi gönderilebilir:

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

Bu, sağlanan en son özniteliklere sahip olacak aynı gizli dizinin yeni bir sürümünü oluşturur.

Öznitelikler aşağıdaki gibi ile updateSecretPropertiesvar olan bir gizli dizi sürümüne de güncelleştirilebilir:

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

Gizli dizi silme

yöntemi gizli beginDeleteSecret dizi silme işlemini başlatır. Bu işlem, gerekli kaynaklar kullanılabilir duruma gelir gelmez arka planda gerçekleşir.

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

Key Vault geçici silme etkinleştirildiyse, bu işlem gizli diziyi yalnızca silinmiş gizli dizi olarak etiketler. Silinen gizli dizi güncelleştirilemez. Bunlar yalnızca okunabilir, kurtarılabilir veya temizlenebilir.

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

Gizli dizilerin tamamen silinmesi biraz zaman aldığından, beginDeleteSecret yönergelerimize göre temel alınan Uzun Süre Çalışan İşlemi takip eden bir Poller nesnesi döndürür: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Alınan poller, öğesine arayarak silinen gizli diziyi almanıza poller.getResult()olanak sağlar. Ayrıca gizli dizi silinene kadar tek tek hizmet çağrılarını çalıştırarak veya işlem bitene kadar bekleyerek silme işleminin bitmesini de bekleyebilirsiniz:

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

Gizli dizi tamamen silinene kadar beklemenin bir diğer yolu da aşağıdaki gibi tek tek çağrılar yapmaktır:

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

Gizli dizi listelerini yineleme

SecretClient'ı kullanarak, bir Key Vault içindeki tüm gizli dizileri ve silinen tüm gizli dizileri ve belirli bir gizli dizinin sürümlerini alıp yineleyebilirsiniz. Aşağıdaki API yöntemleri kullanılabilir:

  • listPropertiesOfSecrets silinmeyen tüm gizli dizilerinizi yalnızca en son sürümlerinde adlarına göre listeler.
  • listDeletedSecrets silinen tüm gizli dizilerinizi yalnızca en son sürümlerinde adlarına göre listeler.
  • listPropertiesOfSecretVersions gizli dizinin tüm sürümlerini gizli dizi adına göre listeler.

Aşağıdaki gibi kullanılabilir:

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

Bu yöntemlerin tümü tüm kullanılabilir sonuçları aynı anda döndürür. Bunları sayfalara göre almak için, kullanmak istediğiniz API yöntemini çağırdıktan hemen sonra aşağıdaki gibi ekleyin .byPage() :

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

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzumuza bakın.

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Sonraki adımlar

Aşağıdaki bağlantılardan daha fazla kod örneği bulabilirsiniz:

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

İzlenimler