Aracılığıyla paylaş

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

  • Makale

Azure Key Vault, bir bulut uygulaması genelinde kullanılan sertifikaların güvenli depolama ve otomatik yönetimini sağlayan bir bulut hizmetidir. Birden çok sertifika ve aynı sertifikanın birden çok sürümü Azure Key Vault'ta tutulabilir. Kasadaki her sertifika, sertifikanın verilmesini ve kullanım ömrünü denetleyen ve süresi dolmak üzere olan sertifikalar olarak gerçekleştirilecek eylemlerle ilişkili bir ilkeye sahiptir.

Azure Key Vault hakkında daha fazla bilgi edinmek isterseniz şunları gözden geçirmek isteyebilirsiniz: Azure Key Vault nedir?

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

  • Sertifikayı alın, ayarlayın ve silin.
  • Sertifikayı, özniteliklerini, vereni, ilkeyi, işlemi ve kişileri güncelleştirin.
  • Sertifikayı yedekleme ve geri yükleme.
  • Silinen bir sertifikayı alma, temizleme veya kurtarma.
  • Sertifikanın tüm sürümlerini alın.
  • Tüm sertifikaları alın.
  • Silinen tüm sertifikaları alın.

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

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

  • Node.js LTS sürümleri

Önkoşullar

  • Azure aboneliği
  • Mevcut Azure Key Vault. Anahtar kasası oluşturmanız gerekiyorsa, azure portalda bu belgeyiadımlarını izleyerek bunu yapabilirsiniz. Alternatif olarak,bu adımları izleyerek Azure CLI'yı kullanın.

Paketi yükleme

npm kullanarak Azure Key Vault Sertifikaları istemci kitaplığını yükleme

npm install @azure/keyvault-certificates

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.jsoncompilerOptions.allowSyntheticDefaultImports etkinleştirmeniz gerekir. compilerOptions.esModuleInteropetkinleştirdiyseniz allowSyntheticDefaultImports varsayılan olarak etkin olduğunu unutmayın. Daha fazla bilgi için bkz. TypeScript'in derleyici seçenekleri el kitabı.

Azure Active Directory ile kimlik doğrulaması

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

Azure Key Vault hizmetiyle etkileşim kurmak için CertificateClient sınıfının bir örneğini, kasası url'sini 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 DefaultAzureCredentialadlı bir kimlik bilgisi nesnesi kullanılır. Ayrıca, üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz.

Kimlik doğrulamasının farklı yolları ve bunların ilgili kimlik bilgileri türleri hakkında daha fazla bilgiyiAzure Kimliği belgelerinde bulabilirsiniz.

İşte hızlı bir örnek. İlk olarak, DefaultAzureCredential içeri aktarıp CertificateClient:

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

Bunlar içeri aktarıldıktan sonra anahtar kasası hizmetine bağlanabiliriz:

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

Temel kavramlar

  • Sertifikalar istemcisi, JavaScript uygulamasından Azure Key Vault API'sindeki sertifikalarla ilgili API yöntemleriyle etkileşime geçmek için kullanılan birincil arabirimdir. Başlatıldıktan sonra, sertifikaları oluşturmak, okumak, güncelleştirmek ve silmek için kullanılabilecek temel bir yöntem kümesi sağlar.
  • Sertifika sürümü, Key Vault'taki bir sertifikanın sürümüdür. Kullanıcı benzersiz bir sertifika adına her değer atayışında, bu sertifikanın yeni bir sürümü oluşturulur. Sertifikayı bir ada göre almak, sorguya belirli bir sürüm sağlanmadığı sürece her zaman atanan en son değeri döndürür.
  • geçici silme Key Vault'ların silme ve temizlemeyi iki ayrı adım olarak desteklemesine olanak tanır, bu nedenle silinen sertifikalar hemen kaybolmaz. Bu durum yalnızca Key Vault geçici silme etkin olduğunda gerçekleşir.
  • Oluşturulan herhangi bir sertifikadan Sertifika yedekleme oluşturulabilir. Bu yedeklemeler ikili veri olarak gelir ve yalnızca daha önce silinmiş bir sertifikayı yeniden oluşturmak için kullanılabilir.

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

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

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

Örnekler

Aşağıdaki bölümlerde, Azure Key Vault Sertifikalarını kullanarak bazı yaygın görevleri kapsayan kod parçacıkları sağlanır. Burada ele alınan senaryolar şunlardan oluşur:

  • sertifika oluşturma ve ayarlama.
  • Key Vault sertifikası alma .
  • bir sertifikanın tüm bilgilerini alma.
  • PEM biçimindeki Sertifikaları.
  • tüm sertifikaları listeleyin.
  • bir sertifikayı güncelleştirme .
  • sertifika silme.
  • sertifika listelerini yinelemeyi .

Sertifika oluşturma ve ayarlama

beginCreateCertificate, Azure Key Vault'ta depolanacak bir sertifika oluşturur. Aynı ada sahip bir sertifika zaten varsa, sertifikanın yeni bir sürümü oluşturulur.

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

Sertifikanın ve ilkenin adının yanı sıra, aşağıdaki özellikleri isteğe bağlı değerlerle üçüncü bir bağımsız değişkene de geçirebilirsiniz:

  • enabled: Sertifikanın kullanılıp kullanılamayacağını belirleyen boole değeri.
  • tags: Sertifikaları aramak ve filtrelemek için kullanılabilecek herhangi bir anahtar-değer kümesi.
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();

Aynı ada sahip beginCreateCertificate çağrılması, aynı sertifikanın yeni bir sürümünü oluşturur ve bu sürüm sağlanan en son özniteliklere sahip olur.

Sertifikaların tam olarak oluşturulması biraz zaman aldığından, beginCreateCertificate temel alınan Uzun Süre Çalışan İşlemi yönergelerimize göre izleyen bir poller nesnesi döndürür: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Alınan poller, poller.getResult()çağrısı yaparak oluşturulan sertifikayı almanıza olanak sağlar. Ayrıca, sertifika oluşturulana kadar tek tek hizmet çağrılarını çalıştırarak veya işlem tamamlanıncaya kadar bekleyerek silme işleminin bitmesini de bekleyebilirsiniz:

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

Sertifika imzalanana kadar beklemenin bir diğer yolu da tek tek çağrıları aşağıdaki gibi yapmaktır:

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

Key Vault sertifikası alma

Sertifikaları kasadan geri okumanın en basit yolu, ada göre bir sertifika almaktır. getCertificate sertifikanın ilkesiyle birlikte sertifikanın en son sürümünü alır. İsteğe bağlı olarak, sürümü belirtirseniz getCertificateVersion çağırarak sertifikanın farklı bir sürümünü alabilirsiniz. getCertificateVersion sertifikanın ilkesini döndürmez.

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

Sertifikanın tüm bilgilerini alma

Azure Key Vault'un tasarımı Anahtarlar, Gizli Diziler ve Sertifikalar arasında net ayrımlar yapar. Key Vault hizmetinin Sertifika özellikleri, Anahtarlar ve Gizli Diziler özelliklerinden yararlanılarak tasarlanmıştır. Şimdi key vault sertifikasının bileşimini değerlendirelim:

Key Vault sertifikası oluşturulduğunda, aynı adla adreslenebilir bir anahtar ve gizli dizi de oluşturulur. Key Vault anahtarı anahtar işlemlerine, Key Vault gizli dizisi ise sertifika değerinin gizli dizi olarak alınmasına olanak tanır. Key Vault sertifikası genel x509 sertifika meta verilerini de içerir. Kaynağı: sertifikaoluşturma.

Özel anahtarın bir Key Vault Gizli Dizisinde depolandığını bilerek, ortak sertifika dahil, Key Vault Gizli Dizileri istemcisini kullanarak bu anahtarı akleyebilirsiniz.

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

Varsayılan olarak sertifikaların içerik türünün PKCS 12 olduğunu unutmayın. Sertifikanızın içerik türünü belirterek PEM biçiminde alabilirsiniz. PEM sertifikalarının nasıl oluşturulacağını göstermeden önce önce BIR PKCS 12 sertifikasından PEM gizli anahtarı almayı inceleyelim.

opensslkullanarak, aşağıdaki komutu kullanarak genel sertifikayı PEM biçiminde alabilirsiniz:

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

Özel anahtarı almak için aşağıdaki gibi openssl de kullanabilirsiniz:

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

Her iki durumda da, openssl'nin sertifikayı oluşturmak için kullanılan parolayı sizden isteyeceğine dikkat edin. Şimdiye kadar kullandığımız örnek kod bir parola belirtmediğinden her komutun sonuna -passin 'pass:' ekleyebilirsiniz.

PEM biçimindeki sertifikalar

Sertifikalarla PEM biçiminde çalışmak istiyorsanız, sertifikaları oluştururken contentType özelliğini sağlayarak Azure Key Vault hizmetine sertifikalarınızı PEM biçiminde oluşturmasını ve yönetmesini söyleyebilirsiniz.

Aşağıdaki örnekte, Sertifikalar ve Gizli Diziler için Key Vault istemcilerini kullanarak PEM biçimli bir sertifikanın genel ve özel bölümlerinin nasıl oluşturulacağı ve alınacağı gösterilmektedir:

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

Ortak sertifikanızın özel anahtarınız ile aynı içerik blobunda olacağını unutmayın. PEM üst bilgilerini uygun şekilde ayıklamak için kullanabilirsiniz.

Tüm sertifikaları listeleme

listPropertiesOfCertificates, Key Vault'taki tüm sertifikaları listeler.

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

Sertifikayı güncelleştirme

Sertifika öznitelikleri, updateCertificateile mevcut bir sertifika sürümüne aşağıdaki gibi güncelleştirilebilir:

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

Sertifikanın ilkesi aşağıdaki gibi updateCertificatePolicyile tek tek güncelleştirilebilir:

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

Sertifika silme

beginDeleteCertificate yöntemi, silinmek üzere bir sertifika ayarlar. Bu işlem, gerekli kaynaklar kullanılabilir duruma gelir gelmez arka planda gerçekleşir.

Key Vault için geçici silme etkinleştirilirse, bu işlem sertifikayı yalnızca silinmiş sertifikası olarak etiketler. Silinen bir sertifika güncelleştirilemez. Bunlar yalnızca okunabilir, kurtarılabilir veya temizlenebilir.

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

Sertifikanın silinmesi anında gerçekleşmeyeceğinden, silinen sertifika okunmaya, kurtarılmaya veya temizlenmeye hazır hale gelmeden önce beginDeleteCertificate yöntemi çağrıldıktan sonra biraz zaman gerekir.

Sertifika listelerini yineleme

CertificateClient'ı kullanarak, sertifika kasasındaki tüm sertifikaların yanı sıra silinen tüm sertifikalar ve belirli bir sertifikanın sürümleri aracılığıyla alabilir ve yineleyebilirsiniz. Aşağıdaki API yöntemleri kullanılabilir:

  • listPropertiesOfCertificates, silinmeyen tüm sertifikalarınızı yalnızca en son sürümlerinde adlarına göre listeler.
  • listDeletedCertificates, silinen tüm sertifikalarınızı yalnızca en son sürümlerinde adlarına göre listeler.
  • listPropertiesOfCertificateVersions sertifikanın tüm sürümlerini bir sertifika adına göre listeler.

Aşağıdaki gibi kullanılabilir:

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

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 .byPage() ekleyin:

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

Sorun giderme

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, @azure/loggersetLogLevel çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

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

Sonraki adımlar

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

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Gösterimler