Udostępnij za pośrednictwem


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

Wprowadzenie do biblioteki klienta kluczy usługi Azure Key Vault dla języka JavaScript. Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn kluczy kryptograficznych. 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ć klucze z magazynu kluczy platformy Azure przy użyciu biblioteki klienta klucza 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 kluczy, zobacz:

Wymagania wstępne

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

Logowanie się do platformy Azure

  1. 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.

  2. 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.

  1. 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
    
  2. Zainicjuj projekt Node.js:

    npm init -y
    

Instalowanie pakietów usługi Key Vault

  1. Za pomocą terminalu zainstaluj bibliotekę klienta wpisów tajnych usługi Azure Key Vault, @azure/keyvault-keys dla Node.js.

    npm install @azure/keyvault-keys
    
  2. Zainstaluj bibliotekę klienta tożsamości platformy Azure, @azure/pakiet tożsamości w celu uwierzytelnienia 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 Crypto 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>

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

W poniższych przykładach kodu pokazano, jak utworzyć klienta, ustawić wpis tajny, pobrać wpis tajny i usunąć wpis tajny.

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

Konfigurowanie struktury aplikacji

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

    const { KeyClient } = require("@azure/keyvault-keys");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    async function main() {
    
        // 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 KeyClient(keyVaultUrl, credential);
    
        const uniqueString = Date.now();
        const keyName = `sample-key-${uniqueString}`;
        const ecKeyName = `sample-ec-key-${uniqueString}`;
        const rsaKeyName = `sample-rsa-key-${uniqueString}`;
    
        // Create key using the general method
        const result = await client.createKey(keyName, "EC");
        console.log("key: ", result);
    
        // Create key using specialized key creation methods
        const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
        const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
        console.log("Elliptic curve key: ", ecResult);
        console.log("RSA Key: ", rsaResult);
    
        // Get a specific key
        const key = await client.getKey(keyName);
        console.log("key: ", key);
    
        // Or list the keys we have
        for await (const keyProperties of client.listPropertiesOfKeys()) {
        const key = await client.getKey(keyProperties.name);
        console.log("key: ", key);
        }
    
        // Update the key
        const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
        enabled: false
        });
        console.log("updated key: ", updatedKey);
    
        // Delete the key - the key is soft-deleted but not yet purged
        const deletePoller = await client.beginDeleteKey(keyName);
        await deletePoller.pollUntilDone();
    
        const deletedKey = await client.getDeletedKey(keyName);
        console.log("deleted key: ", deletedKey);
    
        // Purge the key - the key is permanently deleted
        // This operation could take some time to complete
        console.time("purge a single key");
        await client.purgeDeletedKey(keyName);
        console.timeEnd("purge a single key");
    }
    
    main().catch((error) => {
      console.error("An error occurred:", error);
      process.exit(1);
    });
    

Uruchamianie przykładowej aplikacji

  1. Uruchom aplikację:

    node index.js
    
  2. Metody tworzenia i pobierania zwracają pełny obiekt JSON dla klucza:

    "key":  {
      "key": {
        "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
        "kty": "YOUR-KEY-TYPE",
        "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
        ... other properties based on key type
      },
      "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
      "name": "YOUR-KEY-NAME",
      "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
      "keyType": "YOUR-KEY-TYPE",
      "properties": {
        "tags": undefined,
        "enabled": true,
        "notBefore": undefined,
        "expiresOn": undefined,
        "createdOn": 2021-11-29T18:29:11.000Z,
        "updatedOn": 2021-11-29T18:29:11.000Z,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "exportable": undefined,
        "releasePolicy": undefined,
        "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
        "version": "YOUR-KEY-VERSION",
        "name": "YOUR-KEY-VAULT-NAME",
        "managed": undefined,
        "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
      }
    }
    
  • Utwórz nowy plik tekstowy i wklej następujący kod do pliku index.ts .

    import {
      KeyClient,
      KeyVaultKey,
      KeyProperties,
      DeletedKey,
    } from "@azure/keyvault-keys";
    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 printKey(keyVaultKey: KeyVaultKey): void {
      const { name, key, id, keyType, keyOperations, properties } = keyVaultKey;
      console.log("Key: ", { name, key, id, keyType });
    
      const { vaultUrl, version, enabled, expiresOn }: KeyProperties = properties;
      console.log("Key Properties: ", { vaultUrl, version, enabled, expiresOn });
    
      console.log("Key Operations: ", keyOperations.join(", "));
    }
    
    async function main(): Promise<void> {
      // Create a new KeyClient
      const client = new KeyClient(keyVaultUrl, credential);
    
      // Create unique key names
      const uniqueString = Date.now().toString();
      const keyName = `sample-key-${uniqueString}`;
      const ecKeyName = `sample-ec-key-${uniqueString}`;
      const rsaKeyName = `sample-rsa-key-${uniqueString}`;
    
      // Create a EC key
      const ecKey = await client.createKey(keyName, "EC");
      printKey(ecKey);
    
      // Elliptic curve key
      const ec256Key = await client.createEcKey(ecKeyName, {
        curve: "P-256",
      });
      printKey(ec256Key);
    
      // RSA key
      const rsa2048Key = await client.createRsaKey(rsaKeyName, {
        keySize: 2048,
      });
      printKey(rsa2048Key);
    
      // Get a key
      const key = await client.getKey(keyName);
      printKey(key);
    
      // Get properties of all keys
      for await (const keyProperties of client.listPropertiesOfKeys()) {
        const iteratedKey = await client.getKey(keyProperties.name);
        printKey(iteratedKey);
      }
    
      // Update key properties - disable key
      const updatedKey = await client.updateKeyProperties(
        keyName,
        ecKey.properties.version,
        {
          enabled: false,
        }
      );
      printKey(updatedKey);
    
      // Delete key (without immediate purge)
      const deletePoller = await client.beginDeleteKey(keyName);
      await deletePoller.pollUntilDone();
    
      // Get a deleted key
      const deletedKey = await client.getDeletedKey(keyName);
      console.log("deleted key: ", deletedKey.name);
    
      // Purge a deleted key
      console.time("purge a single key");
      await client.purgeDeletedKey(keyName);
      console.timeEnd("purge a single key");
    }
    
    main().catch((error) => {
      console.error("An error occurred:", error);
      process.exit(1);
    });
    

Uruchamianie przykładowej aplikacji

  1. Skompiluj aplikację TypeScript:

    tsc
    
  2. Uruchom aplikację:

    node index.js
    
  3. Metody tworzenia i pobierania zwracają pełny obiekt JSON dla klucza:

    "key":  {
      "key": {
        "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
        "kty": "YOUR-KEY-TYPE",
        "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
        ... other properties based on key type
      },
      "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
      "name": "YOUR-KEY-NAME",
      "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
      "keyType": "YOUR-KEY-TYPE",
      "properties": {
        "tags": undefined,
        "enabled": true,
        "notBefore": undefined,
        "expiresOn": undefined,
        "createdOn": 2021-11-29T18:29:11.000Z,
        "updatedOn": 2021-11-29T18:29:11.000Z,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "exportable": undefined,
        "releasePolicy": undefined,
        "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
        "version": "YOUR-KEY-VERSION",
        "name": "YOUR-KEY-VAULT-NAME",
        "managed": undefined,
        "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
      }
    }
    

Integrowanie z usługą App Configuration

Zestaw Azure SDK udostępnia metodę pomocnika, parseKeyVaultKeyIdentifier, aby przeanalizować dany identyfikator klucza usługi Key Vault. Jest to konieczne, jeśli używasz odwołań usługi App Configuration do usługi Key Vault. Konfiguracja aplikacji przechowuje identyfikator klucza usługi Key Vault. Aby przeanalizować ten identyfikator, musisz przeanalizować metodę parseKeyVaultKeyIdentifier , aby uzyskać nazwę klucza. Po utworzeniu nazwy klucza możesz uzyskać bieżącą wartość klucza przy użyciu kodu z tego przewodnika Szybki start.

Następne kroki

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