0Pricing
NestJS Enterprise Backend APIs · Lesson

Loading Secrets from HashiCorp Vault and AWS SSM

Pull runtime secrets from external stores using async config factories and custom loaders.

Loading Secrets from HashiCorp Vault and AWS SSM is a free NestJS Enterprise Backend APIs lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the NestJS Enterprise Backend APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Pull Secrets at Runtime?

Hardcoding API keys and DB passwords in .env files works for a single laptop, but it falls apart at enterprise scale.

  • Rotation: security teams rotate credentials frequently; baking them into images means a redeploy on every rotation.
  • Auditing: central stores like HashiCorp Vault and AWS SSM Parameter Store log who read which secret and when.
  • Least privilege: each service authenticates with its own identity and only sees the secrets it needs.

In this lesson we wire NestJS's ConfigModule to fetch secrets asynchronously at boot from these external stores using custom loaders.

The Async Config Factory Pattern

NestJS's ConfigModule normally loads from static files. To reach a network store we need code that runs before the rest of the app, returning a plain object of resolved values.

That code is a custom loader — an async function passed to ConfigModule.forRoot({ load: [...] }). Nest awaits each loader and merges the results into the config namespace.

Key rule: a loader must fully resolve its promise before the module finishes initializing, so every downstream provider sees fully-populated config.

// config/config.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { vaultLoader } from './loaders/vault.loader';
import { ssmLoader } from './loaders/ssm.loader';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      // each loader is an async () => Record<string, unknown>
      load: [vaultLoader, ssmLoader],
    }),
  ],
})
export class AppConfigModule {}

Anatomy of a Custom Loader

A loader is just an async function returning an object. The keys become config paths you read later with configService.get('database.password').

Best practices:

  • Group secrets under a namespace key (database, jwt) so reads are predictable.
  • Convert and validate types here — external stores return everything as strings.
  • Throw on missing critical secrets so the app fails fast at boot, not mid-request.
// loaders/example.loader.ts
export const exampleLoader = async () => {
  const raw = await fetchFromStore(); // returns string map
  if (!raw.DB_PASSWORD) {
    throw new Error('Missing DB_PASSWORD from secret store');
  }
  return {
    database: {
      host: raw.DB_HOST ?? 'localhost',
      port: Number(raw.DB_PORT ?? 5432),
      password: raw.DB_PASSWORD,
    },
  };
};

async function fetchFromStore() {
  // placeholder for the real Vault/SSM call
  return {} as Record<string, string>;
}

How Vault Stores Secrets

HashiCorp Vault exposes secrets over an HTTP API. The common KV v2 engine stores versioned key-value pairs at a path like secret/data/myapp/database.

To read, a client sends a token in the X-Vault-Token header and receives JSON shaped like { data: { data: { ... } } } — note the double data nesting unique to KV v2.

In production the token usually comes from an AppRole login (a role id + secret id exchanged for a short-lived token), not a static root token.

A Vault Loader with AppRole Login

This loader first exchanges an AppRole roleId/secretId for a client token, then reads a KV v2 path. We use the built-in fetch available in Node 18+.

Notice how we unwrap the double data nesting and namespace the result under vault.

// loaders/vault.loader.ts
export const vaultLoader = async () => {
  const addr = process.env.VAULT_ADDR!;

  // 1) AppRole login -> short-lived client token
  const login = await fetch(`${addr}/v1/auth/approle/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      role_id: process.env.VAULT_ROLE_ID,
      secret_id: process.env.VAULT_SECRET_ID,
    }),
  });
  const { auth } = await login.json();

  // 2) Read KV v2 secret using the issued token
  const res = await fetch(`${addr}/v1/secret/data/myapp/database`, {
    headers: { 'X-Vault-Token': auth.client_token },
  });
  const body = await res.json();
  const kv = body.data.data; // KV v2 double nesting

  return {
    database: {
      host: kv.host,
      port: Number(kv.port),
      password: kv.password,
    },
  };
};

How AWS SSM Parameter Store Works

AWS SSM Parameter Store holds parameters by name, e.g. /myapp/prod/db-password. Secrets use type SecureString, encrypted with a KMS key.

  • GetParametersByPath fetches every parameter under a prefix in one call — ideal for loading a whole namespace.
  • Pass WithDecryption: true to receive plaintext values (your IAM role needs kms:Decrypt).
  • Authentication is automatic via the instance/task IAM role — no token to manage.

An SSM Loader by Path

This loader pulls every parameter under /myapp/prod and strips the prefix to build clean keys. We page through results because GetParametersByPath caps each response and returns a NextToken.

// loaders/ssm.loader.ts
import { SSMClient, GetParametersByPathCommand } from '@aws-sdk/client-ssm';

export const ssmLoader = async () => {
  const client = new SSMClient({ region: process.env.AWS_REGION });
  const prefix = '/myapp/prod/';
  const out: Record<string, string> = {};
  let NextToken: string | undefined;

  do {
    const res = await client.send(
      new GetParametersByPathCommand({
        Path: prefix,
        Recursive: true,
        WithDecryption: true,
        NextToken,
      }),
    );
    for (const p of res.Parameters ?? []) {
      const key = p.Name!.replace(prefix, '');
      out[key] = p.Value!;
    }
    NextToken = res.NextToken;
  } while (NextToken);

  return {
    jwt: { secret: out['jwt-secret'] },
    database: { password: out['db-password'] },
  };
};

Merging Loaders & Precedence

When you list multiple loaders in load: [vaultLoader, ssmLoader], Nest deep-merges their returned objects. Loaders later in the array win on key conflicts.

This lets you layer sources: a base loader for defaults, then an override loader for environment-specific secrets. Plan the order intentionally — accidental overrides are a common bug.

The merge is a simple example of how last-write-wins resolves overlapping keys:

function deepMerge(target: any, source: any): any {
  for (const key of Object.keys(source)) {
    if (
      source[key] && typeof source[key] === 'object' &&
      !Array.isArray(source[key])
    ) {
      target[key] = deepMerge(target[key] ?? {}, source[key]);
    } else {
      target[key] = source[key]; // later source wins
    }
  }
  return target;
}

const base = { db: { host: 'localhost', port: 5432 } };
const override = { db: { host: 'prod-db', password: 's3cr3t' } };
console.log(deepMerge(base, override));
// { db: { host: 'prod-db', port: 5432, password: 's3cr3t' } }

Validating Loaded Secrets

External stores fail in surprising ways — a typo'd path returns nothing, a rotated secret may be empty. Validate the merged config with a schema so the app refuses to start when something critical is missing.

NestJS supports a validate function in forRoot. Here we use a lightweight check, but Joi or class-validator are common in production.

// config/validate.ts
export function validateConfig(config: Record<string, any>) {
  const required = [
    ['database', 'password'],
    ['jwt', 'secret'],
  ];
  for (const [ns, key] of required) {
    if (!config[ns]?.[key]) {
      throw new Error(`Missing required secret: ${ns}.${key}`);
    }
  }
  return config; // must return the validated config
}

Consuming Secrets in Providers

Once loaders have run, any provider injects ConfigService and reads namespaced values. Because loading was async at boot, reads are synchronous and cheap — no network call per request.

For modules that themselves need config (like TypeORM), use the forRootAsync + useFactory pattern so they receive resolved secrets.

// database/database.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get<string>('database.host'),
        port: config.get<number>('database.port'),
        password: config.get<string>('database.password'),
        autoLoadEntities: true,
      }),
    }),
  ],
})
export class DatabaseModule {}

Caching, TTL, and Rotation

Loaders run once at boot, so a value rotated in Vault won't reach a long-running pod until restart. Strategies to handle rotation:

  • Lease-aware refresh: Vault dynamic secrets carry a TTL; a background job renews or re-fetches before expiry.
  • Sidecar injection: tools like Vault Agent or AWS Secrets Manager rotation write fresh values to a file/env the app watches.
  • Rolling restart: simplest for static KV secrets — redeploy on rotation.

Avoid fetching secrets on every request — it adds latency and can hit store rate limits. Cache in memory with an explicit, bounded TTL instead.

Quick Check: Loader Behavior

Test your understanding of async config loaders in NestJS.

Recap & Takeaways

You learned how to load runtime secrets from external stores into NestJS:

  • Custom loaders are async functions passed to ConfigModule.forRoot({ load }); they fully resolve before providers initialize.
  • Vault (KV v2) is read over HTTP with an AppRole-issued token; remember the double data nesting.
  • AWS SSM uses GetParametersByPath with WithDecryption and IAM-role auth; page through NextToken.
  • Loaders are deep-merged with last-write-wins, so order matters.
  • Validate merged config to fail fast, and plan a rotation strategy since loaders run only at boot.

With these patterns your services authenticate with their own identity, never ship plaintext secrets in images, and stay auditable at scale.

Frequently asked questions

Is the “Loading Secrets from HashiCorp Vault and AWS SSM” lesson free?

Yes — the full text of “Loading Secrets from HashiCorp Vault and AWS SSM” is free to read here on the web, and the NestJS Enterprise Backend APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the NestJS Enterprise Backend APIs course, upgrade to CoddyKit PRO.

What will I learn in “Loading Secrets from HashiCorp Vault and AWS SSM”?

Pull runtime secrets from external stores using async config factories and custom loaders. You practise NestJS Enterprise Backend APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start NestJS Enterprise Backend APIs?

No prior experience is required. NestJS Enterprise Backend APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Loading Secrets from HashiCorp Vault and AWS SSM” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this NestJS Enterprise Backend APIs lesson?

Yes. Every NestJS Enterprise Backend APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Schema-Validated Env with Joi and forRoot
  2. Namespaced Config with registerAs
  3. Loading Secrets from HashiCorp Vault and AWS SSM
  4. Per-Environment Config and Safe Defaults
← Back to NestJS Enterprise Backend APIs