Skip to main content
Version: v1.8

Local Key Vault development with Topaz

In this tutorial, we will create a local Key Vault on Topaz, store a secret in it, retrieve it with the Azure CLI, and connect to it from a .NET application using SecretClient.

What you will build​

  • A local Key Vault instance running on Topaz
  • Secrets stored and retrieved via the Azure CLI
  • A .NET snippet connecting to the local vault using SecretClient

Prerequisites​

  • Topaz installed and running (see Getting started)
  • DNS setup completed
  • Topaz certificate trusted by your OS and tooling
  • Azure CLI installed (az --version)
  • Topaz cloud registered in Azure CLI (see Azure CLI integration)

Step 1: Start Topaz​

topaz-host \
  --default-subscription 00000000-0000-0000-0000-000000000001 \
  --log-level Information

You will see the Topaz ASCII art banner, a table listing every running service with its port, and a "Default subscription created" confirmation.

Leave this terminal open and Topaz running throughout the tutorial.

Step 2: Set the active cloud to Topaz​

az cloud set -n Topaz
export AZURE_CORE_INSTANCE_DISCOVERY=false
az login
az account set --subscription 00000000-0000-0000-0000-000000000001

Step 3: Create a resource group and Key Vault​

az group create \
  --name rg-local \
  --location westeurope

az keyvault create \
  --name myvault \
  --resource-group rg-local \
  --location westeurope

Topaz assigns the vault a local hostname: myvault.vault.topaz.local.dev, which resolves to 127.0.0.1 via the DNS setup you completed in the prerequisites.

Step 4: Store and retrieve secrets​

Set a secret:

az keyvault secret set \
  --vault-name myvault \
  --name MySecret \
  --value "hello-from-topaz"

Retrieve it:

az keyvault secret show \
  --vault-name myvault \
  --name MySecret \
  --query value \
  --output tsv

Expected output: hello-from-topaz

List all secrets in the vault:

az keyvault secret list --vault-name myvault --output table

Step 5: Connect with the Azure SDK (.NET)​

Install the Azure Key Vault secrets client:

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Identity

Connect to the local vault using DefaultAzureCredential, which picks up the Azure CLI session automatically:

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

var vaultUri = new Uri("https://myvault.vault.topaz.local.dev:8898");
var client = new SecretClient(vaultUri, new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync("MySecret");
Console.WriteLine(secret.Value); // hello-from-topaz
Switching to production

The only difference from production is the URI. Replace https://myvault.vault.topaz.local.dev:8898 with https://myvault.vault.azure.net and the rest of the code — credentials, SDK calls, response handling — is identical.

Step 6: Soft-delete and recovery​

Topaz emulates soft-delete behaviour. Delete a secret:

az keyvault secret delete --vault-name myvault --name MySecret

List deleted secrets:

az keyvault secret list-deleted --vault-name myvault --output table

Recover a deleted secret:

az keyvault secret recover --vault-name myvault --name MySecret

Purge (permanent delete):

az keyvault secret purge --vault-name myvault --name MySecret

API coverage​

Topaz implements the full secrets lifecycle. See the Key Vault API coverage page for the complete operation matrix. Keys and Certificates are not yet emulated.

Next steps​

Star on GitHub