빠른 시작: 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 및 키에 대한 자세한 내용은 다음을 참조하세요.

• Key Vault 개요
• 키 개요.

필수 조건

• Azure 구독 - 체험 구독 만들기
• 현재 Node.js LTS.
• Azure CLI
• 기존 Key Vault - 다음을 사용하여 만들 수 있습니다.
  • Azure CLI
  • Azure Portal
  • Azure PowerShell

이 빠른 시작에서는 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
   

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

Azure CLI

RBAC(역할 기반 액세스 제어)를 통해 키 자격 증명 모음에 애플리케이션 권한을 부여하려면 az role assignment create Azure CLI 명령을 사용하여 역할을 할당합니다.

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

Azure PowerShell

RBAC(역할 기반 액세스 제어)를 통해 키 자격 증명 모음에 애플리케이션 권한을 부여하려면 Azure PowerShell cmdlet New-AzRoleAssignment를 사용하여 역할을 할당합니다.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

<app-id>, <subscription-id>, <resource-group-name>, <unique-keyvault-name>를 실제 값으로 대체합니다. <app-id>는 Azure AD에 등록된 애플리케이션의 애플리케이션(클라이언트) ID입니다.

환경 변수 설정

이 애플리케이션은 키 자격 증명 모음 이름을 KEY_VAULT_NAME이라는 환경 변수로 사용합니다.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

PowerShell

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS 또는 Linux

export KEY_VAULT_NAME=<your-key-vault-name>

클라이언트 인증 및 만들기

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

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

이 코드에서 키 자격 증명 모음 이름은 https://<your-key-vault-name>.vault.azure.net 형식의 키 자격 증명 모음 URI를 만드는 데 사용됩니다. 키 자격 증명 모음 인증에 대한 자세한 내용은 개발자 가이드를 참조하세요.

코드 예

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

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

• DefaultAzureCredential 클래스
• KeyClient 클래스
  • createKey
  • createEcKey
  • createRsaKey
  • getKey
  • listPropertiesOfKeys
  • updateKeyProperties
  • beginDeleteKey
  • getDeletedKey
  • purgeDeletedKey

앱 프레임워크 설정

1. 새 텍스트 파일을 만들고 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 keyVaultName = process.env["KEY_VAULT_NAME"];
       if(!keyVaultName) throw new Error("KEY_VAULT_NAME is empty");
       const url = "https://" + keyVaultName + ".vault.azure.net";
   
       const client = new KeyClient(url, 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-NAME.vault.azure.net/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-NAME.vault.azure.net/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-NAME.vault.azure.net",
       "version": "YOUR-KEY-VERSION",
       "name": "YOUR-KEY-VAULT-NAME",
       "managed": undefined,
       "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.net/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 및 이를 애플리케이션과 통합하는 방법에 대해 자세히 알아보려면 아래 문서로 계속 진행하세요.

• Azure Key Vault 개요 참조
• Azure Key Vault 개요 읽기
• 키 자격 증명 모음에 대한 액세스를 보호하는 방법
• Azure Key Vault 개발자 가이드 참조
• Azure Key Vault 보안 개요를 검토하세요.