Secretless Terraform Authentication

The Defakto Terraform provider can authenticate to the Defakto control plane using Workload Identity Federation. A short-lived OIDC token from your CI/CD platform is exchanged for a service account session instead of a long-lived Ed25519 private key.

This guide covers Terraform Cloud (HCP Terraform). The same pattern applies to any CI/CD platform that issues OIDC tokens.

Prerequisites

• A Defakto Administrator account to register the WIF issuer
• A service account with a role appropriate for your Terraform operations
• Terraform Cloud with workload identity enabled on your workspace

Step 1: Register the Terraform Cloud WIF issuer

An Administrator must register Terraform Cloud as a trusted OIDC provider before any service account can use it.

spirlctl iam wif-issuer set "terraform-cloud" https://app.terraform.io

Example output:

WIF issuer "terraform-cloud" set successfully.
ID:          owi-def8901234
Name:        terraform-cloud
Issuer URL:  https://app.terraform.io
Key Source:  auto-discover

Alternatively, manage the issuer as a Terraform resource:

resource "spirl_org_wif_issuer" "tfc" {
  name       = "terraform-cloud"
  issuer_url = "https://app.terraform.io"
}

Step 2: Attach a WIF Configuration to your service account

The service account owner (or an administrator) attaches a WIF Configuration that specifies which Terraform Cloud workspace is allowed to authenticate as this service account. Every claim listed must be present in the token with an exactly matching value.

spirlctl iam service-account wif-config set my-service-account terraform-cloud \
  --claim terraform_organization_name=my-org \
  --claim terraform_workspace_name=my-workspace

Example output:

WIF config set successfully.
ID:                sawif-tyce2dfe3
Service Account:   sa-1123j3k2
Issuer:            owi-def8901234
Allow Any Bearer:  false
Claims:
  terraform_organization_name = my-org
  terraform_workspace_name    = my-workspace

tip

Scope claims as tightly as practical. Including both terraform_organization_name and terraform_workspace_name ensures only that specific workspace can authenticate as this service account. You can also add terraform_run_phase (e.g. apply) to restrict authentication to a specific run phase.

Alternatively, manage the WIF Configuration as a Terraform resource using spirl_service_account_wif_config:

resource "spirl_service_account_wif_config" "deployer" {
  service_account_id  = "sa-1234567890"
  org_wif_issuer_name = spirl_org_wif_issuer.tfc.name

  claims = {
    terraform_organization_name = "my-org"
    terraform_workspace_name    = "my-workspace"
  }
}

Step 3: Configure the Terraform provider

In your Terraform configuration, pass the Terraform Cloud workload identity token to the provider. Terraform Cloud exposes this as the TFC_WORKLOAD_IDENTITY_TOKEN environment variable during runs.

provider "spirl" {
  service_account_id = "sa-1234567890"
  oidc_token         = var.oidc_token
}

variable "oidc_token" {
  description = "OIDC token from the CI/CD platform."
  sensitive   = true
}

Set the variable from the environment in your workspace:

TF_VAR_oidc_token = $TFC_WORKLOAD_IDENTITY_TOKEN

When oidc_token and service_account_id are both set, the provider uses WIF token exchange to authenticate instead of using key-based authentication. The two authentication modes are mutually exclusive.

Alternatively, you can set the environment variable SPIRL_SERVICE_ACCOUNT_ID and SPIRL_OIDC_TOKEN to the corresponding values in your workspace and the provider will use those to authenticate.

How it works

When Terraform runs, the provider:

1. Reads service_account_id and oidc_token from the provider configuration.
2. Calls ExchangeToken on the Defakto control plane, passing both values.
3. The control plane decodes the JWT, looks up the WIF Configuration for the service account, and verifies the issuer and all configured claims.
4. The control plane fetches the JWKS from Terraform Cloud, verifies the token signature, audience, and expiry.
5. On success, the control plane returns a standard service account session token. The provider uses this token for all subsequent API calls.

The resulting session carries the same org role and realm assignments as the service account. From an authorization standpoint it is identical to a key-based session.

Removing WIF from a service account

To revert to key-based authentication, delete the WIF Configuration:

spirlctl iam service-account wif-config delete my-service-account

The service account's keys are unaffected by WIF Configuration changes. After deleting the WIF Configuration, the provider must be reconfigured to use a key.