Connect a KMS provider

1. Open Settings → Encryption for your team or organization.
2. Click Add encryption configuration. If configurations already exist, click Create encryption configuration above All configurations.
3. Under Basic information, enter a unique Name and an optional Description.
4. Select a Provider.

Continue with the instructions below for your provider.

We recommend using a cross-account role to avoid storing long-lived AWS credentials in Northflank.

The IAM role or user that Northflank uses to access your key needs kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, and kms:DescribeKey permissions. The KMS key policy must also permit access, either directly or through IAM policies.

Connect with a cross-account role

Open the configuration form with AWS KMS selected. Then follow these steps:

1. In Northflank, select Cross-account role under Credentials.
2. Enter an External ID, or click the Generate icon beside the field.
3. Click Copy Custom trust policy.
4. In AWS IAM, open Roles → Create role → Custom trust policy.
5. Paste the copied trust policy.
6. Name and save the role.
7. In Northflank, enter the role's IAM role ARN.
8. Enter the key's Region under Key location.
9. Enter the full key ARN in Key ID (id, ARN, or alias).
10. Click Copy IAM policy.
11. In AWS, add the copied policy as an inline policy on the role.
12. Make sure that the KMS key policy permits this role to use the key.
13. In Northflank, click Validate.
14. Wait for Validation successful before you click Create encryption configuration.

The key field also accepts a key ID or alias. If you use either, replace placeholders in the copied IAM policy with the actual key ARN before saving it. The policy resource must identify the key.

Connect with access keys

Open the configuration form with AWS KMS selected. Then follow these steps:

1. In AWS, create an IAM user and an access key for that user.
2. In Northflank, select Access key under Credentials.
3. Enter the Access key and Secret key.
4. Enter the key's Region under Key location.
5. Enter the full key ARN in Key ID (id, ARN, or alias).
6. Click Copy IAM policy.
7. In AWS, add the copied policy as an inline policy on the IAM user.
8. Make sure that the KMS key policy permits this user to use the key.
9. In Northflank, click Validate.
10. Wait for Validation successful before you click Create encryption configuration.

For either authentication method, continue to verify and activate the configuration.

We recommend Cross-project service account to avoid storing long-lived GCP credentials in Northflank.

The service account that Northflank uses needs the Cloud KMS CryptoKey Encrypter/Decrypter role (roles/cloudkms.cryptoKeyEncrypterDecrypter) on your key.

The Location field defaults to global. If your key ring uses another location, enter that location instead.

Connect with a cross-project service account

Open the configuration form with GCP Cloud KMS selected. Then follow these steps:

1. In Northflank, select Cross-project service account under Credentials.
2. Enter your Project ID and Location under Key location.
3. Enter your Key ring and Crypto key names.
4. Click Create encryption configuration. Northflank creates the configuration and opens its details page.
5. Copy the Email under Service account.
6. Click Open Cloud KMS in the GCP console.
7. In Google Cloud, open the key's permissions.
8. Add the copied service account email as a principal.
9. Assign the Cloud KMS CryptoKey Encrypter/Decrypter role.
10. Save the assignment.
11. In Northflank, verify and activate the configuration.

The creation form does not show Validate because Northflank creates the service account when you create the encryption configuration. You must then grant the service account access to your key. The details page also provides a gcloud CLI tab with a command to grant access.

Connect with a service account key

This method also requires permission to create a service account and a JSON key.

Open the configuration form with GCP Cloud KMS selected. Then follow these steps:

1. In Google Cloud, create a service account for Northflank.
2. Grant that account the Cloud KMS CryptoKey Encrypter/Decrypter role on your key.
3. Create and download a JSON key for the service account.
4. In Northflank, select Service account key under Credentials.
5. Add the JSON contents to Service account key (keyfile.json).
6. Enter your Project ID and Location under Key location.
7. Enter your Key ring and Crypto key names.
8. Click Validate.
9. Wait for Validation successful before you click Create encryption configuration.
10. Continue to verify and activate the configuration.

The Key Vault Crypto Service Encryption User role grants key metadata access and wrapping operations. If your vault uses access policies, grant wrapKey and unwrapKey. A versionless key URL also requires get.

Enable purge protection for production vaults. Follow the key-availability guidance for previous key versions.

Open the configuration form with Azure Key Vault selected. Then follow these steps:

1. In Microsoft Entra ID, register an application for Northflank.
2. Create a client secret for the application.
3. In Azure Key Vault, grant its service principal the key access described above.
4. In Northflank, enter the directory ID in Tenant ID and the application ID in Client ID.
5. Enter the client secret value, not its identifier, in Secret.
6. Enter the Key identifier URL under Key location.
7. Click Validate.
8. Wait for Validation successful before you click Create encryption configuration.
9. Continue to verify and activate the configuration.

Vault Transit performs encryption operations with a named key. Northflank uses it to wrap DEKs. This differs from a Vault KV integration, which stores secret values in Vault.

The token needs the update capability on these paths. Replace transit with your mount path and northflank with your key name:

path "transit/encrypt/northflank" {
  capabilities = ["update"]
}
path "transit/decrypt/northflank" {
  capabilities = ["update"]
}
path "transit/datakey/plaintext/northflank" {
  capabilities = ["update"]
}

Open the configuration form with HashiCorp Vault Transit selected. Then follow these steps in Northflank:

1. Under Connection, enter the HTTPS Address of your Vault server.
2. Enter your Token.
3. If your Vault uses a namespace, enter it in Namespace (optional).
4. Under Key location, enter Mount path (optional), or leave it blank for transit.
5. Enter the Key name.
6. Use the displayed Vault policy to make sure that your token has the required permissions.
7. Click Validate.
8. After Validation successful appears, click Create encryption configuration.
9. Continue to verify and activate the configuration.

Keep the token valid and replace it before it expires.