다음을 통해 공유


빠른 시작: JavaScript용 Azure Key Vault 키 클라이언트 라이브러리

JavaScript용 Azure Key Vault 키 클라이언트 라이브러리를 시작합니다. Azure Key Vault는 암호화 키에 대한 보안 저장소를 제공하는 클라우드 서비스입니다. 키, 암호, 인증서 및 기타 비밀을 안전하게 저장할 수 있습니다. Azure Portal을 통해 Azure Key Vault를 만들고 관리할 수 있습니다. 이 빠른 시작에서는 JavaScript 키 클라이언트 라이브러리를 사용하여 Azure Key Vault에서 키를 만들고, 검색하고, 삭제하는 방법을 알아봅니다.

Key Vault 클라이언트 라이브러리 리소스:

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(npm)

Key Vault 및 키에 대한 자세한 내용은 다음을 참조하세요.

필수 조건

이 빠른 시작에서는 Azure CLI를 실행하고 있다고 가정합니다.

Azure에 로그인

  1. login 명령을 실행합니다.

    az login
    

    CLI는 기본 브라우저를 열 수 있으면 기본 브라우저를 열고 Azure 로그인 페이지를 로드합니다.

    그렇지 않으면 https://aka.ms/devicelogin 에서 브라우저 페이지를 열고 터미널에 표시된 권한 부여 코드를 입력합니다.

  2. 브라우저에서 계정 자격 증명으로 로그인합니다.

새 Node.js 애플리케이션 만들기

키 자격 증명 모음을 사용하는 Node.js 애플리케이션을 만듭니다.

  1. 터미널에서 key-vault-node-app라는 폴더를 만들고 해당 폴더로 변경합니다.

    mkdir key-vault-node-app && cd key-vault-node-app
    
  2. Node.js 프로젝트를 초기화합니다.

    npm init -y
    

Key Vault 패키지 설치

  1. 터미널을 사용하여 Azure Key Vault 비밀 클라이언트 라이브러리(Node.js용 @azure/keyvault-keys)를 설치합니다.

    npm install @azure/keyvault-keys
    
  2. Azure ID 클라이언트 라이브러리인 @azure/identity 패키지를 설치하여 Key Vault에 인증합니다.

    npm install @azure/identity
    

키 자격 증명 모음에 대한 액세스 권한 부여

RBAC(역할 기반 액세스 제어)를 통해 키 자격 증명 모음에 대한 권한을 얻으려면 Azure CLI 명령 az role assignment create을 사용하여 UPN("사용자 계정 이름")에 역할을 할당합니다.

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

<upn>, <subscription-id>, <resource-group-name> 및 <your-unique-keyvault-name>을 실제 값으로 바꿉니다. UPN은 일반적으로 이메일 주소 형식(예: username@domain.com)입니다.

환경 변수 설정

이 애플리케이션은 KEY_VAULT_URL(이)라는 환경 변수로 키 자격 증명 모음 엔드포인트를 사용하고 있습니다.

set KEY_VAULT_URL=<your-key-vault-endpoint>

클라이언트 인증 및 만들기

대부분의 Azure 서비스에 대한 애플리케이션 요청은 승인되어야 합니다. Azure.Identity 클라이언트 라이브러리에서 제공하는 DefaultAzureCredential 메서드를 사용하는 것은 코드에서 Azure 서비스에 대한 암호 없는 연결을 구현하는 데 권장되는 접근 방식입니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용해야 하는 방법을 결정합니다. 이 방법을 사용하면 앱에서 환경별 코드를 구현하지 않고도 다양한 환경(로컬 및 프로덕션)에서 다양한 인증 방법을 사용할 수 있습니다.

이 빠른 시작에서 DefaultAzureCredential은 Azure CLI에 로그인한 로컬 개발 사용자의 자격 증명을 사용하여 키 자격 증명 모음에 인증합니다. 애플리케이션이 Azure에 배포되면 동일한 DefaultAzureCredential 코드에서 App Service, 가상 머신 또는 기타 서비스에 할당된 관리 ID를 자동으로 검색하고 사용할 수 있습니다. 자세한 내용은 관리 ID 개요를 참조하세요.

이 코드에서는 키 자격 증명 모음의 엔드포인트를 사용하여 키 자격 증명 모음 클라이언트를 만듭니다. 엔드포인트 형식은 https://<your-key-vault-name>.vault.azure.net과(와) 유사하지만 소버린 클라우드의 경우 변경될 수 있습니다. 키 자격 증명 모음 인증에 대한 자세한 내용은 개발자 가이드를 참조하세요.

코드 예

아래의 코드 샘플에서는 클라이언트를 만들고, 비밀을 설정, 검색 및 삭제하는 방법을 보여 줍니다.

이 코드는 다음 Key Vault 비밀 클래스 및 메서드를 사용합니다.

앱 프레임워크 설정

  • 새 텍스트 파일을 만들고 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);
    });
    

샘플 애플리케이션 실행

  1. 앱을 실행합니다.

    node index.js
    
  2. create 및 get 메서드는 키에 대한 전체 JSON 개체를 반환합니다.

    "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"
      }
    }
    
  • 새 텍스트 파일을 만들고 다음 코드를 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);
    });
    

샘플 애플리케이션 실행

  1. TypeScript 앱 빌드:

    tsc
    
  2. 앱을 실행합니다.

    node index.js
    
  3. create 및 get 메서드는 키에 대한 전체 JSON 개체를 반환합니다.

    "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"
      }
    }
    

App Configuration과 통합

Azure SDK는 지정된 Key Vault Key ID를 구문 분석하는 도우미 메서드인 parseKeyVaultKeyIdentifier를 제공합니다. Key Vault에 대한 App Configuration 참조를 사용하는 경우에 필요합니다. 앱 구성은 Key Vault Key ID를 저장합니다. 키 이름을 가져오기 위해 해당 ID를 구문 분석하려면 parseKeyVaultKeyIdentifier 메서드가 필요합니다. 키 이름이 있는 경우 이 빠른 시작의 코드를 사용하여 현재 키 값을 가져올 수 있습니다.

다음 단계

이 빠른 시작에서는 키 자격 증명 모음을 만들고, 키를 저장하고, 해당 키를 검색했습니다. Key Vault 및 이를 애플리케이션과 통합하는 방법에 대해 자세히 알아보려면 아래 문서로 계속 진행하세요.