Skip to content

An open source Azure Key Vault API compatible server (emulator).

License

Notifications You must be signed in to change notification settings

sebastiean/volt

Repository files navigation

Build Contributors Stargazers Issues MIT License


Logo

An open source Azure Key Vault API compatible server (emulator).
Report Bug · Request Feature

🚨 This project is in alpha status. This means that bugs are extremely likely and no assurances are made about compatability with the Key Vault REST API.

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Contact
  8. Acknowledgements

About The Project

Volt is an open source Azure Key Vault API compatible server (emulator) based on Node.js and written in Typescript.

Volt is inspired by and heavily based on Azurite, an Azure Storage API emulator. Volt uses (pretty much) the same architecture and patterns that are found in the Azurite project.

Built With

Supported Features

Getting Started

Install / run using one of the following options:

Clone this repo

After cloning source code, execute following commands to install and start Volt.

npm ci
npm run build
npm install -g
volt [options]

Run Volt docker image

docker run -p 13000:13000 sebastiean/volt

-p 13000:13000 will expose secrets service default listening port.

Run Volt docker image with customized persisted data location

docker run -p 13000:13000 -v ~/volt:/data sebastiean/volt

-v ~/volt:/data will use and map host path ~/volt as Volt's workspace location.

Customize other Volt supported parameters for docker image

docker run -p 8888:8888 -v ~/volt:/data sebastiean/volt volt -l --secretsPort 8888 --secretsHost 0.0.0.0 --loose --skipApiVersionCheck --cert ./localhost.cert --key ./localhost.key --oauth basic 

When running via Docker with HTTPS enabled, you must use --secretsHost 0.0.0.0 to correctly bind to the correct hostname.

Usage

SDK

To use Volt with the Azure Key Vault SDKs, you must enable HTTPS and OAuth.

volt --oauth basic --cert certname.pem --key certname-key.pem

Example (JavaScript SDK):

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();
         
const url = `https://127.0.0.1:13000`;

const client = new SecretClient(url, credential);

Command line options

Standard options

Option Example Description
--secretsHost --secretsHost 127.0.0.1 Listening host. By default Volt secrets will listen on 127.0.0.1
Use 0.0.0.0 to accept requests from remote addresses (unsafe).
---secretsPort --secretsPort 8888 Listening port. By default, Volt will listen on port 13000 for secrets.
Customize the listening port per your requirements.
-s
---silent
Disable access logs. By default Volt will display access logs in the console.
-d
--debug
-d ./debug.log Debug log includes detailed information on every request and exception stack traces.
Enable it by providing a valid local file path for the debug log destination.
-L
--loose
By default Volt will apply strict mode. Strict mode will block unsupported request headers or parameters.
Disable it by enabling loose mode.

Certificate options (HTTPS)

Please see HTTPS Setup section for help with creating self-signed certificates to use with Volt.

Option Example Description
--cert --cert path/server.pem By default Volt will listen on HTTP protocol.
Provide a PEM or PFX certificate file path to enable HTTPS mode.
--key --key path/key.pem When --cert is provided for a PEM file, must provide corresponding --key.
--pwd --pwd pfxpassword When --cert is provided for a PFX file, must provide corresponding --pwd.

OAuth options

Option (with example) Example Description
--oauth --oauth basic Enable OAuth authentication for Volt. Requires HTTPS to be enabled too.

Currently, Volt supports following OAuth authentication levels:

Basic

In basic level, --oauth basic, Volt will do basic authentication, such as validating incoming bearer token, checking issuer, audience, expiry.
Volt will NOT verify the token signature or permission.

Key Vault specific options

These options can be used to change the soft-delete behaviour of Volt. Please see the linked official documentation to understand this feature.

Option Example Description
--disableSoftDelete Disable the soft-delete feature entirely.
See https://docs.microsoft.com/en-us/azure/key-vault/general/soft-delete-change
--recoverableDays --recoverableDays 10 Number of calendar days deleted vault objects remain in a recoverable state.
Should be between 7 and 90.
Default is 90.
--purgeProtection If enabled, deleted vault objects cannot be purged during the retention period.
--protectedSubscription If enabled, Volt will behave as if part of a subscription that cannot be cancelled.

HTTPS Setup

This section is borrowed almost directly from Azurite

Volt natively supports HTTPS with self-signed certificates via the --cert and --key/--pwd options. You have two certificate type options: PEM or PFX. PEM certificates are split into "cert" and "key" files. A PFX certificate is a single file that can be assigned a password.

PEM

Generate PEM Certificate and Key

You have a few options to generate PEM certificate and key files. We'll show you how to use mkcert and OpenSSL.

mkcert

mkcert is a utility that makes the entire self-signed certificate process much easier because it wraps a lot of the complex commands that you need to manually execute with other utilities.

Generate Certificate and Key with mkcert

  1. Install mkcert: https://github.com/FiloSottile/mkcert#installation.
  2. Run the following commands to install the Root CA and generate a cert for Volt.
mkcert -install
mkcert 127.0.0.1

That will create two files. A certificate file: 127.0.0.1.pem and a key file: 127.0.0.1-key.pem.

Start Volt with HTTPS and PEM

Then you start Volt with that cert and key.

volt --cert 127.0.0.1.pem --key 127.0.0.1-key.pem

NOTE: If you are using the Azure SDKs, then you will also need to pass the --oauth basic option.

OpenSSL

OpenSSL is a TLS/SSL toolkit. You can use it to generate certificates. It is more involved than mkcert, but has more options.

Install OpenSSL on Windows

  1. Download and install the OpenSSL v1.1.1a+ EXE from http://slproweb.com/products/Win32OpenSSL.html
  2. Set the following environment variables
set OPENSSL_CONF=c:\OpenSSL-Win32\bin\openssl.cfg
set Path=%PATH%;c:\OpenSSL-Win32\bin

Generate Certificate and Key

Execute the following command to generate a cert and key with OpenSSL.

openssl req -newkey rsa:2048 -x509 -nodes -keyout key.pem -new -out cert.pem -sha256 -days 365 -addext "subjectAltName=IP:127.0.0.1" -subj "/C=CO/ST=ST/L=LO/O=OR/OU=OU/CN=CN"

The -subj values are required, but do not have to be valid. The subjectAltName must contain the Volt IP address.

Add Certificate to Trusted Root Store

You then need to add that certificate to the Trusted Root Certification Authorities. This is required to work with Azure SDKs and Storage Explorer.

Here's how to do that on Windows:

certutil –addstore -enterprise –f "Root" cert.pem
Start Volt with HTTPS and PEM

Then you start Volt with that cert and key.

volt --cert cert.pem --key key.pem

NOTE: If you are using the Azure SDKs, then you will also need to pass the --oauth basic option.

PFX

Generate PFX Certificate

You first need to generate a PFX file to use with Volt.

You can use the following command to generate a PFX file with dotnet dev-certs, which is installed with the .NET Core SDK.

dotnet dev-certs https --trust -ep cert.pfx -p <password>
Start Volt with HTTPS and PFX

Then you start Volt with that cert and key.

volt --cert cert.pem --key key.pem

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Please see CONTRIBUTION.md for more detailed contribution guidelines.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Sebastian Gatti - [email protected]

Project Link: https://github.com/sebastiean/volt

Acknowledgements