Auth0 Provider Terraform Module

This Terraform module configures Auth0 resources for authentication and authorization for the Nuon BYOC (Bring Your Own Cloud) applications. It creates and manages:

• A SPA Application for web interfaces
• A Native Application for CLI tools
• An API Resource Server for backend services
• A Custom Action to add email claims to access tokens

Prerequisites

• An Auth0 account
• A Management API client with sufficient permissions to create and manage Auth0 resources

Module Structure

.
├── main.tf         # Resources definition
├── variables.tf    # Input variables
├── outputs.tf      # Output values
├── versions.tf     # Version constraints
├── README.md       # Project documentation
├── MODULE_README.md # Detailed module documentation
└── examples/
    └── basic/      # Basic usage example
        ├── main.tf
        ├── variables.tf
        └── terraform.tfvars.example

Usage

Setting Up Auth0 Management API Access

Before using this module, you need to set up a properly scoped Auth0 Management API client:

1. Optionally create a new tenant in Auth0 where you will house the Nuon applications

2. Go to Applications > Create Application > Machine to Machine

3. Select the Auth0 Management API

4. Click on the API tab to configure permissions

5. Configure the following permissions (use the filter to find each category):

   Clients permissions:

   • Create:clients
   • Read:clients
   • Update:clients
   • Delete:clients

   Client Keys permissions:

   • Create:client_keys

   Client Credentials permissions:

   • Create:client_credentials
   • Read:client_credentials
   • Update:client_credentials
   • Delete:client_credentials

   Resource Servers permissions:

   • Create:resource_servers
   • Read:resource_servers
   • Update:resource_servers
   • Delete:resource_servers

   Actions permissions:

   • Create:actions
   • Read:actions
   • Update:actions
   • Delete:actions

6. After creating the application, collect the following values for your Terraform configuration:

   • auth0_domain - Your Auth0 tenant domain (e.g., your-tenant-name.us.auth0.com)
   • auth0_mgmt_client_id - Client ID of the Management API client
   • auth0_mgmt_client_secret - Client Secret of the Management API client

Using the Module in Your Terraform Configuration

module "auth0_provider" {
  source = "path/to/auth0-provider"
  
  # Auth0 Provider Configuration
  auth0_domain           = var.auth0_domain
  auth0_mgmt_client_id   = var.auth0_mgmt_client_id
  auth0_mgmt_client_secret = var.auth0_mgmt_client_secret
  
  # Application Configuration
  install_name      = "my-app"      # Optional: defaults to "BYOC"
  public_domain     = "app.example.com"
  
  # URL Configuration - Optional
  # These are automatically derived from public_domain if not specified:
  # callback_url = "https://app.example.com/api/auth/callback"
  # logout_url   = "https://app.example.com"
  # web_origin   = "https://app.example.com"
}

Input Variables

Name	Description	Type	Default	Required
auth0_domain	Your Auth0 domain (e.g., your-tenant.auth0.com)	string	-	yes
auth0_mgmt_client_id	Auth0 Management API Client ID	string	-	yes
auth0_mgmt_client_secret	Auth0 Management API Client Secret	string	-	yes
install_name	Installation name used as a prefix for Auth0 resources	string	"BYOC"	no
public_domain	Public domain for the installation	string	-	yes
callback_url	The callback URL for the SPA application (defaults to https://[public_domain]/api/auth/callback if not specified)	string	null	no
logout_url	The logout URL for the SPA application (defaults to https://[public_domain] if not specified)	string	null	no
web_origin	The web origin for CORS (domain only, no paths) (defaults to https://[public_domain] if not specified)	string	null	no

Important Notes

• auth0_domain: This is your Auth0 tenant domain (e.g., your-tenant.us.auth0.com). You must create this tenant in Auth0 before using this module.
• auth0_mgmt_client_id and auth0_mgmt_client_secret: These are credentials for an Auth0 Management API client that has permissions to create and manage resources in your Auth0 tenant.
• install_name: This is used as a prefix for all Auth0 resources created by this module. Default is "BYOC".
• public_domain: This is the only required application configuration parameter. It's used to configure the API identifier and automatically construct all URL values.
• URL variables: In a default installation, you don't need to specify callback_url, logout_url, or web_origin. These are automatically derived from public_domain in the module's main.tf file. You only need to provide these if you want to use custom URLs different from the defaults.

Provider Configuration

The Auth0 provider must be configured in your root module:

provider "auth0" {
  domain        = var.auth0_domain
  client_id     = var.auth0_mgmt_client_id
  client_secret = var.auth0_mgmt_client_secret
}

Examples

See the examples directory for working examples of how to use this module.

Basic Example

1. Navigate to the example directory:

   cd examples/basic
   

2. Copy the example variables file and edit it with your Auth0 credentials:

   cp terraform.tfvars.example terraform.tfvars
   

3. Initialize and apply the Terraform configuration:

   terraform init
   terraform apply
   

Requirements

• Terraform >= 1.0.0
• Auth0 Provider ~> 1.21.0
• An Auth0 account
• A Management API client with sufficient permissions

License

This module is licensed under the MIT License.