azure-middy-keyvault-secrets

Azure Key Vault Secrets middleware for the azure-middy framework, the Node.js middleware engine for Azure functions.

Install

To install the this middleware, you can use NPM:

npm install --save @kevboutin/azure-middy-keyvault-secrets

Prerequisites

• Node.js >= 18
• An Azure Function App
• An Azure Key Vault instance
• Proper Azure credentials configured (using DefaultAzureCredential)

Usage

The middleware provides Azure Key Vault secrets management for your Azure Functions.

JavaScript (CommonJS)

const { app } = require("@azure/functions");
const middy = require("@kevboutin/azure-middy-core");
const {
    keyvaultSecretsMiddleware,
} = require("@kevboutin/azure-middy-keyvault-secrets");

// Your handler
const baseHandler = async (req, context) => {
    // Your business logic here
    // Secrets are available in req.internal
    return {
        body: JSON.stringify({ message: "Success" }),
    };
};

// Wrap handler with middy
const handler = middy(baseHandler).use(
    keyvaultSecretsMiddleware({
        vaultUrl: "https://your-vault.vault.azure.net",
        fetchData: {
            apiKey: "api-key-secret-name",
            dbPassword: "db-password-secret-name",
        },
        cacheKey: "my-secrets",
    }),
);

module.exports = { handler };

app.http("yourFunction", {
    route: "your-route",
    methods: ["GET"],
    authLevel: "anonymous",
    handler: handler,
});

TypeScript

import { app } from "@azure/functions";
import middy from "@kevboutin/azure-middy-core";
import {
    keyvaultSecretsMiddleware,
    KeyVaultSecretsOptions,
} from "@kevboutin/azure-middy-keyvault-secrets";
import type { AzureFunctionRequest } from "@kevboutin/azure-middy-types";

// Your handler
const baseHandler = async (req: AzureFunctionRequest, context: any) => {
    // Access secrets from the request internal object
    const apiKey = req.internal?.["apiKey"];
    const dbPassword = req.internal?.["dbPassword"];

    console.log("Retrieved secrets:", {
        hasApiKey: !!apiKey,
        hasDbPassword: !!dbPassword,
    });

    return {
        body: JSON.stringify({ message: "Success" }),
    };
};

// Configure Key Vault options with TypeScript
const keyVaultOptions: KeyVaultSecretsOptions = {
    vaultUrl: "https://your-vault.vault.azure.net",
    fetchData: {
        apiKey: "api-key-secret-name",
        dbPassword: "db-password-secret-name",
        jwtSecret: "jwt-signing-key",
    },
    cacheKey: "my-secrets",
};

// Wrap handler with middy
const handler = middy(baseHandler).use(
    keyvaultSecretsMiddleware(keyVaultOptions),
);

export { handler };

app.http("yourFunction", {
    route: "your-route",
    methods: ["GET"],
    authLevel: "anonymous",
    handler: handler,
});

TypeScript Support

This package includes full TypeScript support with:

• Type Definitions: Complete type definitions for all Key Vault interfaces and functions
• Type Safety: Full type checking for middleware options and request objects
• IntelliSense: Enhanced IDE support with autocomplete and type hints

Available Types

import {
    KeyVaultSecretsOptions,
    AzureFunctionRequest,
    KeyVaultSecretsMiddleware,
    CachedValues,
    FetchedValues,
} from "@kevboutin/azure-middy-keyvault-secrets";

TypeScript Configuration

To use TypeScript with this package, ensure your tsconfig.json includes:

{
    "compilerOptions": {
        "esModuleInterop": true,
        "moduleResolution": "node"
    }
}

API

keyvaultSecretsMiddleware(opts = {})

Creates a middleware instance with the following options:

• opts.vaultUrl (required): The URL of your Azure Key Vault (e.g., "https://your-vault.vault.azure.net")
• opts.fetchData (required): Object mapping of local names to Key Vault secret names
• opts.cacheKey (optional): Custom cache key for storing secrets (default: "secrets")

Authentication

The middleware uses DefaultAzureCredential from @azure/identity which supports multiple authentication methods:

1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
2. Managed Identity
3. Visual Studio Code credentials
4. Azure CLI credentials
5. Interactive browser login

For production, we recommend using Managed Identity or service principal credentials.

Caching

The middleware supports caching of secrets to reduce Key Vault API calls:

• Set cacheExpiry to the number of milliseconds to cache secrets
• Use cacheKey to specify a custom cache key if needed
• Cache is automatically invalidated after expiry
• Set cacheExpiry: 0 to disable caching

Security Considerations

1. Always use RBAC or Access Policies to limit Key Vault access
2. Consider enabling Key Vault soft-delete and purge protection
3. Monitor Key Vault access using Azure Monitor
4. Regularly rotate secrets
5. Use Managed Identity when possible

Documentation and examples

For more documentation and examples, refer to the main Azure-middy monorepo on GitHub.

Contributing

Everyone is very welcome to contribute to this repository. Feel free to raise issues or to submit Pull Requests.

License

Licensed under MIT License. Copyright (c) 2024 Kevin Boutin and the Azure-Middy team.