Help center

Azure Key Vault bring-your-own-key (BYOK) lets your firm hold the top encryption key in your own Azure subscription. Northdocs never stores your customer-managed key (CMK). Your CMK only wraps and unwraps Northdocs’ per-organization key (org KEK). That org KEK wraps per-document keys used for envelope encryption of files in object storage.

Who does what: a Northdocs organization admin enables envelope encryption and activates BYOK in Settings. A firm Azure / Entra admin creates the Key Vault, creates an RSA key, consents the Northdocs app, and grants wrap/unwrap permission. Ask sales@northdocs.com or support@northdocs.com for the Northdocs application (client) ID for your environment before you start.

How the keys stack: Customer CMK in Azure Key Vault → wraps Org KEK (stored wrapped in Northdocs) → wraps per-document DEK → encrypts the file bytes in OVH Object Storage. Document data residency stays EU by default. Prefer creating the vault in North Europe or West Europe so the key and the documents share an EU residency story.

Prerequisites (Northdocs): Enterprise plan with the azure_key_vault_byok entitlement; organization admin access; per-document envelope encryption available. Prerequisites (Azure): subscription rights to create a Key Vault; Entra Application Administrator (or Global Admin) to consent apps; ability to assign Key Vault RBAC.

1. 1

   Turn on envelope encryption in Northdocs

   Go to Settings → Organization, enable Per-document envelope encryption, and Save. BYOK cannot activate until this is on. Details: Per-document envelope encryption

2. 2

   Create a Key Vault in Azure Portal (Key vaults → Create)

   Choose a firm-owned subscription and resource group. Region: North Europe or West Europe recommended. Use Azure role-based access control (RBAC) on the vault. After creation, open Settings → Properties and ensure soft delete and purge protection are enabled. Copy the Vault URI from Overview (form: https://your-name.vault.azure.net/).

3. 3

   Networking

   The simplest path is a public vault endpoint so Northdocs can reach Key Vault over HTTPS. If your policy requires private endpoints or strict IP allowlists, contact Northdocs before go-live; production egress is not a fixed customer IP list today.

4. 4

   Create the RSA key

   In the vault open Objects → Keys → Generate/Import. Name example: northdocs-cmk (letters, digits, hyphens only). Key type: RSA. Size: 2048-bit minimum (3072 or 4096 also fine). Enabled: Yes. Do not use EC keys; Northdocs uses RSA-OAEP-256 for wrap and unwrap. Copy the key name. Optionally copy a specific key version (32-character hex); leave the version blank in Northdocs to always use the latest version.

5. 5

   Consent the Northdocs Entra application into your tenant

   Northdocs authenticates with client credentials against your tenant and scope https://vault.azure.net/.default. In Settings → Organization → Azure Key Vault BYOK, copy the Northdocs application (client) ID (shown in the UI; it is not a secret) and enter your Entra tenant ID to enable Admin consent link. Open that link as an Entra admin and Accept. Then open Entra ID → Enterprise applications, find the Northdocs app, and confirm the service principal exists.

6. 6

   Conditional Access

   If your tenant blocks confidential clients or requires interactive users for all apps, add an exclusion for this service principal so client-credentials token requests succeed. There is no signed-in user in this flow.

7. 7

   Grant Key Vault permissions

   On the vault (Access control IAM → Add role assignment), assign the Northdocs enterprise application the built-in role Key Vault Crypto User. That role includes wrap, unwrap, and get on keys. For least privilege you may use a custom role limited to wrapKey, unwrapKey, and get. Do not grant Northdocs permission to delete or purge the key. Wait a few minutes for RBAC to propagate.

8. 8

   Collect four values

   (1) Key Vault URI from vault Overview. (2) Key name. (3) Key version only if you want to pin one; otherwise leave blank. (4) Entra tenant ID from Entra ID → Overview → Tenant ID (a GUID).

9. 9

   Activate in Northdocs

   Settings → Organization → Azure Key Vault BYOK. Paste the four values. Click Test connection first: Northdocs wraps and unwraps a random probe with your CMK and stores nothing. When the test succeeds, click Activate BYOK. Activate re-wraps your organization encryption key under your CMK. Existing envelope-encrypted documents keep working because the org KEK material does not change; only how that org KEK is stored changes. Status should show active.

10. 10

    Smoke-test

    Upload a small PDF to a case, wait for processing, open and download it. If anything fails, use the troubleshooting section below before flipping Azure kill switches.

Disable BYOK (clean path): keep Key Vault reachable and RBAC intact, then click Disable BYOK in Settings. Northdocs unwraps via Azure, re-wraps the same org KEK under the Northdocs platform root, then turns BYOK off. If Azure is already unreachable, Disable will fail; restore Key Vault access first, or contact support@northdocs.com.

Kill switch (firm-controlled): disabling the key in Azure, or removing the Northdocs app’s Crypto User role, makes unwrap fail. Encrypted documents then fail closed until you restore access. Coordinate with practice ops before using this in production. Deleting or purging the key without a recovery plan can make data permanently unreadable.

What BYOK protects: document file bytes at rest in object storage after envelope encryption is on. What it does not protect: cleartext in memory during OCR, detection, redaction, and verify; detection rows and page text in the application database (needed for review); Clerk identity processing for sign-in. Northdocs calls Key Vault when wrapping or unwrapping the org KEK (activate, disable, cold decrypt paths), not once per page in the UI forever.

Troubleshooting: “not configured on this Northdocs environment” means server environment secrets are missing (ask Northdocs ops). “Entra token request failed” means missing admin consent, wrong tenant ID, or Conditional Access blocking client credentials. “wrapkey/unwrapkey failed (403)” means RBAC is missing or not propagated. “404” usually means wrong vault URI, key name, or pinned version. “Vault URI host must be *.vault.azure.net” means a typo (China cloud uses *.vault.azure.cn). If Activate fails after a good Test, confirm envelope encryption is still on and retry.

Key rotation tip: if you pin a key version in Northdocs and later rotate in Azure, update the version field, run Test, then Sync CMK version (or clear the version field to follow latest). Soft delete and purge protection on the vault are strongly recommended. Sync re-wraps the same organization key; it does not re-encrypt document files.

Fields reference: Vault URI example https://contoso.vault.azure.net ; Key name example northdocs-cmk ; Key version optional 32-char hex ; Tenant ID example 11111111-2222-3333-4444-555555555555.

See also: Per-document envelope encryption (Per-document envelope encryption), Security overview, Architecture, and your Northdocs contact for the IT runbook (Azure Key Vault BYOK) used in Enterprise onboarding.