Szybki start: biblioteka klienta certyfikatów usługi Azure Key Vault dla języka JavaScript

Artykuł
10/05/2024

Wprowadzenie do biblioteki klienta certyfikatów usługi Azure Key Vault dla języka JavaScript. Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn certyfikatów. Możesz bezpiecznie przechowywać klucze, hasła, certyfikaty oraz inne wpisy tajne. Magazyny kluczy platformy Azure można tworzyć oraz nimi zarządzać za pośrednictwem witryny Azure Portal. Z tego przewodnika Szybki start dowiesz się, jak tworzyć, pobierać i usuwać certyfikaty z magazynu kluczy platformy Azure przy użyciu biblioteki klienta Języka JavaScript.

Zasoby biblioteki klienta usługi Key Vault:

Dokumentacja interfejsu API — pakiet | kodu | źródłowego biblioteki (npm)

Aby uzyskać więcej informacji na temat usługi Key Vault i certyfikatów, zobacz:

Wymagania wstępne

Subskrypcja platformy Azure — utwórz bezpłatnie.
Bieżąca Node.js LTS.
Interfejs wiersza polecenia platformy Azure
Istniejący magazyn Key Vault — można go utworzyć przy użyciu:

Subskrypcja platformy Azure — utwórz bezpłatnie.
Bieżąca Node.js LTS.
TypeScript 5+
Interfejs wiersza polecenia platformy Azure
Istniejący magazyn Key Vault — można go utworzyć przy użyciu:

W tym przewodniku Szybki start założono, że używasz interfejsu wiersza polecenia platformy Azure.

Uruchom polecenie login.
```
az login
```
Jeśli interfejs wiersza polecenia może otworzyć domyślną przeglądarkę, zrobi to i załaduje stronę logowania platformy Azure.

W przeciwnym razie otwórz stronę przeglądarki pod https://aka.ms/devicelogin adresem i wprowadź kod autoryzacji wyświetlany w terminalu.
Zaloguj się w przeglądarce przy użyciu poświadczeń swojego konta.

Tworzenie nowej aplikacji Node.js

Utwórz aplikację Node.js korzystającą z magazynu kluczy.

W terminalu utwórz folder o nazwie key-vault-node-app i przejdź do tego folderu:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Zainicjuj projekt Node.js:
```
npm init -y
```

Instalowanie pakietów usługi Key Vault

Za pomocą terminalu zainstaluj bibliotekę wpisów tajnych usługi Azure Key Vault, @azure/keyvault-certificates dla Node.js.
```
npm install @azure/keyvault-certificates
```
Zainstaluj bibliotekę klienta tożsamości platformy Azure, @azure/tożsamość, aby uwierzytelnić się w usłudze Key Vault.
```
npm install @azure/identity
```

Udzielanie dostępu do magazynu kluczy

Aby uzyskać uprawnienia do magazynu kluczy za pomocą kontroli dostępu opartej na rolach (RBAC), przypisz rolę do głównej nazwy użytkownika (UPN) przy użyciu polecenia az role assignment create interfejsu wiersza polecenia platformy Azure.

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

Zastąp <wartości upn>, <subscription-id>, <resource-group-name> i <your-unique-keyvault-name> rzeczywistymi wartościami. Nazwa UPN będzie zwykle mieć format adresu e-mail (np. username@domain.com).

Ustawianie zmiennych środowiskowych

Ta aplikacja używa punktu końcowego magazynu kluczy jako zmiennej środowiskowej o nazwie 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>

Uwierzytelnianie i tworzenie klienta

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. Użycie metody DefaultAzureCredential udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

W tym przewodniku Szybki start DefaultAzureCredential uwierzytelnia się w magazynie kluczy przy użyciu poświadczeń lokalnego użytkownika dewelopera zalogowanego do interfejsu wiersza polecenia platformy Azure. Po wdrożeniu aplikacji na platformie Azure ten sam DefaultAzureCredential kod może automatycznie odnajdywać i używać tożsamości zarządzanej przypisanej do usługi App Service, maszyny wirtualnej lub innych usług. Aby uzyskać więcej informacji, zobacz Omówienie tożsamości zarządzanej.

W tym kodzie punkt końcowy magazynu kluczy jest używany do tworzenia klienta magazynu kluczy. Format punktu końcowego wygląda podobnie, https://<your-key-vault-name>.vault.azure.net ale może ulec zmianie w przypadku suwerennych chmur. Aby uzyskać więcej informacji na temat uwierzytelniania w magazynie kluczy, zobacz Przewodnik dewelopera.

Przykład kodu

Ten kod używa następujących klas i metod certyfikatów usługi Key Vault:

Konfigurowanie struktury aplikacji

Utwórz nowy plik tekstowy i wklej następujący kod do pliku index.js .

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

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, 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 CertificateClient(keyVaultUrl, credential);

  const uniqueString = new Date().getTime();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  const pendingCertificate = createPoller.getResult();
  console.log("Certificate: ", pendingCertificate);

  // To read a certificate with their policy:
  let certificateWithPolicy = await client.getCertificate(certificateName);
  // Note: It will always read the latest version of the certificate.

  console.log("Certificate with policy:", certificateWithPolicy);

  // To read a certificate from a specific version:
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version
  );
  // Note: It will not retrieve the certificate's policy.
  console.log("Certificate from a specific version:", certificateFromVersion);

  const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
    tags: {
      customTag: "value"
    }
  });
  console.log("Updated certificate:", updatedCertificate);

  // Updating the certificate's policy:
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyOtherCert"
  });
  certificateWithPolicy = await client.getCertificate(certificateName);
  console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);

  // delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  console.log("Recovery Id: ", deletedCertificate.recoveryId);
  console.log("Deleted Date: ", deletedCertificate.deletedOn);
  console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
}

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

Uruchamianie przykładowej aplikacji

Uruchom aplikację:
```
node index.js
```

Metody tworzenia i pobierania zwracają pełny obiekt JSON dla certyfikatu:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Utwórz nowy plik tekstowy i wklej następujący kod do pliku index.ts .

import {
  CertificateClient,
  DefaultCertificatePolicy,
  KeyVaultCertificate,
  DeletedCertificate,
  CertificatePolicy,
  KeyVaultCertificateWithPolicy,
} from "@azure/keyvault-certificates";
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 printCertificate(
  certificate: KeyVaultCertificate | KeyVaultCertificateWithPolicy
): void {
  console.log("-- printCertificate ---------------------------");

  // if policy is defined, it's a KeyVaultCertificateWithPolicy
  if ((certificate as KeyVaultCertificateWithPolicy).policy) {
    const { name, properties, policy } =
      certificate as KeyVaultCertificateWithPolicy;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    console.log("Certificate Policy: ", policy);
    printObjectProperties(tags);
    return;
  } else {
    const { name, properties } = certificate;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    printObjectProperties(tags);
  }
}
// Object properties are tags and CertificatePolicy
function printObjectProperties(obj: Record<string, any>): void {
  if (!obj) return;

  console.log("-- printObjectProperties ---------------------------");

  Object.entries(obj).forEach(([key, value]) => {
    if (key === "lifetimeActions") {
      console.log(`${key}: ${JSON.stringify(value)}`);
    } else {
      console.log(`${key}: ${value}`);
    }
  });
}
function printDeletedCertificate(deletedCertificate: DeletedCertificate): void {
  const { recoveryId, deletedOn, scheduledPurgeDate } = deletedCertificate;
  console.log("Deleted Certificate: ", {
    recoveryId,
    deletedOn,
    scheduledPurgeDate,
  });
}
async function main(): Promise<void> {
  // Create a new CertificateClient
  const client = new CertificateClient(keyVaultUrl, credential);

  // Create a unique certificate name
  const uniqueString = new Date().getTime().toString();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  // Get the created certificate
  const pendingCertificate = await createPoller.getResult();
  printCertificate(pendingCertificate);

  // Get certificate by name
  let certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(pendingCertificate);

  // Get certificate by version
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version!
  );
  printCertificate(certificateFromVersion);

  // Update properties of the certificate
  const updatedCertificate = await client.updateCertificateProperties(
    certificateName,
    certificateWithPolicy.properties.version!,
    {
      tags: {
        customTag: "my value",
      },
    }
  );
  printCertificate(updatedCertificate);

  // Updating the certificate's policy
  const certificatePolicy = await client.updateCertificatePolicy(
    certificateName,
    {
      issuerName: "Self",
      subject: "cn=MyOtherCert",
    }
  );
  printObjectProperties(certificatePolicy);

  // Get certificate again to see the updated policy
  certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(certificateWithPolicy);

  // Delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  printDeletedCertificate(deletedCertificate);
}

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

Uruchamianie przykładowej aplikacji

Skompiluj aplikację TypeScript:
```
tsc
```
Uruchom aplikację:
```
node index.js
```

Metody tworzenia i pobierania zwracają pełny obiekt JSON dla certyfikatu:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Integrowanie z usługą App Configuration

Zestaw Azure SDK udostępnia metodę pomocnika, parseKeyVaultCertificateIdentifier, aby przeanalizować dany identyfikator certyfikatu usługi Key Vault, co jest konieczne, jeśli używasz odwołań usługi App Configuration do usługi Key Vault. Konfiguracja aplikacji przechowuje identyfikator certyfikatu usługi Key Vault. Potrzebujesz metody parseKeyVaultCertificateIdentifier, aby przeanalizować ten identyfikator, aby uzyskać nazwę certyfikatu. Po utworzeniu nazwy certyfikatu możesz pobrać bieżący certyfikat przy użyciu kodu z tego przewodnika Szybki start.

Następne kroki

W tym przewodniku Szybki start utworzono magazyn kluczy, zapisano certyfikat i pobrano ten certyfikat. Aby dowiedzieć się więcej o usłudze Key Vault i sposobie jej integracji z aplikacjami, przejdź do tych artykułów.

Przeczytaj omówienie usługi Azure Key Vault
Przeczytaj omówienie certyfikatów
Samouczek dotyczący uzyskiwania dostępu do usługi Key Vault z poziomu aplikacji usługi App Service
Zobacz samouczek uzyskiwania dostępu do usługi Key Vault z poziomu maszyny wirtualnej
Zobacz przewodnik dewelopera usługi Azure Key Vault
Przegląd zabezpieczeń usługi Key Vault

Udostępnij za pośrednictwem

Szybki start: biblioteka klienta certyfikatów usługi Azure Key Vault dla języka JavaScript

Wymagania wstępne

Tworzenie nowej aplikacji Node.js

Instalowanie pakietów usługi Key Vault

Udzielanie dostępu do magazynu kluczy

Ustawianie zmiennych środowiskowych

Uwierzytelnianie i tworzenie klienta

Przykład kodu

Konfigurowanie struktury aplikacji

Uruchamianie przykładowej aplikacji

Uruchamianie przykładowej aplikacji

Integrowanie z usługą App Configuration

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Szybki start: biblioteka klienta certyfikatów usługi Azure Key Vault dla języka JavaScript

Wymagania wstępne

Logowanie się do platformy Azure

Tworzenie nowej aplikacji Node.js

Instalowanie pakietów usługi Key Vault

Udzielanie dostępu do magazynu kluczy

Ustawianie zmiennych środowiskowych

Uwierzytelnianie i tworzenie klienta

Przykład kodu

Konfigurowanie struktury aplikacji

Uruchamianie przykładowej aplikacji

Uruchamianie przykładowej aplikacji

Integrowanie z usługą App Configuration

Następne kroki

Opinia

Dodatkowe zasoby