umbraco-mfa-login-provider

name	umbraco-mfa-login-provider
description	Implement MFA login providers for Umbraco backoffice using official docs
version	1.0.0
location	managed
allowed-tools	Read, Write, Edit, WebFetch

Umbraco MFA Login Provider

What is it?

An MFA Login Provider is the UI component for Two-Factor Authentication (2FA) in Umbraco. It provides the interface for users to enable/disable and configure their 2FA provider (e.g., Google Authenticator, SMS codes). The backend ITwoFactorProvider must be configured separately in C# - this extension type handles the frontend setup and configuration UI.

Documentation

Always fetch the latest docs before implementing:

• Two-Factor Authentication: https://docs.umbraco.com/umbraco-cms/run-in-production/security/two-factor-authentication
• Extension Types: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

Workflow

1. Fetch docs - Use WebFetch on the URLs above
2. Ask questions - What 2FA method? QR code setup? Custom validation UI?
3. Configure backend - Set up C# ITwoFactorProvider first
4. Generate frontend files - Create manifest + configuration element
5. Explain - Show what was created and how to test

Minimal Examples

Manifest (umbraco-package.json)

{
  "name": "My MFA Provider",
  "extensions": [
    {
      "type": "mfaLoginProvider",
      "alias": "My.MfaProvider.Authenticator",
      "name": "Authenticator App MFA",
      "forProviderName": "Umbraco.GoogleAuthenticator",
      "element": "/App_Plugins/MyMfa/mfa-setup.js",
      "meta": {
        "label": "Authenticator App"
      }
    }
  ]
}

Manifest (TypeScript)

import type { ManifestMfaLoginProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestMfaLoginProvider = {
  type: 'mfaLoginProvider',
  alias: 'My.MfaProvider.Authenticator',
  name: 'Authenticator MFA Provider',
  forProviderName: 'Umbraco.GoogleAuthenticator', // Must match backend provider name
  element: () => import('./mfa-setup.element.js'),
  meta: {
    label: 'Authenticator App',
  },
};

export const manifests = [manifest];

MFA Setup Element (mfa-setup.element.ts)

import { html, css, customElement, property, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
import type { UmbMfaProviderConfigurationElementProps } from '@umbraco-cms/backoffice/user';

@customElement('my-mfa-setup')
export class MyMfaSetupElement extends UmbLitElement implements UmbMfaProviderConfigurationElementProps {
  @property({ type: String })
  providerName = '';

  @property({ type: String })
  displayName = '';

  @property({ attribute: false })
  callback!: (providerName: string, code: string, secret: string) => Promise<{ error?: string }>;

  @property({ attribute: false })
  close!:  ;

  ()
   _loading = ;

  ()
   _secret = ;

  ()
   _qrCodeUrl = ;

  ()
   _code = ;

  ()
   _submitting = ;

  #?:  .;

  () {
    ();
    .(,  {
      .#notificationContext = context;
    });
  }

   () {
    .();
     .#();
  }

   #() {
     {
      
       response =  ();
       data =  response.();

      . = data.;
      . = data.;
    }  (error) {
      .#notificationContext?.(, { : { :  } });
    }  {
      . = ;
    }
  }

   #() {
    e.();

     (!. || .. !== ) {
      .#notificationContext?.(, { : { :  } });
      ;
    }

    . = ;

     {
       result =  .(., ., .);

       (result.) {
        .#notificationContext?.(, { : { : result. } });
      }  {
        .#notificationContext?.(, { : { :  } });
        .();
      }
    }  {
      . = ;
    }
  }

  () {
     (.) {
       html`;
    }

     html`;
  }

   styles = css`;
}

  ;

  {
    {
    : ;
  }
}

Using Default MFA Element

// If you don't need custom UI, you can use the built-in default element
// Just register the manifest without a custom element - Umbraco provides a default
const manifest: ManifestMfaLoginProvider = {
  type: 'mfaLoginProvider',
  alias: 'My.MfaProvider.Default',
  name: 'Default MFA Provider',
  forProviderName: 'Umbraco.GoogleAuthenticator',
  // No element specified - uses default
  meta: {
    label: 'Authenticator App',
  },
};

Backend C# Configuration (for reference)

// ITwoFactorProvider implementation
public class GoogleAuthenticatorProvider : ITwoFactorProvider
{
    public string ProviderName => "Umbraco.GoogleAuthenticator";

    public Task<bool> ValidateTwoFactorPIN(string secret, string code)
    {
        var twoFactorAuthenticator = new TwoFactorAuthenticator();
        return Task.FromResult(
            twoFactorAuthenticator.ValidateTwoFactorPIN(secret, code)
        );
    }

    public Task<bool> ValidateTwoFactorSetup(string secret, string code)
    {
        return ValidateTwoFactorPIN(secret, code);
    }

    public async Task<object> GetSetupDataAsync(Guid userKey, IMemberService memberService)
    {
        var secret = Base32Encoding.ToString(Guid.NewGuid().ToByteArray());
        var authenticator = new TwoFactorAuthenticator();
        var setupInfo = authenticator.GenerateSetupCode(
            "My App",
            userKey.ToString(),
            secret,
            false
        );

        return new
        {
            secret,
            qrCodeSetupImageUrl = setupInfo.QrCodeSetupImageUrl
        };
    }
}

// Register in Composer
public class  : 
{
    
    {
         identityBuilder =  BackOfficeIdentityBuilder(builder.Services);
        identityBuilder.AddTwoFactorProvider<GoogleAuthenticatorProvider>(
            GoogleAuthenticatorProvider.Name
        );
    }
}

Element Props Interface

Property	Type	Description
providerName	string	The provider identifier
displayName	string	Human-readable provider name
callback	Function	Call with code/secret to validate
close	Function	Close the setup modal

Callback Function

callback(providerName: string, code: string, secret: string): Promise<{ error?: string }>

Returns an object with an error property if validation failed, or empty object on success.

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.