Skip to main content

​
Overview

CertForge integrates with Azure Key Vault (AKV) in two distinct ways. Choose the path that matches your infrastructure: Both paths support CertForge’s full governance model: approval workflows, Domain Trust Profiles, audit log, expiry alerts, and auto-renewal.

​
Path A — AKV as CA

In this mode, AKV is the Certificate Authority. CertForge calls the AKV Certificates API to request issuance. AKV either signs the cert itself (“Self”) or delegates to a configured external CA such as DigiCert or GlobalSign.

​
When to use AKV as CA

  • You want DigiCert or GlobalSign to sign certificates and store them in AKV
  • You want AKV self-signed certificates for internal testing
  • Your security policy requires all keys to be created inside AKV HSM

​
Azure setup

  1. Create a Key Vault (Standard or Premium tier)
  2. Create a Service Principal (app registration):
    • Note the Tenant ID, Client ID, and Client Secret
  3. Assign RBAC roles on the Key Vault:
The Key Vault Secrets User role is required to download private keys — even if you already have Certificates Officer. The PKCS#12 bundle is stored in AKV’s Secrets API under the same name as the certificate.
  1. Configure an issuer (if using DigiCert or GlobalSign):
    • In the AKV portal: Certificates → Certificate Authorities → Add
    • Provider: DigiCert or GlobalSign
    • Enter your CA account credentials
    • Note the issuer name (e.g. DigiCert, GlobalSign-Production)

​
CertForge setup

  1. Go to Admin → Certificate Authorities → New CA
  2. Set Type to Azure Key Vault
  3. Fill in:
    • Vault URL — e.g. https://my-vault.vault.azure.net
    • Tenant ID, Client ID, Client Secret
    • Issuer Name — leave blank or Self for self-signed; enter the AKV issuer name for DigiCert/GlobalSign
  4. Optionally enable Export private key — see Key Exportability below
  5. Click Ping to verify connectivity, then Save

​
Issuance timeout

  • Self-signed: completes in seconds
  • DigiCert / GlobalSign: CertForge waits up to 30 minutes for the CA to sign and return the cert. The approval shows as pending until AKV confirms completion.

​
Path B — AKV as Key Store

In this mode, your private CA (e.g. HashiCorp Vault PKI) signs the certificate, but the key pair is generated inside AKV. The key never leaves AKV unless you explicitly enable exportable keys.

​
When to use AKV as Key Store

  • You have an existing private CA and want AKV for key custody only
  • Your private CA can’t be replaced but your security team requires HSM-backed keys
  • You want different CAs signing certs for different domains but consistent key storage

​
Azure setup

Same RBAC requirements as Path A. The service principal on the connector needs:
  • Key Vault Certificates Officer — to create the key/cert object
  • Key Vault Secrets User — to export the PKCS#12 bundle when exportable keys are enabled

​
CertForge setup

  1. Add the CA connector (your private CA):
    • Go to Admin → CA Connectors → New Connector → Private CA
    • Deploy the connector binary, configure it to reach your Vault PKI or internal CA
  2. Add the AKV key store connector:
    • Go to Admin → CA Connectors → New Connector
    • Type: AKV Key Store
    • Enter the Vault URL, Tenant ID, Client ID, Client Secret
    • Click Ping to verify, then Save
  3. Link via Issuance Profile:
    • Go to Admin → Issuance Profiles → New Profile
    • Set CA to your private CA connector
    • Set Key Store Connector to the AKV connector
    • Optionally enable Export private key
    • Click Save

​
Key Exportability

By default, AKV keys are non-exportable — the private key is permanently bound to AKV and cannot be downloaded. This is appropriate for native Azure services (App Service, API Management, Azure Kubernetes Service) that can reference AKV directly. For non-native applications — web servers (nginx, Apache), Java apps, Python services — that need the private key as a file, enable exportable keys.

​
Exportable key: Path A (AKV CA)

Enable on the CA record:
  1. Admin → Certificate Authorities → Edit your AKV CA
  2. Check Export private key
  3. Save
All certs issued by this CA will have an exportable key policy. The private key is retrieved from AKV at issuance time and stored encrypted in CertForge’s database.

​
Exportable key: Path B (AKV Key Store)

Enable per Issuance Profile:
  1. Admin → Issuance Profiles → Edit your profile
  2. Check Export private key
  3. Save
This lets you have exportable keys for some workloads and non-exportable for others, using the same AKV vault.

​
Downloading the private key

Once a cert has an exportable key in CertForge:
  1. Go to Certificates → Inventory → open the cert
  2. Under Downloads & Actions, click Download .p12
  3. Enter an encryption password for the PKCS#12 bundle
  4. Save the .p12 file
The .key (PEM) download is also available without a password, authenticated by your CertForge session.
Exportable key policy is set at issuance time. Changing the setting after a cert is already issued does not retroactively make that cert’s key exportable — you must renew the cert for the new policy to apply.

​
Key Algorithm

Both AKV paths respect the Key Algorithm field on the Issuance Profile: AKV Premium tier uses HSM-backed keys for all types. AKV Standard tier uses software-backed keys.

​
Renewal

CertForge handles AKV cert renewal automatically:
  1. Renewal fires when the cert reaches its renewal threshold
  2. A new AKV certificate object is created (new key, new cert, new AKV name)
  3. The prior AKV cert object is deleted after the new cert is confirmed saved
  4. If the Issuance Profile has Export private key enabled, the new key is exported and saved to CertForge
The old AKV cert name is stored in ca_external_id and used for the deletion step — no manual cleanup required.

​
What if the AKV cert was manually deleted?

If the AKV cert entry is deleted from Azure before CertForge renews it, the old cert’s deletion step is silently skipped (404 = already gone). The new cert is still issued normally. This also applies to revocation — if the AKV cert doesn’t exist when CertForge tries to revoke it, the revocation is treated as complete.

​
RBAC quick reference

If you add a second AKV vault by creating a second AKV connector in CertForge, remember to assign the connector’s Managed Identity or Service Principal to that vault’s Access Control (IAM) independently. RBAC roles are per vault — they don’t inherit across vaults in the same subscription.

​
Troubleshooting

“Failed to dynamically fetch target download uri” in the Azure portal The cert is marked exportable in AKV, but your user account is missing Key Vault Secrets User on that vault. The PFX download uses the AKV Secrets API. Add the role in the vault’s Access Control (IAM). Cert shows CN=placeholder as issuer Your private CA’s Vault PKI instance is using the default development issuer. Generate a named intermediate CA (see Internal CA), set it as the default issuer in Vault, then restart the connector so it picks up the new default. Issuance times out waiting for DigiCert / GlobalSign CertForge waits up to 30 minutes for external AKV issuers. If issuance consistently times out, check the AKV issuer configuration in the portal (Certificates → Certificate Authorities) and confirm your DigiCert/GlobalSign account credentials are valid. ECDSA cert requested but RSA cert issued Verify the Key Algorithm field on the Issuance Profile matches one of: rsa-2048, rsa-4096, ecdsa-p256, ecdsa-p384. Values must be exact — typos fall through to the RSA-2048 default.