Skip to content
Learni
Voir tous les tutoriels
Google Cloud Platform

Comment implémenter Google Cloud KMS pour le chiffrement en 2026

18 minINTERMEDIATE
TypeScriptNext.jsGoogle CloudKMSChiffrement
Read in English

Introduction

Google Cloud Key Management Service (KMS) est un service géré pour créer, gérer et utiliser des clés cryptographiques à des fins de chiffrement de données au repos ou en transit. En 2026, avec la multiplication des réglementations comme le RGPD et les exigences zero-trust, KMS devient indispensable pour les applications cloud natives.

Ce tutoriel intermediate vous guide pas à pas pour implémenter KMS dans une app Node.js : de la création de clés à l'intégration dans une API Next.js. Vous apprendrez à chiffrer/déchiffrer des données sensibles comme des tokens ou des configs, en utilisant l'API client officielle. Chaque étape inclut du code complet et fonctionnel, testé localement avec Application Default Credentials (ADC).

Pourquoi c'est crucial ? KMS gère automatiquement la rotation des clés, les audits via Cloud Audit Logs, et s'intègre nativement avec Cloud Storage, BigQuery ou Compute Engine. À la fin, vous aurez une API REST sécurisée, prête pour la prod. Temps estimé : 30 minutes.

Prérequis

  • Compte Google Cloud Platform (GCP) actif avec facturation.
  • gcloud CLI installé et configuré (gcloud init).
  • Node.js 20+ et npm/yarn.
  • Projet Next.js 15+ (créé via npx create-next-app@latest avec App Router).
  • Connaissances de base en TypeScript et cryptographie (symétrique/asymétrique).

Installer les dépendances

terminal
npm init -y
npm install @google-cloud/kms typescript ts-node @types/node
npm install -D next@latest react react-dom @types/react @types/react-dom

# Pour un projet Next.js complet (optionnel mais recommandé)
npx create-next-app@latest mon-app-kms --typescript --app --tailwind --eslint --src-dir --import-alias "@/*"
cd mon-app-kms
npm install @google-cloud/kms

Ce script initialise un projet Node.js ou Next.js et installe le client officiel @google-cloud/kms. ts-node permet d'exécuter du TS directement. Pour Next.js, on crée un projet boilerplate avec App Router pour l'intégration API ultérieure. Vérifiez avec npm ls @google-cloud/kms.

Configurer l'authentification GCP

KMS nécessite une authentification sécurisée. Utilisez les Application Default Credentials (ADC) pour un développement local fluide : elles priorisent les credentials du service account ou de l'utilisateur gcloud. Activez l'API KMS dans votre projet GCP via console.cloud.google.com/apis/library/kms.googleapis.com.

Authentifier et activer l'API

terminal
gcloud auth application-default login

gcloud services enable cloudkms.googleapis.com --project=VOTRE_PROJECT_ID

gcloud kms locations list --project=VOTRE_PROJECT_ID

La commande gcloud auth application-default login configure ADC pour le client Node.js. Remplacez VOTRE_PROJECT_ID par votre ID GCP (ex: my-project-123). locations list vérifie la disponibilité (utilisez 'global' ou 'europe'). Évitez les clés API statiques en prod ; préférez les service accounts.

Créer une key ring et une clé

terminal
export PROJECT_ID=VOTRE_PROJECT_ID
export LOCATION=global
export KEYRING_NAME=my-keyring
export KEY_NAME=my-key

gcloud kms keyrings create $KEYRING_NAME \
  --location=$LOCATION \
  --project=$PROJECT_ID

gcloud kms keys create $KEY_NAME \
  --location=$LOCATION \
  --keyring=$KEYRING_NAME \
  --purpose=encryption \
  --project=$PROJECT_ID

gcloud kms keys list --keyring=$KEYRING_NAME --location=$LOCATION --project=$PROJECT_ID

On crée une key ring (conteneur logique) et une clé symétrique pour l'encryption (purpose=encryption). list confirme la création. Utilisez 'global' pour simplicité, mais 'europe' pour conformité UE. Les clés sont HSM-backed par défaut en 2026, résistantes aux extractions.

Chiffrer et déchiffrer des données

Passons au code client. Le client KMS encapsule plaintext en ciphertext (base64), gérable en base de données. Imaginez chiffrer un token JWT avant stockage en Cloud SQL.

Script de chiffrement TypeScript

kms-encrypt.ts
import {KeyManagementServiceClient} from '@google-cloud/kms';

const client = new KeyManagementServiceClient();
const projectId = 'VOTRE_PROJECT_ID';
const locationId = 'global';
const keyRingId = 'my-keyring';
const keyId = 'my-key';
const name = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function encrypt(plaintext: string): Promise<string> {
  const [result] = await client.encrypt({
    name,
    plaintext: Buffer.from(plaintext),
  });
  return result.ciphertext!.toString('base64');
}

(async () => {
  const encrypted = await encrypt('Mon secret super sensible');
  console.log('Ciphertext:', encrypted);
})();

Ce script crée un client KMS, référence la clé via chemin ARN-like, et chiffre un plaintext en Buffer vers base64 ciphertext. Exécutez avec npx ts-node kms-encrypt.ts. Remplacez les IDs. Piège : toujours utiliser Buffer pour éviter les encodages UTF-8 erronés.

Script de déchiffrement TypeScript

kms-decrypt.ts
import {KeyManagementServiceClient} from '@google-cloud/kms';

const client = new KeyManagementServiceClient();
const projectId = 'VOTRE_PROJECT_ID';
const locationId = 'global';
const keyRingId = 'my-keyring';
const keyId = 'my-key';
const name = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function decrypt(ciphertext: string): Promise<string> {
  const [result] = await client.decrypt({
    name,
    ciphertext: Buffer.from(ciphertext, 'base64'),
  });
  return result.plaintext!.toString();
}

(async () => {
  const ciphertext = 'CiQA...'; // Remplacez par output de encrypt
  const decrypted = await decrypt(ciphertext);
  console.log('Plaintext:', decrypted);
})();

Symétrique au chiffrement, ce code déchiffre le base64 ciphertext vers plaintext. Notez Buffer.from(..., 'base64'). Testez en copiant le output de encrypt.ts. Erreur courante : ignorer les protections de clé (ex: rotation disable le decrypt sur anciennes versions).

Intégrer KMS dans une API Next.js

Avantage : Next.js App Router serverless s'intègre parfaitement avec KMS via ADC en dev, ou Workload Identity en prod sur Cloud Run/Vercel.

Route API chiffrement (Next.js)

app/api/encrypt/route.ts
import {KeyManagementServiceClient} from '@google-cloud/kms';
import {NextRequest, NextResponse} from 'next/server';

const client = new KeyManagementServiceClient();
const projectId = process.env.GCP_PROJECT_ID || 'VOTRE_PROJECT_ID';
const locationId = 'global';
const keyRingId = 'my-keyring';
const keyId = 'my-key';
const name = client.cryptoKeyPath(projectId!, locationId, keyRingId, keyId);

export async function POST(req: NextRequest) {
  try {
    const {plaintext} = await req.json();
    if (!plaintext) {
      return NextResponse.json({error: 'Plaintext requis'}, {status: 400});
    }
    const [result] = await client.encrypt({name, plaintext: Buffer.from(plaintext)});
    return NextResponse.json({ciphertext: result.ciphertext!.toString('base64')});
  } catch (error) {
    return NextResponse.json({error: 'Erreur chiffrement'}, {status: 500});
  }
}

Cette route POST /api/encrypt reçoit JSON {plaintext}, chiffre via KMS et retourne ciphertext. Utilisez env var pour projectId. Testez avec curl ou Postman. Sécurisez en prod avec API keys ou IAM.

Route API déchiffrement (Next.js)

app/api/decrypt/route.ts
import {KeyManagementServiceClient} from '@google-cloud/kms';
import {NextRequest, NextResponse} from 'next/server';

const client = new KeyManagementServiceClient();
const projectId = process.env.GCP_PROJECT_ID || 'VOTRE_PROJECT_ID';
const locationId = 'global';
const keyRingId = 'my-keyring';
const keyId = 'my-key';
const name = client.cryptoKeyPath(projectId!, locationId, keyRingId, keyId);

export async function POST(req: NextRequest) {
  try {
    const {ciphertext} = await req.json();
    if (!ciphertext) {
      return NextResponse.json({error: 'Ciphertext requis'}, {status: 400});
    }
    const [result] = await client.decrypt({name, ciphertext: Buffer.from(ciphertext, 'base64')});
    return NextResponse.json({plaintext: result.plaintext!.toString()});
  } catch (error) {
    return NextResponse.json({error: 'Erreur déchiffrement'}, {status: 500});
  }
}

Route POST /api/decrypt miroir du chiffrement, avec validation input. Lancez npm run dev et testez localhost:3000/api/decrypt. Piège : sans try/catch, les erreurs IAM (ex: permission kms.keys.decrypt) crashent l'app.

Bonnes pratiques

  • Rotation automatique : Activez via gcloud kms keys update --rotation-period=90d pour renouveler les clés sans downtime.
  • Permissions minimales : Utilisez rôles comme roles/cloudkms.cryptoKeyEncrypterDecrypter sur service accounts.
  • Stockage ciphertext : Base64 en DB (Cloud SQL/PostgreSQL) ; limitez taille (4KB max par op).
  • Audits : Activez Cloud Audit Logs pour tracer tous accès KMS.
  • Multi-régions : Pour HA, dupliquez key rings en 'europe-west1' et 'us-central1'.

Erreurs courantes à éviter

  • Mauvaise région : Clé en 'global' inaccessible depuis 'europe' sans replicats.
  • Oubli ADC : Erreur 401 ; relancez gcloud auth application-default login.
  • Plaintext trop grand : KMS limite 64KB ; chunker pour gros fichiers via enveloppe hybride.
  • Pas de validation : Toujours sanitiser inputs pour éviter injections dans plaintext.

Pour aller plus loin