From 8e70731c4c8d65c895cedaa9b7af735bb40f0057 Mon Sep 17 00:00:00 2001 From: Maidul Islam Date: Tue, 18 Feb 2025 17:23:03 -0500 Subject: [PATCH] add terraform cloud oidc docs --- .../identities/oidc-auth/terraform-cloud.mdx | 88 +++++++++++++++++++ docs/mint.json | 6 +- 2 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 docs/documentation/platform/identities/oidc-auth/terraform-cloud.mdx diff --git a/docs/documentation/platform/identities/oidc-auth/terraform-cloud.mdx b/docs/documentation/platform/identities/oidc-auth/terraform-cloud.mdx new file mode 100644 index 000000000..8c2136029 --- /dev/null +++ b/docs/documentation/platform/identities/oidc-auth/terraform-cloud.mdx @@ -0,0 +1,88 @@ +--- +title: "Terraform Cloud" +description: "How to authenticate with Infisical from Terraform Cloud using OIDC." +--- + +This guide will show you how to configure Terraform Cloud to inject a workload identity token and use it for OIDC-based authentication with the Infisical Terraform provider. +At a high level, we'll begin by creating a machine identity in Infisical, then move on to enabling and using the injected token in your Terraform runs. + + + + Follow the instructions [in this documentation](/documentation/platform/identities/oidc-auth/general) to create a machine identity with OIDC auth. Infisical OIDC configuration values for Terraform Cloud: + 1. Set the OIDC Discovery URL to https://app.terraform.io. + 2. Set the Issuer to https://app.terraform.io. + 3. 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](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/dynamic-provider-credentials/workload-identity-tokens#token-structure). + + + + + + + 1. **Navigate to your workspace** in Terraform Cloud. + 2. **Add a workspace variable** named `TFC_WORKLOAD_IDENTITY_AUDIENCE`: + - **Key**: `TFC_WORKLOAD_IDENTITY_AUDIENCE` + - **Value**: For example, `my-infisical-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: + + ```hcl + provider "infisical" { + host = "https://app.infisical.com" + + auth = { + oidc = { + identity_id = "" + # This must match the environment variable Terraform injects: + token_environment_variable_name = "TFC_WORKLOAD_IDENTITY_TOKEN" + } + } + } + ``` + + - **`host`**: Defaults to `https://app.infisical.com`. Override if using a self-hosted Infisical instance. + - **`identity_id`**: The OIDC identity ID from Infisical. + - **`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`). + + + 1. Run a plan and apply in Terraform Cloud. + 2. Verify the Infisical provider authenticates successfully without issues. If you run into authentication errors, double-check the Infisical identity has the correct roles/permissions in Infisical. + + + \ No newline at end of file diff --git a/docs/mint.json b/docs/mint.json index b62af6533..aa3543274 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -232,7 +232,8 @@ "documentation/platform/identities/oidc-auth/general", "documentation/platform/identities/oidc-auth/github", "documentation/platform/identities/oidc-auth/circleci", - "documentation/platform/identities/oidc-auth/gitlab" + "documentation/platform/identities/oidc-auth/gitlab", + "documentation/platform/identities/oidc-auth/terraform-cloud" ] }, "documentation/platform/mfa", @@ -633,7 +634,8 @@ "api-reference/endpoints/oidc-auth/attach", "api-reference/endpoints/oidc-auth/retrieve", "api-reference/endpoints/oidc-auth/update", - "api-reference/endpoints/oidc-auth/revoke" + "api-reference/endpoints/oidc-auth/revoke", + "integrations/frameworks/terraform-cloud" ] }, {