Skip to main content
This is the workflow we recommend for keeping Authsignal configuration consistent across dev, QA, and production with the Authsignal Terraform provider. You can set up a new environment from the same code.

​
Overview

Each environment has its own Authsignal tenant. You build and test configuration in the dev tenant using the portal. You then capture the changes as code in a shared module and apply that module to QA and then production.
The dev tenant is edited by hand in the portal. Changes are captured as code in the shared module and reviewed in a pull request, then applied in order to QA and production.

Changes start in dev and are applied to QA, then production

Once it’s set up, a plan against any tenant shows whether it matches the module. No changes means it does.

​
Terraform basics

Terraform reads code written in files ending in .tf and changes a system to match it. The Authsignal Terraform provider is the plugin that lets Terraform manage an Authsignal tenant through the Management API. A module is a folder of .tf files that other folders can reuse. Here, one module holds the Authsignal configuration and each environment’s folder uses it. Terraform keeps a record of the resources it manages, called state. Each environment has its own state. Importing adds something that already exists in a tenant to state, without changing the tenant. You run Terraform from inside an environment’s folder, mostly with three commands:
  • terraform init downloads the provider and prepares the folder. Run it once in each folder, and again after changing the provider or where state is stored.
  • terraform plan compares the code with the tenant and lists what it would change. It doesn’t change anything.
  • terraform apply makes those changes.
If this is your first time using Terraform, HashiCorp’s introduction and tutorials explain these in more depth. Those tutorials run Terraform on your own machine. In these guides you do that for dev only. QA and production run from a CI pipeline, as in Running QA and production.

​
What’s covered

The module holds whichever parts of the Authsignal configuration you choose to manage, such as authenticators, flows, rules, and branding. You can bring in new resources at any time. The resources the provider supports are listed on the Terraform Registry. A few values usually have to differ per tenant, such as web addresses and the tenant name shown to users. These are variables, which you set in each environment’s terraform.tfvars file. Everything else should be the same in every tenant. Resources that should only exist in some environments, such as an action that only your automated tests use in dev and QA, sit behind a variable that you switch on per environment.

​
Repository layout

One shared module holds the Authsignal configuration. Each environment has a small folder that applies the module to one tenant, with its own state and terraform.tfvars file.

​
Prerequisites

  • Terraform 1.11 or later. Install it, then check the version with terraform version.
  • A git repository for the code.
  • An Authsignal Portal account that can create tenants and Management API secret keys.
  • Somewhere shared to keep state, such as an S3 bucket. See Where state is stored.

​
Setup

  1. Configure the dev tenant in the portal.
  2. Capture the dev configuration as code in the shared module. Terraform can generate a starting point from dev, or you can write the code by hand.
  3. Set up shared state storage, then import dev into Terraform state. The plan should show no changes to the tenant.
  4. Add QA and production one at a time. Terraform creates the configuration in each new tenant, importing anything the tenant already has.

​
Day to day

You still make changes to the dev tenant in the portal. You then update the module until terraform plan in envs/dev reports No changes, then open a pull request. Once it merges, run the QA pipeline, then production. If you change an existing resource in the QA or production tenant, Terraform reverts it the next time it’s applied there. Anything new you add in those tenants isn’t managed by Terraform, so it’s left alone. Dev should be the only tenant anyone edits by hand.

​
Guides

  1. How the repository is set up
  2. Generate code from the dev tenant
  3. Build the module from the generated code
  4. Import the dev tenant into Terraform
  5. Add a new environment
  6. Promote a change from dev