Terraform Cloud | Hanzo Docs

This guide will walk you through setting up Terraform Cloud to inject a workload identity token and use it for OIDC-based authentication with the Hanzo KMS Terraform provider. You'll start by creating a machine identity in Hanzo KMS, then configure Terraform Cloud to pass the injected token into your Terraform runs.

Follow the instructions in this documentation to create a machine identity with OIDC auth. Hanzo KMS OIDC configuration values for Terraform Cloud:

Set the OIDC Discovery URL to https://app.terraform.io.
Set the Issuer to https://app.terraform.io.
Configure the Audience to match the value you will use for TFC_WORKLOAD_IDENTITY_AUDIENCE in Terraform Cloud for the next step.

To view all possible claims available from Terraform cloud, visit HashiCorp’s documentation.

Navigate to your workspace in Terraform Cloud.
Add a workspace variable named TFC_WORKLOAD_IDENTITY_AUDIENCE:

Key: TFC_WORKLOAD_IDENTITY_AUDIENCE
Value: For example, my-kms-audience
Category: Environment

Important:

The presence of TFC_WORKLOAD_IDENTITY_AUDIENCE is required for Terraform Cloud to inject a token.
If you are self-hosting HCP Terraform agents, ensure they are v1.7.0 or above.

Once set, Terraform Cloud will inject a workload identity token into the run environment as TFC_WORKLOAD_IDENTITY_TOKEN.

If you need multiple tokens (each with a different audience), create additional variables:

TFC_WORKLOAD_IDENTITY_AUDIENCE_[YOUR_TAG_HERE]

For example:

TFC_WORKLOAD_IDENTITY_AUDIENCE_INFISICAL
TFC_WORKLOAD_IDENTITY_AUDIENCE_OTHER_SERVICE

Terraform Cloud will then inject:

TFC_WORKLOAD_IDENTITY_TOKEN_INFISICAL
TFC_WORKLOAD_IDENTITY_TOKEN_OTHER_SERVICE

Note:

The [YOUR_TAG_HERE] can only contain letters, numbers, and underscores.
You cannot use the reserved keyword TYPE.
Generating multiple tokens requires v1.12.0 or later if you are self-hosting agents.

If you are running on self-hosted HCP Terraform agents, you must use v1.7.0 or later to enable token injection. If you need to generate multiple tokens, you must use v1.12.0 or later.

In your Terraform configuration, reference the injected token by name. For example:

provider "kms" {
  host = "https://app.kms.hanzo.ai"

  auth = {
    oidc = {
      identity_id = "<identity-id>"
      # This must match the environment variable Terraform injects:
      token_environment_variable_name = "TFC_WORKLOAD_IDENTITY_TOKEN"
    }
  }
}

host: Defaults to https://app.kms.hanzo.ai. Override if using a self-hosted Hanzo KMS instance.
identity_id: The OIDC identity ID from Hanzo KMS.
token_environment_variable_name: Must match the injected variable name from Terraform Cloud. If using single token, use TFC_WORKLOAD_IDENTITY_TOKEN. If using multiple tokens, choose the one you want to use (e.g., TFC_WORKLOAD_IDENTITY_TOKEN_INFISICAL).

Run a plan and apply in Terraform Cloud.
Verify the Hanzo KMS provider authenticates successfully without issues. If you run into authentication errors, double-check the Hanzo KMS identity has the correct roles/permissions in Hanzo KMS.