Support configuring MFA settings for the unified phone experience

[RaniSputnik]

Checklist

• I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

This is somewhere between a feature request and a bug. I have started to use the new custom phone provider resource introduced in #1152. However, there doesn't seem to be a way to manage the MFA configuration using the Terraform provider, so I believe this feature isn't fully completed.

Previously we were using the auth0_guardian resource to manage our configuration but we are now getting this error:

│ Error: 403 Forbidden: Insufficient privileges to use this deprecated feature.
│ 
│   with auth0_guardian.my_guardian,
│   on modules/oauth/settings.tf line 16, in resource "auth0_guardian" "my_guardian":
│   16: resource "auth0_guardian" "my_guardian" {
│ 

I've tried stripping as much as I can out of our guardian configuration but even with a limited config I still see the errors:

resource "auth0_guardian" "my_guardian" {
  policy        = "never"
  email         = true
  otp           = true
  recovery_code = true

  phone {
    enabled       = true
    message_types = ["sms"]
  }
}

I have read this page comparing the endpoints that are not supported by the unified phone experience and I assume this is why I'm seeing the issue.

Describe the ideal solution

I think it would make sense to introduce a new guardian resource that is used when the new unified phone experience is enabled. This resource would allow me to configure this page in the dashboard:

It would also support enabling other MFA methods like OTP, email, recovery code etc. same as the existing guardian resource does. It would not call any of the deprecated API methods.

Alternatives and current workarounds

I'm not aware of any work arounds at the moment. It seems like the options are either to stay on the old phone settings (ie. not on the unified phone settings) or to configure these options manually in the dashboard.

Additional context

No response

[jwoodrow]

I think you might just be in the same situation as I am. I opened a support ticket and got the following answer

it looks like the 403 Error you are encountering is related to the custom phone provider configuration present on the tenant, the endpoint being called seems to be blocked by the fact that there is no Phone Message Action set up on the tenant.

The issue being that just as you seem to have done, I simply followed the interface recommendation in the MFA phone message section and configured my phone provider "globally" in the tenant section, rather than creating a custom phone message action manually in the Actions menu. Have you done the same thing as I suspect you might have ?

[RaniSputnik]

Sorry for the delay getting back to you @jwoodrow

It sounds like we have done the same thing, but I'm a little confused about this:

@jwoodrow ...rather than creating a custom phone message action manually in the Actions menu

There doesn't seem to be any way to configure it from the actions menu.

I think we've both configured this action type in the "correct" way 😕 Did you hear anything more from Auth0 support?

[jwoodrow]

Hi @RaniSputnik,

Before I had setup the phone provider via the phone_provider resource in terraform. But this creates a global/tenant level provider which seems to be incompatible with the guardian resource on terraform.

but now I've set it up the "old" way like so

resource "auth0_action" "custom_sms_provider" {
  name    = "Custom SMS provider"
  runtime = "node22"
  deploy  = true
  code    = file("${path.module}/actions/custom_sms_provider.js")


  supported_triggers {
    id      = "send-phone-message"
    version = "v2"
  }
}

# attach the phone provider action to the correct trigger
resource "auth0_trigger_actions" "send_phone_message" {
  depends_on = [auth0_action.custom_sms_provider]
  trigger = "send-phone-message"

  actions {
    id           = auth0_action.custom_sms_provider.id
    display_name = auth0_action.custom_sms_provider.name
  }
}

# Guardian
resource "auth0_guardian" "my_guardian" {
  #...
  # DO NOT USE TENANT LEVEL PHONE PROVIDER - THIS WILL BREAK
  phone {
    enabled       = true
    provider      = "phone-message-hook"
    message_types = ["sms"]
  }
  #...
}

And my guardian resource no longer has any errors

[polishere]

Configuring phone provider using guardian works, but it causes deprecation notice visible in logs.

"type": "depnote",
"description": "Allows use of legacy MFA phone provider: This feature is being deprecated. Please see details.feature of this log for more information.",

When I want to use global provider by enabling the switch below (btw is it possible to set up in terraform instead doing it in UI?) i got the same 403 Forbidden error when I want to use guardian resource in terraform.

403 Forbidden: Insufficient privileges to use this deprecated feature

[bendiknesbo]

+1, we also want to migrate to the new unified phone setup.

We have configured both the old send-phone-message v2 Action for MFA, and the new custom-phone-provider v1 Action for use from Connection Attributes (e.g. verification of phone during signup). We can enable the "Use Tenant-Level Messaging Provider" in the Auth0 Dashboard UI, but then our Terraform will fail every single run, with the same 403-error stated above.

[kushalshit27]

Hi all,
Our team is currently investigating the issue. We will come up with a solution soon.

[wiseman13]

Any updates on resolving this issue as we are seeing the same thing.

[bendiknesbo]

Any updates here, Auth0?

[francesco995]

hey auth0 any news on this?
cc @fabiograsso

[bendiknesbo]

@kushalshit27, do you have an update? It's been a while...

[bendiknesbo]

@kushalshit27 , do you have any progress on this issue? It is still blocking us from using the new unified experience.

Not being able to move to the new unified experience means that we have to maintain 2 almost-identical actions, one for MFA and one for phone-verification during signup.

[duedares-rvj]

Hello again @bendiknesbo
I know this might be frustrating, but we are working with the API team on this to clarify some crucial flows on the Unified Experience before implementing it on terraform.

I appreciate the patience on this from everyone. Please bear with me meanwhile.
Regards.

[ManuelSaleta]

This is very relevant at the end of 2025; do you happen to have any updates? - My team and I are trying to use a Custom Phone Provider, with Twilio's Verify API.

# This is an example on how to set up the phone provider with a custom action.
# Make sure a corresponding action exists with custom-phone-provider as supported triggers
resource "auth0_action" "send_custom_phone" {
  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) => {
    const { TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_VERIFY_SID } = event.secrets;

      const client = require('twilio')(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN);

      // map auth0 voice value to call
      const messageType = event.notification.delivery_method === 'voice' ? 'call' : 'sms';

      const { recipient, code } = event.notification;

      // add this to fix " 1333444999  "
      // "333 444 5555"
      const sanitizedNumber = recipient.replace(/\s/g, '').trim();

      await client.verify.v2.services(TWILIO_VERIFY_SID)
        .verifications.create({
          to: sanitizedNumber,
          channel: messageType,
          customCode: code
        })

    };
    EOT


  supported_triggers {
    id      = "custom-phone-provider"
    version = "v1"
  }

  dependencies {
    name    = "twilio"
    version = "5.10.2"
  }

  # Twilio credentials as Action secrets
  secrets {
    name  = "TWILIO_ACCOUNT_SID"
    value = some_var
  }
  secrets {
    name  = "TWILIO_AUTH_TOKEN"
    value = some_var
  }
  secrets {
    name  = "TWILIO_VERIFY_SID"
    value = some_var
  }

}

resource "auth0_phone_provider" "custom_phone_provider" {
  depends_on = [auth0_action.send_custom_phone] # 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"] # Supported delivery methods: "text" and/or "voice"
  }
  credentials {}
}

And while the action works, when attempting to enable SMS as an MFA option through the auth0_guardian resource, it results in the same errors OP mentions.

│ Error: 1 error occurred:
│ 	* 403 Forbidden: Insufficient privileges to use this deprecated feature.
│ 
│ 
│ 
│   with module.auth0.auth0_guardian.guardian,
│   on modules/auth0/guardian.tf line 2, in resource "auth0_guardian" "guardian":
│    2: resource "auth0_guardian" "guardian" {

resource "auth0_guardian" "guardian" {
  policy        = "all-applications"
  email         = false
  otp           = true
  recovery_code = false

  #   webauthn_platform {
  #     enabled = true
  #   }


  #   webauthn_roaming {
  #     enabled           = true
  #     user_verification = "required"
  #   }

  phone {
    enabled = true
    provider      = "phone-message-hook"
    message_types = ["sms"]

    #   options {
    #     enrollment_message   = "{{code}} is your verification code for {{tenant.friendly_name}}. Please enter this code to verify your enrollment."
    #     verification_message = "{{code}} is your verification code for {{tenant.friendly_name}}."
    #   }
  }

Additionally, the auth0_connection resource contains a block for mfa but that only controls active and return_enrollmentent_setttings.

If I am understanding everything correctly, currently there is no way to have a Custom Phone Provider with the Verify API while retaining opt options through terramform resources

[ipc-zpg]

I am also having issues with this.

I found that once I have auth0_guardian in state, even plans will start to fail. The only way to get my TF able to run again was to do a terraform state rm on that resource.

This issue is logged as a 'feature', but surely it's a bug?

[duedares-rvj]

Hi everyone,

Thank you all for your patience and valuable input on this issue. As the maintainers of the Terraform provider, we’ve been closely collaborating with both the Unified Phone Experience team and the Custom Phone Provider team.

Due to ongoing discussions and the need for more context from both sides, we’ve determined that it’s best to move this topic from the issue tracker to the Discussions tab; while keeping everyone updated as we work through these dependencies and gather more information.

It’s important to note that this issue isn’t solely a Terraform-specific bug or feature request, but rather a limitation that depends on the API team’s input. As we move forward and receive more insights, we’ll continue to update everyone in the Discussions tab.

We appreciate your understanding and support as we work together to find a resolution.
Thank you!