dotenv-azure

Load environment variables from Azure's services App Configuration, Key Vault or a .env file with an api similar to dotenv.

Why

Maybe you want to securely store secrets in Azure Key Vault, but you also have configurations and feature flags stored in Azure App Configuration and you have to override some of those configurations with a .env file when running your app locally.

Or you have a complex configuration data that you want to centralize it somewhere. Azure recommends the usage of App Config for configuration and Key Vault for secrets. You can read more about it here.

With dotenv-azure you can easily retrieve your app's configurations and secrets from these 3 sources and merge them into process.env.

If you would like to know more about App Configuration and Key Vault, you may want to review What is App Configuration? and What is Azure Key Vault?

Getting started

Install the package

Install with npm

npm install dotenv-azure

or with yarn

yarn add dotenv-azure

Configuring App Configuration

1. Create an app configuration store via Azure portal or CLI.
2. Set AZURE_APP_CONFIG_CONNECTION_STRING as environment variable using bash or put them in a .env file:

AZURE_APP_CONFIG_CONNECTION_STRING="generated-app-config-conneciton-string"

Configuring Key Vault

If you want to use Key Vault alongside with App Configuration you have to create a service principal and configure its access to Azure resources. You can follow this guide.

Once you have AZURE_CLIENT_ID(appId), AZURE_CLIENT_SECRET(password) and AZURE_TENANT_ID(tenant) you have to set them as environment variables. You can do this with export in Bash or put them in a .env file:

In production, if you are using Azure Managed Identities, you don't have to set these variables.

AZURE_CLIENT_ID="generated-app-ID"
AZURE_CLIENT_SECRET="random-password"
AZURE_TENANT_ID="tenant-ID"

If you have a configuration in App Configuration with the content type application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8 then dotenv-azure will try to load it from Key Vault.

You can add a Key Vault reference to App Configuration in the Azure portal:

1. Sign in to the Azure portal. Select All resources, and then select the App Configuration store instance that you created in the quickstart
2. Select Configuration Explorer
3. Select + Create > Key vault reference

Now when you call the .config() method, the value of your key vault secret will be set to process.env:

const { DotenvAzure } = require('dotenv-azure')

async function main() {
  await new DotenvAzure().config()
  console.log(process.env.DATABASE_URL) // prints your secret value
}

main()

Using dotenv-azure programmatically

You should call dotenv-azure before the initialization of your app. Since the method .config() returns a promise, you have to call it inside an async function:

const { DotenvAzure } = require('dotenv-azure')

async function main() {
  const dotenvAzure = new DotenvAzure()
  const { parsed } = await dotenvAzure.config()

  // `parsed` is an object containing:
  //   - Your App Config configurations
  //   - Key Vault secrets
  //   - Environment variables defined in a .env file
  //   - and environment variables that weren't overwritten
  console.log(parsed)

  // process.env now has the keys and values from the parsed result
  console.log(process.env)

  // start app
  // ...
}

main()

Preload dotenv-azure

You can use the --require (-r) command line option to preload dotenv-azure. By doing this, you do not need to require and load dotenv-azure in your application code.

node -r dotenv-azure/config your_script.js

To enable safe mode you should require config-safe:

node -r dotenv-azure/config-safe your_script.js

Rules

dotenv-azure uses dotenv under the covers, so the same rules for .env files apply here as well.

When populating process.env dotenv-azure will follow these steps:

1. Values within the process's environment (i.e. an environment variable exists) takes precedence over everything else.
2. For values defined in the .env file, and not present in the environemnt, process.env will be populated with those values.
3. dotenv-azure will search for the required environment variables to access azure's services after loading variables from the .env file.
4. For values defined within the process's environment, in the .env file or in the Azure App Configuration, where the value is prefixed with kv: what follows is assumed to be the secret identifier of a secret stored in Key Vault, and so dotenv-azure will attempt to populate the value from Key Vault.

Options

You can pass a safe option to validate your variables from a .env.example file like dotenv-safe:

const { DotenvAzure } = require('dotenv-azure')
const dotenvAzure = new DotenvAzure()

async function main() {
  await dotenvAzure.config({
    safe: true,
    allowEmptyValues: true,
    example: './.my-env-example-filename',
  })
}

main()

.config() and .parse() have the same options as dotenv and dotenv-safe

Documentation

You can read the api documentation here.

Inspirations

• dotenv
• dotenv-safe
• dotenv-keyvault

Contributors

This project follows the all-contributors specification. Contributions of any kind are welcome!

Daniel Sousa 💻 📖 🚇 🚧 ⚠️

Mahesh Sasidharan 📖