다음을 통해 공유

JavaScript용 Azure Key Vault 비밀 클라이언트 라이브러리 - 버전 4.8.0

  • 아티클

Azure Key Vault 보안 키를 사용하여 인증 키, 스토리지 계정 키, 데이터 암호화 키, .pfx 파일 및 암호를 암호화할 수 있는 서비스입니다. Azure Key Vault 대해 자세히 알아보려면 Azure Key Vault란?을 검토할 수 있습니다.

Azure Key Vault 비밀 관리를 사용하면 토큰, 암호, 인증서, API 키 및 기타 비밀에 대한 액세스를 안전하게 저장하고 엄격하게 제어할 수 있습니다.

Node.js 애플리케이션에서 Azure Key Vault 비밀용 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

  • 비밀을 가져오기, 설정 및 삭제합니다.
  • 비밀을 업데이트하고 특성입니다.
  • 비밀을 백업하고 복원합니다.
  • 삭제된 비밀을 가져오기, 제거 또는 복구합니다.
  • 비밀의 모든 버전을 가져옵니다.
  • 모든 비밀을 가져옵니다.
  • 삭제된 모든 비밀을 가져옵니다.

참고: 이 패키지는 Azure Key Vault 서비스 제한으로 인해 브라우저에서 사용할 수 없습니다. 지침은 이 문서를 참조하세요.

주요 링크:

시작

현재 지원되는 환경

필수 구성 요소

패키지 설치

npm을 사용하여 Azure Key Vault Secret 클라이언트 라이브러리를 설치합니다.

npm install @azure/keyvault-secrets

ID 라이브러리 설치

Key Vault 클라이언트는 Azure ID 라이브러리를 사용하여 인증합니다. npm을 사용하여 설치

npm install @azure/identity

TypeScript 구성

TypeScript 사용자는 노드 형식 정의를 설치해야 합니다.

npm install @types/node

또한 tsconfig.json 사용하도록 설정 compilerOptions.allowSyntheticDefaultImports 해야 합니다. 를 사용하도록 설정한 compilerOptions.esModuleInteropallowSyntheticDefaultImports 경우 는 기본적으로 사용하도록 설정됩니다. 자세한 내용은 TypeScript의 컴파일러 옵션 핸드북 을 참조하세요.

주요 개념

  • 비밀 클라이언트는 JavaScript 애플리케이션에서 Azure Key Vault API의 비밀과 관련된 API 메서드와 상호 작용하는 기본 인터페이스입니다. 초기화되면 비밀을 만들고, 읽고, 업데이트하고, 삭제하는 데 사용할 수 있는 기본 메서드 집합을 제공합니다.
  • 비밀 버전은 Key Vault 비밀 버전입니다. 사용자가 고유한 비밀 이름에 값을 할당할 때마다 해당 비밀의 새 버전 이 만들어집니다. 특정 버전이 쿼리에 제공되지 않는 한 이름으로 비밀을 검색하면 항상 할당된 최신 값이 반환됩니다.
  • 일시 삭제 를 사용하면 Key Vault가 삭제 및 제거를 두 개의 개별 단계로 지원할 수 있으므로 삭제된 비밀은 즉시 손실되지 않습니다. 이는 Key Vault 일시 삭제를 사용하도록 설정한 경우에만 발생합니다.
  • 비밀 백업은 생성된 비밀에서 생성할 수 있습니다. 이러한 백업은 이진 데이터로 제공되며 이전에 삭제된 비밀을 다시 생성하는 데만 사용할 수 있습니다.

Azure Active Directory를 사용하여 인증

Key Vault 서비스는 Azure Active Directory를 사용하여 API에 대한 요청을 인증합니다. 패키지는 @azure/identity 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 형식을 제공합니다. 에 대한 추가 정보는 시작하기 위한 @azure/identity 자세한 내용과 샘플을 제공합니다.

Azure Key Vault 서비스와 상호 작용하려면 클래스의 instanceSecretClient, 자격 증명 모음 URL 및 자격 증명 개체를 만들어야 합니다. 이 문서에 표시된 예제에서는 라는 자격 증명 개체를 사용합니다. 이 개체 DefaultAzureCredential는 로컬 개발 및 프로덕션 환경을 비롯한 대부분의 시나리오에 적합합니다. 또한 프로덕션 환경에서 인증에 관리 ID 를 사용하는 것이 좋습니다.

다양한 인증 방법 및 해당 자격 증명 유형에 대한 자세한 내용은 Azure ID 설명서에서 확인할 수 있습니다.

다음은 빠른 예제입니다. 먼저 및 를 SecretClient가져옵니다DefaultAzureCredential.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

가져온 후에는 Key Vault 서비스에 연결할 수 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

Azure Key Vault 서비스 API 버전 지정

기본적으로 이 패키지는 최신 Azure Key Vault 서비스 버전()을 7.1사용합니다. 지원되는 유일한 다른 버전은 입니다 7.0. 아래와 같이 클라이언트 생성자에서 옵션을 serviceVersion 설정하여 사용 중인 서비스 버전을 변경할 수 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0",
});

예제

다음 섹션에서는 Azure Key Vault 비밀을 사용하는 몇 가지 일반적인 작업을 다루는 코드 조각을 제공합니다. 여기서 다루는 시나리오는 다음으로 구성됩니다.

비밀 만들기 및 설정

setSecret 는 지정된 비밀 이름에 제공된 값을 할당합니다. 이름이 같은 비밀이 이미 있는 경우 새 버전의 비밀이 만들어집니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

비밀 가져오기

자격 증명 모음에서 비밀을 다시 읽는 가장 간단한 방법은 이름으로 비밀을 가져오는 것입니다. 그러면 비밀의 최신 버전이 검색됩니다. 선택적 매개 변수의 일부로 지정하는 경우 필요에 따라 다른 버전의 키를 가져올 수 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

특성을 사용하여 비밀 만들기 및 업데이트

비밀은 이름 및 값보다 더 많은 정보를 가질 수 있습니다. 다음 특성을 포함할 수도 있습니다.

  • tags: 비밀을 검색하고 필터링하는 데 사용할 수 있는 키-값 집합입니다.
  • contentType: 비밀의 수신자가 비밀 값을 사용하는 방법을 이해하는 데 사용할 수 있는 모든 문자열입니다.
  • enabled: 비밀 값을 읽을 수 있는지 여부를 결정하는 부울 값입니다.
  • notBefore: 비밀 값을 검색할 수 있는 지정된 날짜입니다.
  • expiresOn: 비밀 값을 검색할 수 없는 지정된 날짜입니다.

이러한 특성을 가진 개체는 다음과 같이 비밀의 이름과 값 바로 뒤에 있는 의 setSecret세 번째 매개 변수로 보낼 수 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

이렇게 하면 동일한 비밀의 새 버전이 만들어지며, 이 비밀에는 제공된 최신 특성이 포함됩니다.

특성은 다음과 같이 를 사용하여 기존 비밀 버전으로 updateSecretProperties업데이트할 수도 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

비밀 삭제

메서드는 beginDeleteSecret 비밀 삭제를 시작합니다. 이 프로세스는 필요한 리소스를 사용할 수 있는 즉시 백그라운드에서 발생합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Key Vault 일시 삭제를 사용하도록 설정한 경우 이 작업은 비밀에 삭제된 비밀로만 레이블을 지정합니다. 삭제된 비밀은 업데이트할 수 없습니다. 읽기, 복구 또는 제거만 가능합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

비밀은 완전히 삭제 beginDeleteSecret 되는 데 다소 시간이 걸리기 때문에 지침에 따라 기본 장기 실행 작업을 추적하는 Poller 개체를 반환합니다. https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

수신된 폴러를 사용하면 를 호출하여 삭제된 비밀을 가져올 수 있습니다 poller.getResult(). 비밀이 삭제될 때까지 개별 서비스 호출을 실행하거나 프로세스가 완료될 때까지 대기하여 삭제가 완료될 때까지 기다릴 수도 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

비밀이 완전히 삭제될 때까지 기다리는 또 다른 방법은 다음과 같이 개별 호출을 수행하는 것입니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const { delay } = require("@azure/core-util");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

비밀 목록 반복

SecretClient를 사용하여 Key Vault 모든 비밀과 삭제된 모든 비밀 및 특정 비밀 버전을 검색하고 반복할 수 있습니다. 다음 API 메서드를 사용할 수 있습니다.

  • listPropertiesOfSecrets 는 삭제되지 않은 모든 비밀을 최신 버전에서만 이름별로 나열합니다.
  • listDeletedSecrets 는 삭제된 모든 비밀을 최신 버전에서만 이름별로 나열합니다.
  • listPropertiesOfSecretVersions 는 비밀 이름을 기반으로 비밀의 모든 버전을 나열합니다.

다음과 같이 사용할 수 있습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

이러한 모든 메서드는 사용 가능한 모든 결과를 한 번에 반환합니다. 페이지별로 검색하려면 다음과 같이 사용하려는 API 메서드를 호출한 직후에 를 추가 .byPage() 합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

문제 해결

다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 문제 해결 가이드 를 참조하세요.

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

다음 단계

다음 링크를 통해 더 많은 코드 샘플을 찾을 수 있습니다.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions