Configure a Custom Provider with Terraform

You can configure a Custom Email Provideror Custom Phone Provider with Auth0's Terraform provider.

1. Create your auth0_action:

   Before you update Terraform, create the Terraform auth0_action used to deliver email, phone, or email and phone notifications.

   1. Create an auth0_action for email notifications:

      resource "auth0_action" "custom_email_provider" {
        name    = "Custom Email Provider"
        runtime = "node20"
        deploy  = true
        code    = <<-EOT
          /**
          * Handler to be executed while sending an email notification
          * @param {Event} event - Details about the user and the context in which they are logging in.
          * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending a email notification.
          */
          exports.onExecuteCustomEmailProvider = async (event, api) => {
            // Code goes here
            return;
          };
        EOT
        supported_triggers {
          id      = "custom-email-provider"
          version = "v1"
        }
      }

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

   2. Create an auth0_action for phone notifications:

      resource "auth0_action" "custom_phone_provider" {
        name    = "Custom Phone Provider"
        runtime = "node22"
        deploy  = true
        code    = <<-EOT
          /**
          * Handler to be executed while sending a phone notification
          * @param {Event} event - Details about the user and the context in which they are logging in.
          * @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
          */
          exports.onExecuteCustomPhoneProvider = async (event, api) => {
            // Code goes here
            return;
          };
        EOT
        supported_triggers {
          id      = "custom-phone-provider"
          version = "v1"
        }
      }

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

2. Bind your to the custom provider Action Trigger:

   In order to bind the Terraform auth0_action to an Actions Trigger, you must first deploy the Terraform auth0_action.

   1. Bind email to custom-email-provider Actions Trigger:

      resource "auth0_trigger_actions" "custom_email_provider" {
        trigger = "custom-email-provider"
        actions {
          id           = auth0_action.custom_email_provider.id
          display_name = auth0_action.custom_email_provider.name
        }
         depends_on = [
          auth0_action.custom_email_provider
        ]

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

   2. Bind phone to custom-phone-provider Actions Trigger:

      resource "auth0_trigger_actions" "custom_phone_provider" {
        trigger = "custom-phone-provider"
        actions {
          id           = auth0_action.custom_phone_provider.id
          display_name = auth0_action.custom_phone_provider.name
        }
        depends_on = [
          auth0_action.custom_phone_provider
        ]

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

3. Create your tenant custom provider

   1. Configure custom notifications for email:

      resource "auth0_email_provider" "custom_email_provider" {
        name                 = "custom"
        enabled              = true
        default_from_address = "accounts@example.com"
        credentials {}
        depends_on = [
          auth0_trigger_actions.custom_email_provider
        ]

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

   2. Configure custom notifications for phone:

      resource "auth0_phone_provider" "custom_phone_provider" {
        depends_on = [auth0_trigger_actions.custom_phone_provider] # Ensure the action is created first with `custom-phone-provider` as the supported_triggers
        name       = "custom"                         # Indicates a custom implementation
        disabled   = false                            # Disable the default phone provider
        configuration {
          delivery_methods = ["text", "voice"]
        }
        credentials {}

      feedbackSection.helpful

      feedbackSection.yesButtonText /feedbackSection.noButtonText

• Try to avoid mixing Terraform resource management with Management UI (or other mediums) and your Auth0 tenant.

  • When switching between experiences, we strongly advise rolling back your previous changes before changing.

• An Action binding cannot be undone unless your notification provider has been updated (i.e. switching to another supporter provider) or deleted.

Changes to my Action are not taking effect, and Management UI shows a different Action from the one I want to use.

This situation is highly possible if there are two or more actions with the state deployed:true in your Tenant. The custom-email-provider and custom-phone-provider are designed to support only one Action deployed at a time.

If you encounter this situation, we advise you to list your Actions and identify the duplicate ones. Choose one to delete and leave the desired one untouched.

• If you have a phone or email provider set with this Action, you will need to change (to another notification provider) or delete your the provider before unbinding the auth0_action from the trigger to be able to delete the Action.

• If you find this problem after switching management flows (Terraform to Management UI or Auth0 SDK, etc.), we advise you to roll back all these changes before changing workflows. Otherwise, your Auth0 tenant may contain more similar inconsistencies.

  • For phone or email providers, you can try navigating to Auth0 Dashboard > Branding and select either Phone Provider or Email Provider, then select the Reset button to restore your Tenant’s notification provider to a clean state (including Actions’s bindings).