Skip to main content

Use your own encryption key

Goal​

Measured Cloud encrypts your organization's secrets with a key that belongs to your organization. The secrets are your data source credentials, AI provider API keys, SSO settings, and alert and integration secrets such as Slack webhooks and the dbt Cloud token.

You'll wrap that key in a key from your own Google Cloud KMS. From then on, Measured Cloud can use your secrets only while your key allows it:

  • every use shows in your KMS audit logs;
  • disabling the key, or removing Measured Cloud's access, stops it.

Rules, results, profiles and run history aren't secrets and aren't affected.

How it works​

Your organization's key is wrapped twice: first under your key, then under Measured Cloud's own key, held in Google Cloud KMS. Neither key alone can open it:

  • without yours, nobody can recover your secrets, Measured Cloud included;
  • without ours, your key alone can't read Measured Cloud's database.

Measured Cloud keeps the unwrapped key in memory for up to 5 minutes, then asks your KMS again. So revoking your key takes effect within 5 minutes. Only your organization is affected.

Prereqs​

  • The super admin role. Saving asks you to sign in again.
  • A Google Cloud project where you can create keys and change their access.

Steps​

  1. Create a key in Cloud KMS: a symmetric encryption key, in any location. Note its resource name: projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>.

  2. Open Settings → Encryption key in Measured Cloud. The page shows the service account to grant, and your organization's label.

  3. Grant Measured Cloud's service account two roles on the key:

    gcloud kms keys add-iam-policy-binding <key> --keyring <ring> --location <location> \
      --member serviceAccount:<the service account on the page> \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter
    gcloud kms keys add-iam-policy-binding <key> --keyring <ring> --location <location> \
      --member serviceAccount:<the service account on the page> \
      --role roles/cloudkms.viewer

  4. Label the key with your organization's id. This proves the key is yours: every organization shares Measured Cloud's service account, and only someone who controls the key can label it.

    gcloud kms keys update <key> --keyring <ring> --location <location> \
      --update-labels measured-cloud-org=<your organization id, as shown on the page>

  5. Paste gcp-kms://projects/…/cryptoKeys/<key> into Key resource name, and click Check and save. Measured Cloud:

    • reads the label;
    • encrypts and decrypts a test value with the key;
    • re-wraps your organization's key under it.

    If any step fails, nothing changes and the page says what to fix.

Verify​

  • Settings → Encryption key shows Your key with a recent Last checked time.
  • Your KMS audit logs show Measured Cloud's service account encrypting and decrypting with the key.
  • Test connection on a data source still works: your secrets are re-wrapped, not re-encrypted, so nothing needs re-entering.

Revoking and restoring​

  • To revoke: disable the key version in Cloud KMS, or remove Measured Cloud's role on the key. Within 5 minutes, anything that needs your secrets stops with an error saying your key can't be used:
    • data source tests, runs and profiles;
    • AI with your own provider (built-in AI keeps working);
    • alerts sent to integrations;
    • SSO sign-in.
  • If you enforce SSO: sign-in needs the SSO settings, which are a secret too, so nobody can sign in while the key is revoked. Restoring the key in your KMS restores sign-in; you don't need Measured Cloud for that.
  • To restore: re-enable the key version, or grant the roles again. Everything works again, with nothing to re-enter.
  • Be told: Measured Cloud checks your key every day. Add an alert rule on Encryption key unavailable or restored to hear when it stops working and when it's back. See Encryption key alerts.

Change or remove your key​

  • Change key: paste the new key's name (granted and labelled the same way) and save. Both keys must work while you switch.
  • Remove your key: your secrets go back under Measured Cloud's key only. Your key must still work.
  • If your key is gone for good (destroyed): your secrets can't be recovered. Remove your key offers to start a fresh key; you then re-enter data source credentials, AI provider keys, SSO settings and integration secrets. It's recorded in the audit log.

Every change is recorded in the audit log (organisation.cmek_enabled, organisation.cmek_changed, organisation.cmek_removed), with the key's name and never any key material.

Troubleshooting​

MessageFix
"The key must carry the label measured-cloud-org=…"Add the label from step 4, with your organization's id exactly as the page shows it.
"Measured Cloud can't read the key's labels"Grant roles/cloudkms.viewer on the key, and check the key's name.
"Measured Cloud can't encrypt and decrypt with the key"Make sure the key's primary version is enabled, and grant roles/cloudkms.cryptoKeyEncrypterDecrypter.
"…keys aren't supported here"The hosted service takes Google Cloud KMS keys (gcp-kms://).
"Your organization's encryption key … can't be used"The key was disabled, destroyed or its access removed. Restore it in Cloud KMS.

API​

GET /api/v1/organizations/{org_id}/encryption-key (any member), PUT with {"data": {"key_uri": "gcp-kms://…"}} and DELETE (?discard_secrets=true for a key that's gone), and POST …/check. Changing the key needs a super admin and a recent sign-in. See the API reference.