Setup Common Fate Terraform Provider

​

Prerequisites

• Terraform installed and configured.
• An active Common Fate deployment and access to the deployment Terraform code.

​

Folder Structure

We recommend creating a different folder for setting up the configuration and for each integration. We have an example for AWS here: https://github.com/common-fate/byoc-aws-starter-config

├── aws-integration
   └── main.tf
├── config
   ├── main.tf
   └── aws_idc.tf
└── deployment
    └── main.tf

​

Requirements

This guide will walk you through setting up the commonfate Terraform provider. This guide will be only for getting the provider configured with your Common Fate deployment.

For more information about each of the different resources these are documented on the provider registry page: https://registry.terraform.io/providers/common-fate/commonfate/latest/docs

The provider requires some variables for it to work with your deployment. All of these variables can be found from your deployment Terraforms outputs.

Our Terraform provider uses a machine-to-machine OpenID Connect (OIDC) protocol to authenticate to Common Fate. The AWS Cognito user pool deployed with Common Fate acts as the OIDC issuer.

Here’s an example of a configured provider block:

terraform {
  required_providers {
    commonfate = {
      source  = "common-fate/commonfate"
      version = "2.13.0"
    }
  }
}

provider "commonfate" {
  api_url            = "http://commonfate.example.com"
  oidc_client_id     = "349dfdfkljwerpoizxckf3fds345xcvv" # terraform_client_id from deployment/main.tf's terraform output
  oidc_issuer        = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_jieDxjtS" # auth_issuer from deployment/main.tf's terraform output
}

You’ll also need to set the CF_OIDC_CLIENT_SECRET environment variable in the environment that your Terraform is running in. If you’re using a CI/CD runner like GitHub Actions we recommend storing this as a secret and injecting this when the Terraform plan/apply runs. To get the value of CF_OIDC_CLIENT_SECRET, you need to run terraform output terraform_client_secret in deployment/main.tf.

​

Finding deployment outputs

output "outputs" {
  description = "outputs"
  value       = module.common-fate-deployment.outputs
}

output "terraform_client_secret" {
description = "terraform client secret"
value = module.common-fate-deployment.terraform_client_secret
sensitive = true
}

To get the values you need for each of the provider variables you will need to get the outputs from the deployment Terraform.

This can be done by running the following in the root of the Terraform files:

Make sure you have AWS credentials for the account your Common Fate is deployed to

assume <role_to_access_deployment> -r <region_of_deployment>

Run the output command to get a list of outputs.

terraform output -json

You should see an output like this:

"app_url": {
"sensitive": false,
"type": "string",
"value": ""
},
"auth_url": {
"sensitive": false,
"type": "string",
"value": ""
},
"oidc_issuer": {
"sensitive": false,
"type": "string",
"value": ""
},
...

The variables we need are:

• app_url
• oidc_issuer
• terraform_client_id
• terraform_client_secret

Use these variables in place like this:

provider "commonfate" {
  api_url = <app_url>
  oidc_client_id = <terraform_client_id>
  oidc_client_secret = <terraform_client_secret>
  oidc_issuer = <oidc_issuer>
}