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
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.
- Secrets API
- Set Secret
- Update Secret
- Get Secret
- Get Secret Versions
- Get Secrets
- Delete Secret
- Get Deleted Secret
Get Deleted Secrets*Not yet supportedBackup Secret*Not yet supportedPurge Deleted Secret*Not yet supportedRecover Deleted Secret*Not yet supportedRestore Secret*Not yet supported
Install / run using one of the following options:
After cloning source code, execute following commands to install and start Volt.
npm ci
npm run build
npm install -g
volt [options]docker run -p 13000:13000 sebastiean/volt-p 13000:13000 will expose secrets service default listening port.
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.
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.0to correctly bind to the correct hostname.
To use Volt with the Azure Key Vault SDKs, you must enable HTTPS and OAuth.
volt --oauth basic --cert certname.pem --key certname-key.pemconst { 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);| 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. |
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. |
| 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.
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. |
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.
You have a few options to generate PEM certificate and key files. We'll show you how to use mkcert and OpenSSL.
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
- Install mkcert: https://github.com/FiloSottile/mkcert#installation.
- Run the following commands to install the Root CA and generate a cert for Volt.
mkcert -install
mkcert 127.0.0.1That 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.pemNOTE: If you are using the Azure SDKs, then you will also need to pass the --oauth basic option.
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
- Download and install the OpenSSL v1.1.1a+ EXE from http://slproweb.com/products/Win32OpenSSL.html
- Set the following environment variables
set OPENSSL_CONF=c:\OpenSSL-Win32\bin\openssl.cfg
set Path=%PATH%;c:\OpenSSL-Win32\binGenerate 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.pemThen you start Volt with that cert and key.
volt --cert cert.pem --key key.pemNOTE: If you are using the Azure SDKs, then you will also need to pass the --oauth basic option.
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>Then you start Volt with that cert and key.
volt --cert cert.pem --key key.pemSee the open issues for a list of proposed features (and known issues).
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.
Distributed under the MIT License. See LICENSE for more information.
Sebastian Gatti - [email protected]
Project Link: https://github.com/sebastiean/volt
- Azurite
- Logo design by ch.iordanis 🤩