This repository contains a .NET library and CLI that help you run a small Certificate Authority entirely inside Azure Key Vault. All key material stays in Key Vault; the tooling orchestrates certificate creation, issuance, and renewal by driving the Key Vault APIs for you.
Today the toolset covers the basics needed for internal mTLS deployments: create a root CA, issue intermediates or end-entity certificates (across multiple vaults if desired), renew existing certs, and download certificates in PEM or PFX (PKCS#12) format for distribution. Features such as certificate revocation and automated renewal workers are still on the backlog, and the README calls out workarounds where needed (for example, building a certificate chain manually).
Typical scenarios include:
- Application Gateway needs to communicate with Azure API Management using mTLS
- Event Grid MQTT with certificate authentication
- Services communicating with each other using mTLS
Keeping certificates in Key Vault means you avoid managing private keys on developer machines and can drive issuance from automation such as Azure Pipelines or GitHub Actions. The CLI commands described below are script-friendly and make it easy to renew or reissue certificates as part of your existing deployment workflows.
GitHub Actions runs a basic build/test workflow (.github/workflows/ci.yml) on pushes and pull requests targeting main. Dependabot (.github/dependabot.yml) keeps NuGet packages and workflow actions up to date with weekly checks. Please leave these automations enabled so we can catch regressions and security issues early.
Please make sure these tools are installed:
- Azure CLI - used to authenticate to Azure
- Dotnet 8 - used to build the tools
- An Azure subscription with Key Vault enabled and sufficient permissions to either create resources and grant rights on them, or, an existing KeyVault with sufficient permissions to create and manage certificates and read secrets.
You'll also need to login to Azure CLI and have a Key Vault ready to store the certificates in.
-
Setup resources, assign roles
- Create 2 Key Vaults, one for the CA and one for the leaf certificates
- Ensure you have the following permissions:
- Certificate Officer - allows you to create and update certificates
- Crypto User - allows you to sign data using keys stored in Key Vault
- Secrets User - allows you to read secrets from Key Vault, including certificates and keys
-
Create a CA certificate
keyvaultca create-ca-cert --common-name "KeyVault-ca" --duration 2y root-ca@my-ca-keyvaultRequired permissions (CA vault): Certificate Officer, Crypto User, and Secrets User.
# Issuer and leaf can now live in different vaults by using secret@vault syntax.
keyvaultca issue-cert \
--issuer root-ca@my-ca-keyvault \
--duration 90d \
--not-before 2025-04-01T00:00:00Z \
--dns device1.alanta.local --dns device1 \
device1@my-certs-keyvault
# If both certs share a vault you can still rely on --key-vault.
keyvaultca issue-cert --key-vault my-certs-keyvault --issuer root-ca --duration 90d device1Required permissions:
- Issuer vault: Crypto User (to sign) and Secrets User (to read the CA cert).
- Target vault (where the new certificate lives): Certificate Officer and Secrets User.
Simply run keyvaultca issue-cert again with the same issuer/leaf references and a new validity window—the tool will create the next version for you (no Azure Portal pre-work required):
keyvaultca issue-cert \
--issuer root-ca@my-ca-keyvault \
--duration 90d \
device1@my-certs-keyvaultRequired permissions: same as issuing a new leaf certificate (Crypto + Secrets on the issuer vault, Certificate Officer + Secrets on the target vault).
If you want your leaf certificates to chain off an intermediate instead of the root, use issue-intermediate-cert. The issuer argument points to the parent CA while the name argument defines the intermediate certificate you are creating. Subject/SAN flags work exactly like issue-cert (defaults to CN=<name> if omitted).
# Create an intermediate in another vault so you can isolate issuing rights.
keyvaultca issue-intermediate-cert \
--issuer root-ca@my-ca-keyvault \
--duration 365d \
--dns intermediate.alanta.local \
intermediate-ca@my-intermediate-vault
# Or reuse the same vault via --key-vault
keyvaultca issue-intermediate-cert --key-vault my-ca-keyvault --issuer root-ca intermediate-caAfter the intermediate is created, use it as the --issuer when issuing your leaf certificates.
Required permissions:
- Parent CA vault: Crypto User and Secrets User.
- Intermediate vault (if different): Certificate Officer and Secrets User.
Use download-cert when you need to export certificates from Key Vault. By default, it exports PEM format; use --key to also get the private key, or --pfx to export PKCS12 format with the private key included.
# Export just the certificate (PEM)
keyvaultca download-cert --key-vault my-certs-keyvault device1
# Export the certificate plus the private key (PEM PKCS8)
keyvaultca download-cert --key-vault my-certs-keyvault --key device1
# Export as PFX (PKCS12) with certificate and private key
keyvaultca download-cert --key-vault my-certs-keyvault --pfx device1
# Export as PFX with password protection
keyvaultca download-cert --key-vault my-certs-keyvault --pfx --pfx-password "MySecurePassword" device1
# Full vault URI works too
keyvaultca download-cert --key-vault https://my-certs-keyvault.vault.azure.net/ --pfx device1The files land in the current directory; move them into your chain/keystore workflow as needed.
Required permissions: Secrets User on the vault that stores the certificate (Certificate Officer is not needed for read-only export).
The CLI doesn’t build a full PEM bundle yet, but you can assemble one manually once the certificates are exported:
- Download each certificate you need in the chain (leaf, intermediate(s), root) with
keyvaultca download-cert. - Concatenate them in order (leaf first, root last):
cat device1.pem intermediate-ca.pem root-ca.pem > device1-chain.pem- Use the combined file anywhere a full chain is required (App Gateway, MQTT broker, etc.).
If you also need a PKCS12 (.pfx) bundle with the full chain, download each certificate separately and combine them with OpenSSL:
# Download the certificates
keyvaultca download-cert --key-vault my-certs-keyvault --pfx device1
keyvaultca download-cert --key-vault my-intermediate-vault intermediate-ca
keyvaultca download-cert --key-vault my-ca-keyvault root-ca
# Build the chain bundle
openssl pkcs12 -export -out device1-chain.pfx -in device1.pfx -certfile intermediate-ca.pem -certfile root-ca.pemRequired permissions: whatever was needed to download the individual certificates (Secrets User on each vault). The concatenation/OpenSSL steps run locally.
- Create and merge a certificate signing request in Key Vault
- Application Gateway : Generate an Azure Application Gateway self-signed certificate with a custom root CA
Interested in helping? Please read CONTRIBUTING.md for details on our development workflow, coding conventions, and how to propose changes safely.
If you discover a vulnerability or have questions about security, follow the guidance outlined in SECURITY.md so we can respond quickly and keep our users safe.