> ## Documentation Index
> Fetch the complete documentation index at: https://docs.certgovernance.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Key Vault Integration

> Use Azure Key Vault as a CA backend or as an HSM-backed key store for certificates issued by your private CA.

## Overview

CertForge integrates with Azure Key Vault (AKV) in two distinct ways. Choose the path that matches your infrastructure:

| Path                 | When to use                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **AKV as CA**        | You want AKV to issue certificates — via DigiCert, GlobalSign, or AKV self-signed. The full certificate and key lifecycle lives in Azure. |
| **AKV as Key Store** | You have a private CA (Vault PKI, internal CA) and want keys to be HSM-backed in AKV while your CA signs the cert.                        |

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.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant CertForge
    participant AKV as Azure Key Vault
    participant ExtCA as DigiCert / GlobalSign

    User->>CertForge: Request certificate
    CertForge->>CertForge: Approval workflow
    CertForge->>AKV: CreateCertificate (policy, issuer)
    AKV->>ExtCA: CSR (if external issuer)
    ExtCA-->>AKV: Signed certificate
    AKV-->>CertForge: Certificate ready
    CertForge->>AKV: GetCertificate (DER)
    opt Exportable key
        CertForge->>AKV: GetSecret (PKCS#12)
        AKV-->>CertForge: Private key PEM
        CertForge->>CertForge: Store key in DB
    end
    CertForge-->>User: Certificate (+ key if exportable)
```

### 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:

| Principal         | Role                           | Required for                              |
| ----------------- | ------------------------------ | ----------------------------------------- |
| Service Principal | Key Vault Certificates Officer | Create and manage certificates            |
| Service Principal | Key Vault Secrets User         | Download PKCS#12 bundle (exportable keys) |
| Your admin user   | Key Vault Certificates Officer | Manage certs in the portal                |
| Your admin user   | Key Vault Secrets User         | Download PFX/PEM from the portal          |

<Note>
  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.
</Note>

4. **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](#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.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant CertForge
    participant Connector as CertForge Connector
    participant AKV as Azure Key Vault
    participant VaultPKI as Private CA (Vault PKI)

    User->>CertForge: Request certificate
    CertForge->>CertForge: Approval workflow
    CertForge->>Connector: generate_key_csr job
    Connector->>AKV: CreateCertificate (key policy)
    AKV-->>Connector: CSR
    Connector->>VaultPKI: Sign CSR
    VaultPKI-->>Connector: Signed certificate
    Connector->>CertForge: Upload cert + AKV key ref
    opt Exportable key
        CertForge->>AKV: GetSecret (PKCS#12)
        AKV-->>CertForge: Private key PEM
        CertForge->>CertForge: Store key in DB
    end
    CertForge-->>User: Certificate (+ key if exportable)
```

### 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.

<Warning>
  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.
</Warning>

***

## Key Algorithm

Both AKV paths respect the **Key Algorithm** field on the Issuance Profile:

| Value        | Key type     | Notes                            |
| ------------ | ------------ | -------------------------------- |
| `rsa-2048`   | RSA 2048-bit | Default                          |
| `rsa-4096`   | RSA 4096-bit | Larger key, slower TLS handshake |
| `ecdsa-p256` | EC P-256     | Recommended for modern workloads |
| `ecdsa-p384` | EC P-384     | Higher security margin           |

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

| Action                                 | AKV role needed                |
| -------------------------------------- | ------------------------------ |
| Issue a certificate                    | Key Vault Certificates Officer |
| Revoke / disable a cert                | Key Vault Certificates Officer |
| Download PFX/PEM (portal or CertForge) | Key Vault Secrets User         |
| View cert details (portal)             | Key Vault Certificates Reader  |
| List certs (Ping / Sync)               | Key Vault Certificates Officer |

<Note>
  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.
</Note>

***

## 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](/guides/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.