Terraform

HashiCorp Terraform makes you more productive by enabling you to implement infrastructure as code to provision and manage any cloud, infrastructure, or service. Define infrastructure as code to manage the full lifecycle — create new resources, manage existing ones, and destroy those no longer needed. Terraform provides an elegant user experience for operators to safely and predictably make changes to infrastructure.

Terraform makes it easy to re-use configurations for similar infrastructure, and provides several benefits: a scalable and modular system for managing your cloud resources, a straightforward and flexible configuration language, and cloud and on-premises offerings to scale up usage across teams.

With Auth0 Provider for Terraform, your Auth0 configurations can be managed entirely using HashiCorp's Terraform. Rather than working through the UI, your Auth0 applications, APIs, and more can be created, updated, and managed through code and Terraform's CLI.

Prerequisites

There are a few things you'll need to get started:

• An Auth0 Account. You can sign up for a free Auth0 account here.
• Terraform! Terraform's documentation contains installation instructions.

Note: The command line examples in this guide assume you have a Unix-like Operating System (Linux, macOS, etc.). Terraform works with Windows and you can easily adapt them to fit your OS; consult the Terraform documentation if you're stuck.

Create a Machine to Machine Application

Before you can start using Terraform to manage your Auth0 configurations, you'll need to make a quick detour to the Auth0 site. Think of this as the bootstrapping phase — for Terraform to be able to create resources in Auth0, you'll need to manually create an Auth0 Machine-to-Machine Application that allows Terraform to communicate with Auth0.

Head to the Applications section of your Auth0 Dashboard and click the orange "Create Application" button on the right.

In the form that pops up, give your app a name like "Terraform Auth0 Provider" and select "Machine to Machine Application" as the type. Click the blue "Create" button to be taken to the next screen.

You'll need to authorize your new app to call the Auth0 Management API. Select it in the dropdown and then authorize all scopes by clicking "All" in the top right of the scopes selection area. Click the blue "Authorize" button to continue.

You'll be taken to the details page for your new application. Open the "Settings" tab and copy the Domain, Client ID, and Client Secret values - you'll need them in the next step for configuring the Auth0 Provider.

Configure the Provider

Although you can put passwords, secrets, and other credentials directly into Terraform configuration files, security best practices say that you should never store sensitive information in plaintext. There are several ways to store values like this outside of the configuration file itself; for now, you'll set your Auth0 Application credentials as environment variables. Many secret management products integrate with Terraform, including Hashicorp Vault and AWS Secrets Manager, but those are beyond this tutorial's scope.

In the terminal window where you're running Terraform, run the following commands, substituting AUTHO_DOMAIN, CLIENT_ID, and CLIENT_SECRET for your M2M app's values:

$ export TF_VAR_auth0_domain={AUTH0_DOMAIN}
$ export TF_VAR_auth0_client_id={CLIENT_ID}
$ export TF_VAR_auth0_client_secret={CLIENT_SECRET}

Prefixing TF_VAR_ to the environment variables means that Terraform can pick up those values and use them as Input Variables — injected properties to help parameterize your configuration without changing the source code. You can read up more on environment variables in the Terraform docs.

After you've set your environment variables, head back to your text editor, and add the following in main.tf:

variable "auth0_domain" {}
variable "auth0_client_id" {}
variable "auth0_client_secret" {}

provider "auth0" {
  domain        = var.auth0_domain
  client_id     = var.auth0_client_id
  client_secret = var.auth0_client_secret
}

Here, you can see a Provider block being defined — this is how Providers can be configured to work a specific way. In this case, The Auth0 Provider will communicate with the Auth0 Management API using the M2M credentials you've provided.

The variable blocks create the variable reference that the Provider configuration uses. You don't need to set a variable default value in the config file itself; Terraform will fill them in from your TF_VAR_* environment variables.

Tip: The order doesn't matter in Terraform configuration files - you can declare resources, providers, and other values in any order.

With your provider configured to communicate with Auth0's Management API, you can now start using the various Auth0 resources available from the provider.

Example: Add the auth0_client Resource

Time to create your Auth0 Application. Add the following to your Terraform config file:

resource "auth0_client" "my-example-application" {
  name            = "My Example Application"
  description     = "My example application using Auth0 and managed via Terraform"
  app_type        = "regular_web"
  callbacks       = ["http://localhost:3000/callback"]
  oidc_conformant = true

  jwt_configuration {
    alg = "RS256"
  }
}

This pattern is hopefully starting to look familiar — you're defining a resource of type auth0_client and giving it the unique name my-example-application. Within the resource block, arguments provide more context for the resource. The auth0_client resource has many possible arguments. The only required field is name, but any client configuration options available through the Management API are available.

You also don't need to worry about getting all of your settings right the first time — one of the major benefits of infrastructure-as-code like Terraform is that your settings and configuration can change incrementally over time. Storing config files in version control is a great way to track your infrastructure and configuration changes.

Here are the details of the configuration options above:

• name: The name of your application.
• description: A detailed description of your application.
• app_type: The type of application you're building. Since this is an Express server-side web application, regular_web makes sense here. If we were building a JavaScript single-page app, for instance, we'd use spa instead. The full list of options is available here.
• callbacks: An array of URLs that are valid callbacks for your application. In the Auth0 Dashboard, this is available in your application settings after creating your app.
• oidc_conformant: This flag is on by default if you create new applications in the Auth0 Dashboard and indicates that your app strictly conforms to the OIDC spec, as explained in the Auth0 documentation.
• jwt_configuration: This set of options allows configuration of the handling of JSON Web Tokens (JWTs) in your application. Using the RS256 algorithm for signing JWTs is the recommended best practice, as explained in the Auth0 docs.

With the new resource in place, you can run the following terminal commands to apply your configuration:

$ terraform init
$ terraform apply

init is required here because you've added the auth0 provider to your configuration, so Terraform will need to download the provider before applying the configuration. If you change your configuration but don't add any new providers, you can skip terraform init and just run terraform apply.

After apply finishes, you can verify that the application was created by going to the Auth0 Dashboard Applications page. You should see a new application called "My Example Application", as specified in the name argument passed to the resource.

Further readings and documentations

• Auth0 Blog: Use HashiCorp Terraform to Manage Your Auth0 Configuration
• Terraform Auth0 Provider