Azure Key Vault Keys SDK pour TypeScript

Gérez les clés cryptographiques avec Azure Key Vault.

Installation

# Keys SDK
npm install @azure/keyvault-keys @azure/identity

Variables d'environnement

KEY_VAULT_URL=https://<vault-name>.vault.azure.net
# Ou
AZURE_KEYVAULT_NAME=<vault-name>
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Authentification

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
import { KeyClient, CryptographyClient } from "@azure/keyvault-keys";

// Dev local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Ou utiliser directement une credential spécifique en production :
// Voir https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();
const vaultUrl = `https://${process.env.AZURE_KEYVAULT_NAME}.vault.azure.net`;

const keyClient = new KeyClient(vaultUrl, credential);
const secretClient = new SecretClient(vaultUrl, credential);

Opérations sur les secrets

Créer/Définir un secret

const secret = await secretClient.setSecret("MySecret", "secret-value");

// Avec des attributs
const secretWithAttrs = await secretClient.setSecret("MySecret", "value", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  contentType: "application/json",
  tags: { environment: "production" }
});

Récupérer un secret

// Récupérer la dernière version
const secret = await secretClient.getSecret("MySecret");
console.log(secret.value);

// Récupérer une version spécifique
const specificSecret = await secretClient.getSecret("MySecret", {
  version: secret.properties.version
});

Lister les secrets

for await (const secretProperties of secretClient.listPropertiesOfSecrets()) {
  console.log(secretProperties.name);
}

// Lister les versions
for await (const version of secretClient.listPropertiesOfSecretVersions("MySecret")) {
  console.log(version.version);
}

Supprimer un secret

// Suppression logicielle
const deletePoller = await secretClient.beginDeleteSecret("MySecret");
await deletePoller.pollUntilDone();

// Purger (suppression permanente)
await secretClient.purgeDeletedSecret("MySecret");

// Récupérer
const recoverPoller = await secretClient.beginRecoverDeletedSecret("MySecret");
await recoverPoller.pollUntilDone();

Opérations sur les clés

Créer des clés

// Clé générique
const key = await keyClient.createKey("MyKey", "RSA");

// Clé RSA avec taille
const rsaKey = await keyClient.createRsaKey("MyRsaKey", { keySize: 2048 });

// Clé de courbe elliptique
const ecKey = await keyClient.createEcKey("MyEcKey", { curve: "P-256" });

// Avec des attributs
const keyWithAttrs = await keyClient.createKey("MyKey", "RSA", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  tags: { purpose: "encryption" },
  keyOps: ["encrypt", "decrypt", "sign", "verify"]
});

Récupérer une clé

const key = await keyClient.getKey("MyKey");
console.log(key.name, key.keyType);

Lister les clés

for await (const keyProperties of keyClient.listPropertiesOfKeys()) {
  console.log(keyProperties.name);
}

Faire tourner une clé

// Rotation manuelle
const rotatedKey = await keyClient.rotateKey("MyKey");

// Définir la politique de rotation
await keyClient.updateKeyRotationPolicy("MyKey", {
  lifetimeActions: [{ action: "Rotate", timeBeforeExpiry: "P30D" }],
  expiresIn: "P90D"
});

Supprimer une clé

const deletePoller = await keyClient.beginDeleteKey("MyKey");
await deletePoller.pollUntilDone();

// Purger
await keyClient.purgeDeletedKey("MyKey");

Opérations cryptographiques

Créer un CryptographyClient

import { CryptographyClient } from "@azure/keyvault-keys";

// À partir d'un objet clé
const cryptoClient = new CryptographyClient(key, credential);

// À partir d'un ID de clé
const cryptoClient = new CryptographyClient(key.id!, credential);

Chiffrer/Déchiffrer

// Chiffrer
const encryptResult = await cryptoClient.encrypt({
  algorithm: "RSA-OAEP",
  plaintext: Buffer.from("My secret message")
});

// Déchiffrer
const decryptResult = await cryptoClient.decrypt({
  algorithm: "RSA-OAEP",
  ciphertext: encryptResult.result
});

console.log(decryptResult.result.toString());

Signer/Vérifier

import { createHash } from "node:crypto";

// Créer un digest
const hash = createHash("sha256").update("My message").digest();

// Signer
const signResult = await cryptoClient.sign("RS256", hash);

// Vérifier
const verifyResult = await cryptoClient.verify("RS256", hash, signResult.result);
console.log("Valid:", verifyResult.result);

Encapsuler/Décapsuler des clés

// Encapsuler une clé (la chiffrer pour le stockage)
const wrapResult = await cryptoClient.wrapKey("RSA-OAEP", Buffer.from("key-material"));

// Décapsuler
const unwrapResult = await cryptoClient.unwrapKey("RSA-OAEP", wrapResult.result);

Sauvegarde et restauration

// Sauvegarde
const keyBackup = await keyClient.backupKey("MyKey");
const secretBackup = await secretClient.backupSecret("MySecret");

// Restaurer (peut restaurer vers un coffre différent)
const restoredKey = await keyClient.restoreKeyBackup(keyBackup!);
const restoredSecret = await secretClient.restoreSecretBackup(secretBackup!);

Types de clés

import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
  CryptographyClient,
  KnownEncryptionAlgorithms,
  KnownSignatureAlgorithms
} from "@azure/keyvault-keys";

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
  DeletedSecret
} from "@azure/keyvault-secrets";

Gestion des erreurs

try {
  const secret = await secretClient.getSecret("NonExistent");
} catch (error: any) {
  if (error.code === "SecretNotFound") {
    console.log("Secret does not exist");
  } else {
    throw error;
  }
}

Bonnes pratiques

1. Utiliser DefaultAzureCredential pour le développement local ; utiliser ManagedIdentityCredential ou WorkloadIdentityCredential pour la production
2. Activer la suppression logicielle - Requise pour les coffres en production
3. Définir des dates d'expiration - Sur les clés et les secrets
4. Utiliser les politiques de rotation des clés - Automatiser la rotation des clés
5. Limiter les opérations sur les clés - N'accorder que les opérations nécessaires (chiffrer, signer, etc.)
6. Navigation web non supportée - Ces SDK sont Node.js uniquement