빠른 시작: 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-secrets)를 설치합니다.

   npm install @azure/keyvault-secrets
   

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>를 실제 값으로 대체합니다. <앱 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
• SecretClient 클래스
  • setSecret
  • getSecret
  • updateSecretProperties
  • beginDeleteSecret

앱 프레임워크 설정

1. 새 텍스트 파일을 만들고 index.js 파일에 다음 코드를 붙여넣습니다.

   const { SecretClient } = require("@azure/keyvault-secrets");
   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 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 SecretClient(url, credential);
   
     // Create a secret
     // The secret can be a string of any kind. For example,
     // a multiline text block such as an RSA private key with newline characters,
     // or a stringified JSON object, like `JSON.stringify({ mySecret: 'MySecretValue'})`.
     const uniqueString = new Date().getTime();
     const secretName = `secret${uniqueString}`;
     const result = await client.setSecret(secretName, "MySecretValue");
     console.log("result: ", result);
   
     // Read the secret we created
     const secret = await client.getSecret(secretName);
     console.log("secret: ", secret);
   
     // Update the secret with different attributes
     const updatedSecret = await client.updateSecretProperties(secretName, result.properties.version, {
       enabled: false
     });
     console.log("updated secret: ", updatedSecret);
   
     // Delete the secret immediately without ability to restore or purge.
     await client.beginDeleteSecret(secretName);
   }
   
   main().catch((error) => {
     console.error("An error occurred:", error);
     process.exit(1);
   });
   

샘플 애플리케이션 실행

1. 앱을 실행합니다.

   node index.js
   

2. create 및 get 메서드는 비밀에 대한 전체 JSON 개체를 반환합니다.

   {
       "value": "MySecretValue",
       "name": "secret1637692472606",
       "properties": {
           "createdOn": "2021-11-23T18:34:33.000Z",
           "updatedOn": "2021-11-23T18:34:33.000Z",
           "enabled": true,
           "recoverableDays": 90,
           "recoveryLevel": "Recoverable+Purgeable",
           "id": "https: //YOUR-KEYVAULT-NAME.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
           "vaultUrl": "https: //YOUR-KEYVAULT-NAME.vault.azure.net",
           "version": "YOUR-VERSION",
           "name": "secret1637692472606"
       }
   }
   

   업데이트 메서드는 속성 이름/값 쌍을 반환합니다.

   "createdOn": "2021-11-23T18:34:33.000Z",
   "updatedOn": "2021-11-23T18:34:33.000Z",
   "enabled": true,
   "recoverableDays": 90,
   "recoveryLevel": "Recoverable+Purgeable",
   "id": "https: //YOUR-KEYVAULT-NAME.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
   "vaultUrl": "https: //YOUR-KEYVAULT-NAME.vault.azure.net",
   "version": "YOUR-VERSION",
   "name": "secret1637692472606"
   

App Configuration과 통합

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

다음 단계

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

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