Azure Key Vault Certificates client library for JavaScript - version 4.10.3

Azure Key Vault, bulut uygulaması boyunca kullanılan sertifikaların güvenli depolamasını ve otomatik yönetimini sağlayan bir bulut hizmetidir. Birden fazla sertifika ve aynı sertifikanın birden fazla versiyonu Azure Key Vault'ta saklanabilir. 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, şu adresleri inceleyebilirsiniz: Azure Key Vault?

Node.js uygulamanızdaki Azure Key Vault Sertifikalar için istemci kütüphanesini şu adrese kullanırsınız:

  • 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: Bu paket, Azure Key Vault hizmet sınırlamaları nedeniyle tarayıcıda kullanılamaz, lütfen rehberlik için this document sayfasına bakınız.

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

  • Node.js LTS sürümleri

Önkoşullar

Paketi yükleme

Azure Key Vault Certificates client library using npm

npm install @azure/keyvault-certificates

Kimlik kitaplığını yükleme

Key Vault istemcileri, Azure Identity Library kullanılarak 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ı.

Authenticating with Azure Active Directory

Key Vault hizmeti, API'lerine gelen istekleri 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. README @azure/identity için daha fazla detay ve deneme sunuyor.

Azure Key Vault servisiyle etkileşime girmek için CertificateClient sınıfının bir örneğini, bir vault url ve bir credential nesnesi 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.

Farklı kimlik doğrulama yolları ve bunlara karşılık gelen kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimlik belgeleri adresinde bulabilirsiniz.

İşte hızlı bir örnek. İlk olarak, DefaultAzureCredential içeri aktarıp CertificateClient. Bunlar içeri aktarıldıktan sonra anahtar kasası hizmetine bağlanabiliriz:

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

  • Certificates istemcisi JavaScript uygulamasından Azure Key Vault API'deki sertifikalarla ilgili API yöntemleriyle etkileşime giren birincil arayüzdür. 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 versiyonu Key Vault'daki bir sertifikanın bir versiyonudur. 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 sadece Key Vault soft-delete olur.
  • 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 service API sürümünün belirtilmesi

Varsayılan olarak, bu paket 7.1 olan en son Azure Key Vault servis 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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

Örnekler

Aşağıdaki bölümler, Azure Key Vault Sertifikaları kullanılarak kullanılan bazı yaygın görevleri kapsayan kod parçalarını sunmaktadır. Burada ele alınan senaryolar şunlardan oluşur:

  • sertifika oluşturma ve ayarlama.
  • Key Vault sertifikası almak.
  • 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'de saklanmak üzere bir sertifika oluşturur. Aynı ada sahip bir sertifika zaten varsa, sertifikanın yeni bir sürümü oluşturulur.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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

await client.beginCreateCertificate(certificateName, certificatePolicy, {
  enabled,
  tags,
});

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:

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

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

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

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

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

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The certificate ${certificateName} is fully created`);

Key Vault sertifikası almak

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.

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

Sertifikanın tüm bilgilerini alma

Azure Key Vault'un tasarımı, Anahtarlar, Sırlar ve Sertifikalar arasında keskin ayrımlar yapar. Key Vault servisinin Sertifikalar özellikleri, Anahtarlar ve Sırlar yetenekleri kullanılarak tasarlanmıştır. Bir Key Vault Sertifikasının bileşimini değerlendirelim:

Bir Key Vault sertifikası oluşturulduğunda, adreslenebilir bir anahtar ve gizli de aynı isimle oluşturulur. Key Vault anahtarı anahtar işlemlerine izin verir ve Key Vault gizliliği sertifika değerinin sır olarak alınmasına izin verir. Bir Key Vault sertifikası ayrıca halka açık x509 sertifika meta verilerini içerir. Kaynağı: sertifikaoluşturma.

Özel anahtarın Key Vault Secret'te saklandığını ve halka açık sertifikanın da dahil olduğunu bilerek, Key Vault Secrets istemcisini kullanarak onu geri alabiliriz.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
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

PEM formatında sertifikalarla çalışmak istiyorsanız, sertifikaları oluştururken contentType özelliğini sağlayarak Azure's Key Vault hizmetine sertifikalarınızı PEM formatında oluşturup yönetmesini sağlayabilirsiniz.

Aşağıdaki örnek, Key Vault istemcileri for Certificates and Secrets kullanılarak PEM formatlı bir sertifikanın genel ve özel bölümlerinin nasıl oluşturulacağını ve alınacağını göstermektedir:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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 tüm sertifikaları Key Vault'de listeleyecektir.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Sertifikayı güncelleştirme

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
  enabled: false,
  tags: {
    myCustomTag: "myCustomTagsValue",
  },
});

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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.

Eğer Key Vault için soft-delete etkinleştirilmişse, bu işlem sertifikayı yalnızca silinmiş sertifikası olarak etiketler. Silinen bir sertifika güncelleştirilemez. Bunlar yalnızca okunabilir, kurtarılabilir veya temizlenebilir.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log("Certificate properties: ", certificateProperties);
  }
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
}
for await (const page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
  for (const certificateProperties of page) {
    console.log("Properties of certificate: ", certificateProperties);
  }
}

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, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Çeşitli arıza senaryolarının nasıl teşhis edileceğine dair detaylar için sorun giderme rehberimize bakınız.

Sonraki adımlar

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

Katkıda

Bu kütüphaneye katkıda bulunmak isterseniz, kodun nasıl oluşturulacağı ve test edileceği hakkında daha fazla bilgi edinmek için lütfen katkı rehberi adresini okuyun.

  • Last updated on