빠른 시작: JavaScript용 Azure Key Vault 인증서 클라이언트 라이브러리

아티클
10/05/2024

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

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

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

Key Vault 및 인증서에 대한 자세한 내용은 다음을 참조하세요.

필수 조건

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

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

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

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

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

새 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-certificates)를 설치합니다.
```
npm install @azure/keyvault-certificates
```
Azure ID 클라이언트 라이브러리인 @azure/identity를 설치하여 Key Vault에 인증합니다.
```
npm install @azure/identity
```

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

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

az role assignment create --role "Key Vault Certificate 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 { CertificateClient, DefaultCertificatePolicy } = require("@azure/keyvault-certificates");
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 CertificateClient(keyVaultUrl, credential);

  const uniqueString = new Date().getTime();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  const pendingCertificate = createPoller.getResult();
  console.log("Certificate: ", pendingCertificate);

  // To read a certificate with their policy:
  let certificateWithPolicy = await client.getCertificate(certificateName);
  // Note: It will always read the latest version of the certificate.

  console.log("Certificate with policy:", certificateWithPolicy);

  // To read a certificate from a specific version:
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version
  );
  // Note: It will not retrieve the certificate's policy.
  console.log("Certificate from a specific version:", certificateFromVersion);

  const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
    tags: {
      customTag: "value"
    }
  });
  console.log("Updated certificate:", updatedCertificate);

  // Updating the certificate's policy:
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyOtherCert"
  });
  certificateWithPolicy = await client.getCertificate(certificateName);
  console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);

  // delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  console.log("Recovery Id: ", deletedCertificate.recoveryId);
  console.log("Deleted Date: ", deletedCertificate.deletedOn);
  console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
}

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

샘플 애플리케이션 실행

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

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

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

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

import {
  CertificateClient,
  DefaultCertificatePolicy,
  KeyVaultCertificate,
  DeletedCertificate,
  CertificatePolicy,
  KeyVaultCertificateWithPolicy,
} from "@azure/keyvault-certificates";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

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 printCertificate(
  certificate: KeyVaultCertificate | KeyVaultCertificateWithPolicy
): void {
  console.log("-- printCertificate ---------------------------");

  // if policy is defined, it's a KeyVaultCertificateWithPolicy
  if ((certificate as KeyVaultCertificateWithPolicy).policy) {
    const { name, properties, policy } =
      certificate as KeyVaultCertificateWithPolicy;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    console.log("Certificate Policy: ", policy);
    printObjectProperties(tags);
    return;
  } else {
    const { name, properties } = certificate;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    printObjectProperties(tags);
  }
}
// Object properties are tags and CertificatePolicy
function printObjectProperties(obj: Record<string, any>): void {
  if (!obj) return;

  console.log("-- printObjectProperties ---------------------------");

  Object.entries(obj).forEach(([key, value]) => {
    if (key === "lifetimeActions") {
      console.log(`${key}: ${JSON.stringify(value)}`);
    } else {
      console.log(`${key}: ${value}`);
    }
  });
}
function printDeletedCertificate(deletedCertificate: DeletedCertificate): void {
  const { recoveryId, deletedOn, scheduledPurgeDate } = deletedCertificate;
  console.log("Deleted Certificate: ", {
    recoveryId,
    deletedOn,
    scheduledPurgeDate,
  });
}
async function main(): Promise<void> {
  // Create a new CertificateClient
  const client = new CertificateClient(keyVaultUrl, credential);

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

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  // Get the created certificate
  const pendingCertificate = await createPoller.getResult();
  printCertificate(pendingCertificate);

  // Get certificate by name
  let certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(pendingCertificate);

  // Get certificate by version
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version!
  );
  printCertificate(certificateFromVersion);

  // Update properties of the certificate
  const updatedCertificate = await client.updateCertificateProperties(
    certificateName,
    certificateWithPolicy.properties.version!,
    {
      tags: {
        customTag: "my value",
      },
    }
  );
  printCertificate(updatedCertificate);

  // Updating the certificate's policy
  const certificatePolicy = await client.updateCertificatePolicy(
    certificateName,
    {
      issuerName: "Self",
      subject: "cn=MyOtherCert",
    }
  );
  printObjectProperties(certificatePolicy);

  // Get certificate again to see the updated policy
  certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(certificateWithPolicy);

  // Delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  printDeletedCertificate(deletedCertificate);
}

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

샘플 애플리케이션 실행

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

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

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

App Configuration과 통합

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

다음 단계

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

Azure Key Vault 개요 참조
인증서 개요 읽기
App Service 애플리케이션에서 Key Vault 액세스 자습서 참조
Virtual Machine에서 Key Vault 액세스 자습서 참조
Azure Key Vault 개발자 가이드 참조
Azure Key Vault 보안 개요를 검토하세요.

다음을 통해 공유

빠른 시작: JavaScript용 Azure Key Vault 인증서 클라이언트 라이브러리

필수 조건

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

Key Vault 패키지 설치

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

환경 변수 설정

클라이언트 인증 및 만들기

코드 예

앱 프레임워크 설정

샘플 애플리케이션 실행

샘플 애플리케이션 실행

App Configuration과 통합

다음 단계

피드백

추가 리소스

다음을 통해 공유

빠른 시작: JavaScript용 Azure Key Vault 인증서 클라이언트 라이브러리

필수 조건

Azure에 로그인

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

Key Vault 패키지 설치

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

환경 변수 설정

클라이언트 인증 및 만들기

코드 예

앱 프레임워크 설정

샘플 애플리케이션 실행

샘플 애플리케이션 실행

App Configuration과 통합

다음 단계

피드백

추가 리소스