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

아티클
11/01/2024

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

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

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

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

필수 조건

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

login 명령을 실행합니다.
```
az login
```
CLI는 기본 브라우저를 열 수 있으면 기본 브라우저를 열고 Azure 로그인 페이지를 로드합니다.

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

az group create 명령을 사용하여 리소스 그룹을 만듭니다.
```
az group create --name myResourceGroup --location eastus
```
선호하는 경우 "eastus"를 사용자에게 가까운 위치로 변경할 수 있습니다.
az keyvault create를 사용하여 키 자격 증명 모음을 만듭니다.
```
az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup
```
<your-unique-keyvault-name>을 모든 Azure에서 고유한 이름으로 바꿉니다. 일반적으로 다른 번호 및 식별자와 함께 개인 또는 회사 이름을 사용합니다.

New-AzResourceGroup 명령을 사용하여 리소스 그룹을 만듭니다.
```
New-AzResourceGroup -Name myResourceGroup -Location eastus
```
선호하는 경우 "eastus"를 사용자에게 가까운 위치로 변경할 수 있습니다.
New-AzKeyVault를 사용하여 키 자격 증명 모음을 만듭니다.
```
New-AzKeyVault -Name <your-unique-keyvault-name> -ResourceGroupName myResourceGroup -Location eastus
```
<your-unique-keyvault-name>을 모든 Azure에서 고유한 이름으로 바꿉니다. 일반적으로 다른 번호 및 식별자와 함께 개인 또는 회사 이름을 사용합니다.

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

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

az role assignment create --role "Key Vault Secrets 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)입니다.

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

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

터미널에서 key-vault-node-app라는 폴더를 만들고 해당 폴더로 변경합니다.
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Node.js 프로젝트를 초기화합니다.
```
npm init -y
```

Key Vault 패키지 설치

터미널을 사용하여 Azure Key Vault 비밀 클라이언트 라이브러리(Node.js용 @azure/keyvault-secrets)를 설치합니다.
```
npm install @azure/keyvault-secrets
```
Azure ID 클라이언트 라이브러리인 @azure/identity 패키지를 설치하여 Key Vault에 인증합니다.
```
npm install @azure/identity
```

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

az role assignment create --role "Key Vault Secrets 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>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export 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 { 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 keyVaultUrl = process.env["KEY_VAULT_URL"];
  if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

  const client = new SecretClient(keyVaultUrl, 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);
});

샘플 애플리케이션 실행

앱을 실행합니다.
```
node index.js
```

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-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.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-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

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

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
} from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

// Passwordless credential
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 printSecret(secret: KeyVaultSecret): void {
  const { name, value, properties } = secret;
  const { enabled, expiresOn, createdOn } = properties;
  console.log("Secret: ", { name, value, enabled, expiresOn, createdOn });
}
function printSecretProperties(secret: SecretProperties): void {
  const { name, enabled, expiresOn, createdOn } = secret;
  console.log("Secret: ", { name, enabled, expiresOn, createdOn });
}

async function main(): Promise<void> {
  // Create a new SecretClient
  const client = new SecretClient(keyVaultUrl, credential);

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

  // Create a secret
  const createSecretResult = await client.setSecret(
    secretName,
    "MySecretValue"
  );
  printSecret(createSecretResult);

  // Get the secret by name
  const getSecretResult = await client.getSecret(secretName);
  printSecret(getSecretResult);

  // Update properties
  const updatedSecret = await client.updateSecretProperties(
    secretName,
    getSecretResult.properties.version,
    {
      enabled: false,
    }
  );
  printSecretProperties(updatedSecret);

  // Delete secret (without immediate purge)
  const deletePoller = await client.beginDeleteSecret(secretName);
  await deletePoller.pollUntilDone();
}

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

샘플 애플리케이션 실행

TypeScript 앱 빌드:
```
tsc
```
앱을 실행합니다.
```
node index.js
```

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-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.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-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

App Configuration과 통합

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

다음 단계

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

다음을 통해 공유

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

필수 조건

필수 조건

리소스 그룹 및 키 자격 증명 모음 만들기

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

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

Key Vault 패키지 설치

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

환경 변수 설정

클라이언트 인증 및 만들기

코드 예

앱 프레임워크 설정

샘플 애플리케이션 실행

샘플 애플리케이션 실행

App Configuration과 통합

다음 단계

피드백

추가 리소스

다음을 통해 공유

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

필수 조건

필수 조건

Azure에 로그인

리소스 그룹 및 키 자격 증명 모음 만들기

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

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

Key Vault 패키지 설치

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

환경 변수 설정

클라이언트 인증 및 만들기

코드 예

앱 프레임워크 설정

샘플 애플리케이션 실행

샘플 애플리케이션 실행

App Configuration과 통합

다음 단계

피드백

추가 리소스