Overview

Connector token encryption lets HTTP policy encrypt and decrypt actions seal sensitive values (for example OAuth tokens) when they leave the Formal Connector. Sealed values use the formalsealed:v1: envelope format. The Connector wraps a per-process AES-256 data key with your cloud KMS key encryption key (KEK). This is separate from log encryption keys, which use asymmetric JWE for log fields.

Outcome: You can register a KMS KEK on a Connector and use policy encrypt/decrypt actions.
Prerequisites: A Connector, and a KMS key the Connector role can use.

Configuration via Terraform

Use the formal_connector_token_encryption_key resource. One key per Connector.

AWS KMS
GCP KMS
Azure Key Vault

resource "aws_kms_key" "formal_token_kek" {
  description = "Formal connector token encryption KEK"
  key_usage   = "ENCRYPT_DECRYPT"
}

resource "formal_connector_token_encryption_key" "example" {
  connector_id = formal_connector.example.id
  key_provider = "aws-kms"
  key_id       = aws_kms_key.formal_token_kek.arn
}

Grant the Connector task or pod role kms:Encrypt and kms:Decrypt on the CMK.

provider "google" {
  project = "my-project"
}

resource "google_kms_crypto_key" "formal_token_kek" {
  name     = "formal-token-kek"
  key_ring = "formal-keyring"
  purpose  = "ENCRYPT_DECRYPT"

  version_template {
    algorithm = "GOOGLE_SYMMETRIC_ENCRYPTION"
  }
}

resource "formal_connector_token_encryption_key" "example" {
  connector_id = formal_connector.example.id
  key_provider = "gcp-kms"
  key_id       = google_kms_crypto_key.formal_token_kek.id
}

Use a symmetric ENCRYPT_DECRYPT CryptoKey. Grant the Connector workload identity Cloud KMS CryptoKey Encrypter/Decrypter on that key.

resource "azurerm_key_vault_key" "formal_token_kek" {
  name         = "formal-token-kek"
  key_vault_id = "formal-key-vault-id"
  key_type     = "RSA"
  key_size     = 2048

  key_opts = [
    "wrapKey",
    "unwrapKey",
  ]
}

resource "formal_connector_token_encryption_key" "example" {
  connector_id = formal_connector.example.id
  key_provider = "azure-key-vault"
  key_id       = azurerm_key_vault_key.formal_token_kek.versionless_id
}

Use an RSA key that supports wrap/unwrap (RSA-OAEP-256). Grant the Connector managed identity keys/wrapKey and keys/unwrapKey on that key. Add an access policy or RBAC role for the Connector identity in addition to the Terraform runner policy above.

Verify:

terraform apply

Then enable an HTTP policy with encrypt / decrypt targets and confirm sealed values use the formalsealed:v1: prefix.

IAM requirements

Provider	Connector permissions
AWS KMS	`kms:Encrypt`, `kms:Decrypt` on the CMK
GCP KMS	Cloud KMS CryptoKey Encrypter/Decrypter on the CryptoKey
Azure Key Vault	`keys/wrapKey`, `keys/unwrapKey` on the key

Rotating the KEK

Changing key_id (or key_provider) on a Connector is a breaking change for already-sealed values. Downstream clients that hold formalsealed:v1: tokens produced under the previous KEK will not be able to decrypt them after the Connector switches to the new KEK. Plan for client re-authentication (or re-issuance of sealed tokens) when you rotate the KEK.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Connector Token Encryption

Overview

Configuration via Terraform

IAM requirements

Rotating the KEK

Next Steps

HTTP Policies

Log Encryption Keys

​Overview

​Configuration via Terraform

​IAM requirements

​Rotating the KEK

​Next Steps

HTTP Policies

Log Encryption Keys

Overview

Configuration via Terraform

IAM requirements

Rotating the KEK

Next Steps