Aracılığıyla paylaş


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

Azure Key Vault, bir bulut uygulamasında 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 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çirebilirsiniz: 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ı, sertifikanın özniteliklerini, vereni, ilkesini, işlemini ve kişilerini 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.
  • Tüm silinen sertifikaları 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 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.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ı .

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

Önemli 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 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. Bir sertifikayı bir adla 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 desteklemesini sağlar, bu nedenle silinen sertifikalar hemen kaybolmaz. Bu yalnızca Key Vault geçici silme etkinleştirildiğinde gerçekleşir.
  • Oluşturulan herhangi bir sertifikadan bir Sertifika yedeklemesi 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 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 { 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ümler, Azure Key Vault Sertifikalarını kullanarak bazı yaygın görevleri kapsayan kod parçacıkları sağlar. Burada ele alınan senaryolar şunlardan oluşur:

Sertifika oluşturma ve ayarlama

beginCreateCertificateAzure Key Vault 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, isteğe bağlı değerler içeren üçüncü bir bağımsız değişkende aşağıdaki özellikleri 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ı adla öğesine 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 temel beginCreateCertificate 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, çağrısı yaparak oluşturulan sertifikayı almanıza poller.getResult()olanak sağlar. Ayrıca, sertifika oluşturulana 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 { 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 aşağıdaki gibi tek tek çağrılar 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 çağırarak getCertificateVersion 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 tasarımı Anahtarlar, Gizli Diziler ve Sertifikalar arasında net ayrımlar yapar. Key Vault hizmetinin Sertifika özellikleri, Anahtarlar ve Gizli Diziler özelliklerinden yararlanarak tasarlanmıştır. Şimdi bir Key Vault Sertifikasının bileşimini değerlendirelim:

bir Key Vault sertifikası oluşturulduğunda, aynı adla adreslenebilir bir anahtar ve gizli dizi de oluşturulur. Key Vault anahtarı anahtar işlemlerine ve Key Vault gizli dizi, sertifika değerinin gizli dizi olarak alınmasına olanak tanır. Key Vault sertifikası genel x509 sertifika meta verilerini de içerir. Kaynak: Bir Sertifikanın Bileşimi.

Ö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 sertifikayı 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.

kullanarak openssl, 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 komutunu da kullanabilirsiniz openssl :

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 ekleyebilirsiniz -passin 'pass:' .

PEM biçimindeki sertifikalar

Sertifikalarla PEM biçiminde çalışmak istiyorsanız, Azure'ın Key Vault hizmetine sertifikaları oluştururken özelliğini sağlayarak sertifikalarınızı PEM biçiminde oluşturmasını ve yönetmesini contentType 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

listPropertiesOfCertificatesKey Vault 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 aşağıdaki gibi ile updateCertificatemevcut bir sertifika sürümüne 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 ile updateCertificatePolicytek 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

yöntemi, beginDeleteCertificate 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ştirildiyse, bu işlem sertifikayı yalnızca silinen sertifika 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();

Sertifika silme işlemi anında gerçekleşmeyeceğinden, silinen sertifika okunmaya, kurtarılmaya veya temizlenmeye hazır hale gelmeden önce yöntem çağrıldıktan sonra beginDeleteCertificate biraz zaman gerekir.

Sertifika listelerini yineleme

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

  • listPropertiesOfCertificates , silinmemiş tüm sertifikalarınızı adlarına göre, yalnızca en son sürümlerinde listeler.
  • listDeletedCertificates silinen tüm sertifikalarınızı adlarına göre, yalnızca en son sürümlerinde 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 ekleyin .byPage() :

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

Ç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 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