Azure Key Vault Secret client library for JavaScript - version 4.11.1

Azure Key Vault는 보안 키를 사용해 인증 키, 스토리지 계정 키, 데이터 암호화 키, .pfx 파일, 비밀번호를 암호화할 수 있는 서비스입니다. Azure Key Vault에 대해 더 알고 싶으시다면, Azure Key Vault이란 무엇인가요?

Azure Key Vault 비밀 관리는 토큰, 비밀번호, 인증서, API 키 및 기타 비밀에 대한 접근을 안전하게 저장하고 엄격히 제어할 수 있게 해줍니다.

Node.js 애플리케이션에서 Azure Key Vault 시크릿을 위한 클라이언트 라이브러리를 활용해 다음을 수행하세요:

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

참고: 이 패키지는 Azure Key Vault 서비스 제한으로 브라우저에서 사용할 수 없으니, 안내를 위해 이 문서를 참고해 주세요.

키 링크:

시작하기

현재 지원되는 환경

Node.js의 LTS 버전

필수 조건

Azure 구독
Key Vault 자료
기존의 Azure Key Vault. 키 금고를 생성해야 한다면, 이 문서의 단계를 따라 Azure Portal에서 만들 수 있습니다. 또는 이 문서의 단계를 따라 Azure CLI을 사용할 수도 있습니다.

패키지 설치

npm을 사용하여 Azure Key Vault Secret 클라이언트 라이브러리를 설치하세요:

npm install @azure/keyvault-secrets

ID 라이브러리 설치

Key Vault 클라이언트는 Azure Identity Library를 통해 인증합니다. npm을 사용하여 설치

npm install @azure/identity

TypeScript 구성

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

npm install @types/node

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

주요 개념

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

Azure Active Directory로 인증하기

Key Vault 서비스는 Azure Active Directory를 통해 API에 대한 요청을 인증합니다. @azure/identity 패키지는 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 유형을 제공합니다. 의 README에는 시작하는 데 도움이 되는 더 많은 세부사항과 샘플이 포함되어 있습니다.

Azure Key Vault 서비스와 상호작용하려면 SecretClient 클래스 인스턴스, vault url 그리고 자격 증명 객체를 생성해야 합니다. 이 문서에 표시된 예제에서는 로컬 개발 및 프로덕션 환경을 비롯한 대부분의 시나리오에 적합한 DefaultAzureCredential자격 증명 개체를 사용합니다. 또한 프로덕션 환경에서 인증에 관리 ID 사용하는 것이 좋습니다.

인증의 다양한 방법과 그에 따른 자격 증명 유형에 대한 자세한 정보는 Azure 신원 문서에서 확인할 수 있습니다.

다음은 빠른 예입니다. 먼저 DefaultAzureCredential 가져오고 SecretClient. 이 자료들이 임포트되면 다음으로 Key Vault 서비스에 연결할 수 있습니다:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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);

브라우저 환경의 경우 InteractiveBrowserCredential 패키지의 @azure/identity 사용하여 인증합니다.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Specifying the Azure Key Vault service API version

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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`;

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

예시

다음 섹션에서는 Azure Key Vault Secrets를 사용하는 일반적인 작업 일부를 다루는 코드 스니펫을 제공합니다. 여기서 다루는 시나리오는 다음으로 구성됩니다.

비밀만들고 설정합니다.
비밀가져옵니다.
특성을 사용하여 비밀을 만들고 업데이트합니다.
비밀삭제합니다.
비밀 반복 목록을.

비밀 만들기 및 설정

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

비밀 가져오기

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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,
);

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

비밀 삭제

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

soft-delete가 Key Vault에 활성화되어 있다면, 이 연산은 deleted 비밀로만 라벨을 붙입니다. 삭제된 비밀은 업데이트할 수 없습니다. 읽기, 복구 또는 제거만 가능합니다.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

비밀 목록 반복

SecretClient를 사용하면 Key Vault 내의 모든 비밀뿐만 아니라 삭제된 비밀과 특정 비밀의 버전도 모두 검색하고 반복할 수 있습니다. 사용할 수 있는 API 메서드는 다음과 같습니다.

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

문제 해결

다양한 고장 시나리오 진단 방법에 대한 자세한 내용은 troubleshooting guide를 참고하세요.

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

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

setLogLevel("info");

다음 단계

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

기여하기

이 라이브러리에 기여하고 싶으시다면, 코드 빌드 및 테스트 방법에 대해 더 알고 싶다면 기여 가이드를 읽어보시기 바랍니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-09