API Settings for Changing MFA Preferred

Get Help
,
1

Hey all,

I’m currently trying to figure out how to configure MFA Settings to change this to preferred. I have checked the API, and the closest I’ve come is being able to just set the webauthn-roaming; however, this isn’t sufficient.

Here are the api docs that a0deploy is using i do believe…but i can’t figure out which sets the verification.

image
image960×864 62.1 KB

3

Hi @sclark1

You are trying to configure MFA settings to change a factor to "preferred" using the Auth0 Management API. You have found that you can set webauthn-roaming, but this is not sufficient for your use case.

To set a preferred MFA factor via the Management API, you need to use the /api/v2/users/{id}/authentication-methods endpoint to manage user authentication methods, or use a Post-Login Action to challenge users with a specific factor. The Management API does not have a direct "preferred factor" setting; instead, you control MFA behavior through factor enrollment, challenge logic, and user metadata.

Root Cause:

The Auth0 Management API does not expose a direct "preferred MFA factor" setting. Instead, MFA preference is controlled through:

  1. User enrollment — Which factors the user has enrolled in
  2. Challenge logic — Which factor is presented during login (via Actions or Rules)
  3. User metadata — Storing preference information that your application logic can read

Solution: Set Preferred MFA Factor Using User Metadata and Post-Login Actions

Step 1: Store the Preferred Factor in User Metadata

Use the Management API to add a preferred factor to the user's user_metadata:

PATCH /api/v2/users/{user_id}
Content-Type: application/json

{
  "user_metadata": {
    "preferred_mfa_factor": "otp"
  }
}

Supported factor types:

  • otp — One-Time Password (Google Authenticator, Microsoft Authenticator, etc.)
  • sms — SMS text message
  • email — Email verification code
  • webauthn — WebAuthn/FIDO2 device
  • phone — Phone call

Step 2: Create a Post-Login Action to Challenge with the Preferred Factor

Create a Post-Login Action that reads the preferred factor from user metadata and challenges the user with that factor:

exports.onExecutePostLogin = async (event, api) => {
  // Check if user has a preferred MFA factor set
  const preferredFactor = event.user.user_metadata?.preferred_mfa_factor;

  // Only proceed if user is enrolled in MFA
  if (!event.user.enrolledFactors || event.user.enrolledFactors.length === 0) {
    return;
  }

  // If user has a preferred factor, challenge with it
  if (preferredFactor) {
    console.log(`Challenging user with preferred factor: ${preferredFactor}`);
    
    try {
      api.authentication.challengeWith({
        type: preferredFactor
      });
    } catch (error) {
      console.error(`Failed to challenge with ${preferredFactor}:`, error);
      // Fall back to any available factor
      api.multifactor.enable('any', { allowRememberBrowser: false });
    }
  } else {
    // No preference set; allow user to choose or use default
    api.multifactor.enable('any', { allowRememberBrowser: false });
  }
};

Step 3: Deploy and Add the Action to Your Login Flow

  1. Navigate to Actions → Library → Deploy Action
  2. Go to Actions → Flows → Login
  3. Add your action to the flow
  4. Save the flow

Step 4: Allow Users to Set Their Preferred Factor

In your application, provide a settings page where users can select their preferred MFA factor:

// Example: Update user's preferred MFA factor via Management API
async function setPreferredMfaFactor(userId, factor) {
  const response = await fetch(`https://${AUTH0_DOMAIN}/api/v2/users/${userId}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${managementApiToken}`
    },
    body: JSON.stringify({
      user_metadata: {
        preferred_mfa_factor: factor
      }
    })
  });

  return response.json();
}

Alternative: Use app_metadata for Admin-Controlled Preferences

If you want to control preferences as an admin (not user-controlled), use app_metadata instead:

PATCH /api/v2/users/{user_id}
Content-Type: application/json

{
  "app_metadata": {
    "preferred_mfa_factor": "otp"
  }
}

Then update your Action to read from app_metadata:

const preferredFactor = event.user.app_metadata?.preferred_mfa_factor;

Managing WebAuthn Roaming Factors

If you specifically want to configure webauthn-roaming factors, use the authentication methods endpoint:

GET /api/v2/users/{user_id}/authentication-methods

This returns all enrolled factors for the user. You can then use api.authentication.challengeWith({ type: 'webauthn' }) in your Post-Login Action.

This approach allows you to set and enforce a preferred MFA factor for each user while maintaining flexibility for fallback options.

Kind Regards,
Nik

4

This isn’t quite what I’m asking. The question I’m asking is that in the CiC console, there is a setting with webauthn-roaming for user verfication set to if available. This allows things like nordpass to be used with the app.

I’d like to set this setting at the auth0 deployment tooling instead of per user.

5

Hi again @sclark1

I must have misunderstood your question initially.

You are trying to configure WebAuthn user verification settings at the tenant level using Auth0 deployment tooling (a0deploy) instead of configuring it per-user. You have found that you can enable webauthn-roaming via a0deploy, but the user verification preference setting (currently set to "if available" in the Auth0 Console UI) is not exposed as a configurable parameter.

The WebAuthn user verification setting ("if available", "required", or "discouraged") is currently not available via the Auth0 Management API or a0deploy deployment tooling. This setting can only be configured manually in the Auth0 Dashboard. There is no API endpoint, parameter, or deployment configuration option to set this at the tenant level.

Root Cause:

The Auth0 Dashboard allows you to configure WebAuthn user verification under Security → Multi-factor Auth → WebAuthn Roaming → User Verification, where you can choose:

  • Required — User verification is mandatory
  • If available — User verification is used if the device supports it (optional)
  • Discouraged — User verification is not requested

However, this setting is not exposed in:

  1. The Management API — There is no endpoint parameter to set this preference
  2. a0deploy configuration files — The deployment tooling does not include this setting
  3. Terraform or other Infrastructure as Code tools — This setting cannot be managed as code

The webauthn-roaming.json file in a0deploy only supports:

{
  "name": "webauthn-roaming",
  "enabled": true
}

The user_verification preference is not a configurable field in this file.

Solution: Request Feature or Use Dashboard Configuration

Option 1: Request API Exposure (Recommended)

This is a feature gap in Auth0. You should request that Auth0 expose the WebAuthn user verification setting in the Management API and a0deploy:

  1. Open a feature request with Auth0 Support or on the Auth0 Community
  2. Request: Expose WebAuthn user verification preference in the Management API
  3. Suggested endpoint: Add a parameter to /api/v2/factors/webauthn-roaming or a new endpoint like /api/v2/factors/webauthn-roaming/settings
  4. Suggested parameter: user_verification with values: required, preferred, discouraged
  5. Request a0deploy support: Add WebAuthn user verification configuration to a0deploy deployment files

Step 1: Contact Auth0 Support

  1. Open a support ticket with Auth0
  2. Provide:
    • Your Auth0 tenant name
    • The current Console UI setting path: Security → Multi-factor Auth → WebAuthn Roaming → User Verification
    • The desired value: "If available"
    • Your use case: Configuring this setting via a0deploy for consistent deployment across environments
  3. Request: Expose this setting in the Management API and a0deploy

Option 2: Configure Manually in Dashboard (Current Workaround)

Until this feature is available, you must configure the user verification setting manually in the Auth0 Dashboard:

  1. Navigate to Auth0 Dashboard → Security → Multi-factor Auth
  2. Select WebAuthn Roaming
  3. Under User Verification, select "If available"
  4. Click Save

This setting applies tenant-wide and will affect all users and applications.

Option 3: Use a Post-Deployment Checklist

Create a checklist to verify these settings after each deployment:

  1. After deploying via a0deploy, verify in the Dashboard that:
    • WebAuthn Roaming is enabled
    • User Verification is set to "If available"
    • Relying Party ID is correct
  2. Add to your CI/CD pipeline: A manual approval step to confirm these settings are correct

Why This Limitation Exists:

The WebAuthn user verification setting is a tenant-wide configuration that affects all users and applications. Auth0 may have intentionally limited this to the Dashboard to:

  1. Prevent accidental misconfiguration via API
  2. Ensure consistency across the tenant
  3. Require explicit review before changing security settings

However, this creates a gap for Infrastructure as Code (IaC) workflows where all configuration should be version-controlled and deployed programmatically.

Recommended Next Steps:

  1. Request this feature from Auth0 (contact Auth0 Support or post on the Auth0 Community)
  2. Use the Dashboard to configure the setting for now
  3. Document the manual step in your deployment runbook
  4. Monitor for API updates — Auth0 may expose this setting in a future release

This is a known limitation of Auth0's current deployment tooling. You will need to configure this setting manually in the Dashboard until Auth0 exposes it via the Management API and a0deploy.

Let me know if that is what you were looking for or not.

Kind Regards,
Nik