DX Improvement: Auto-generate authProvider manifests from backend external login configuration

[iOvergaard]

Problem

In V17, external login providers must be registered in two places:

1. Backend: ASP.NET Core authentication via AddBackOfficeExternalLogins()
2. Frontend: Extension manifest of type authProvider

This creates developer experience friction and potential for configuration mismatch. In V13 and earlier, only backend registration was needed - the frontend "just worked."

Proposed Solution

Auto-generate authProvider extension manifests from backend configuration using IPackageManifestReader.

Benefits

• Single source of truth - Backend auth configuration drives everything
• Matches V13 DX - Less migration friction, developers only configure once
• Reduces boilerplate - No manual manifest registration needed
• Eliminates registration mismatch - Backend and frontend always in sync
• Maintains extensibility - Can still register frontend-only providers if needed

Implementation Approach

Phase 1: Auto-Generation with Options Pattern (MVP)

Create AuthProviderManifestReader : IPackageManifestReader that generates manifests from registered authentication schemes.

Backend Options Extensions - Extend existing BackOfficeExternalLoginProviderOptions:

// In BackOfficeExternalLoginProviderOptions.cs
public class BackOfficeExternalLoginProviderOptions
{
    // Existing properties
    public ExternalSignInAutoLinkOptions AutoLinkOptions { get; set; } = new();
    public bool DenyLocalLogin { get; set; }
    
    // NEW: Control manifest auto-generation
    public bool AutoRegisterManifest { get; set; } = true;
    
    // NEW: Auto-redirect behavior
    public bool AutoRedirect { get; set; } = false;
    
    // NEW: Custom login button view
    public ExternalLoginCustomView? CustomView { get; set; }
    
    // NEW: Default button styling (when no custom view)
    public ExternalLoginDefaultView? DefaultView { get; set; }
    
    // NEW: Popup behavior configuration
    public ExternalLoginPopupBehavior? PopupBehavior { get; set; }
}

public class ExternalLoginCustomView
{
    /// <summary>
    /// Path to JavaScript file containing custom element, e.g., "/App_Plugins/MyPlugin/login-view.js"
    /// </summary>
    public string Element { get; set; } = string.Empty;
    
    /// <summary>
    /// Custom element tag name, e.g., "my-custom-login-view" (optional if default export)
    /// </summary>
    public string? ElementName { get; set; }
}

public class ExternalLoginDefaultView
{
    /// <summary>
    /// Icon for default button, e.g., "icon-google", "icon-microsoft"
    /// </summary>
    public string? Icon { get; set; }
    
    /// <summary>
    /// UUIInterfaceColor: "default", "positive", "warning", "danger"
    /// </summary>
    public string? Color { get; set; }
    
    /// <summary>
    /// UUIInterfaceLook: "default", "primary", "secondary", "outline", "placeholder"
    /// </summary>
    public string? Look { get; set; }
}

public class ExternalLoginPopupBehavior
{
    /// <summary>
    /// Window target for popup, e.g., "umbracoAuthPopup", "_blank"
    /// </summary>
    public string? PopupTarget { get; set; }
    
    /// <summary>
    /// Window features string, e.g., "width=800,height=600,menubar=no..."
    /// </summary>
    public string? PopupFeatures { get; set; }
}

Manifest Generation - Implement IPackageManifestReader:

public class AuthProviderManifestReader : IPackageManifestReader
{
    private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider;
    private readonly IOptionsMonitor<BackOfficeExternalLoginProviderOptions> _providerOptions;

    public async Task<IEnumerable<PackageManifest>> ReadAsync()
    {
        var schemes = await _authenticationSchemeProvider.GetAllSchemesAsync();
        var manifests = new List<PackageManifest>();
        
        foreach (var scheme in schemes)
        {
            // Only process Umbraco external login schemes
            if (!scheme.Name.StartsWith(Constants.Security.BackOfficeExternalAuthenticationTypePrefix))
                continue;
                
            var options = _providerOptions.Get(scheme.Name);
            
            // Skip if auto-registration disabled
            if (!options.AutoRegisterManifest)
                continue;
            
            var providerName = GetProviderName(scheme.Name); // Strip prefix
            
            var manifest = new PackageManifest
            {
                Extensions = new[]
                {
                    new // Dynamic object (no backend types yet)
                    {
                        type = "authProvider",
                        alias = $"Umbraco.AuthProvider.{providerName}",
                        name = providerName,
                        forProviderName = providerName,
                        meta = BuildMetaObject(options, scheme),
                        element = options.CustomView?.Element,
                        elementName = options.CustomView?.ElementName
                    }
                }
            };
            
            manifests.Add(manifest);
        }
        
        return manifests;
    }
    
    private object BuildMetaObject(BackOfficeExternalLoginProviderOptions options, AuthenticationScheme scheme)
    {
        return new
        {
            label = scheme.DisplayName ?? GetProviderName(scheme.Name),
            defaultView = options.DefaultView != null ? new
            {
                icon = options.DefaultView.Icon,
                color = options.DefaultView.Color,
                look = options.DefaultView.Look
            } : null,
            behavior = new
            {
                autoRedirect = options.AutoRedirect,
                popupTarget = options.PopupBehavior?.PopupTarget,
                popupFeatures = options.PopupBehavior?.PopupFeatures
            },
            linking = new
            {
                allowManualLinking = options.AutoLinkOptions.AllowManualLinking
            }
        };
    }
}

Generated Manifest Example:

{
  "type": "authProvider",
  "alias": "Umbraco.AuthProvider.Google",
  "name": "Google",
  "forProviderName": "Google",
  "meta": {
    "label": "Sign in with Google",
    "defaultView": {
      "icon": "icon-google",
      "color": "positive",
      "look": "primary"
    },
    "behavior": {
      "autoRedirect": false,
      "popupTarget": "umbracoAuthPopup",
      "popupFeatures": "width=600,height=600"
    },
    "linking": {
      "allowManualLinking": true
    }
  },
  "element": "/App_Plugins/MyCompany/google-login.js",
  "elementName": "my-company-google-login"
}

Usage Example:

public static class GoogleAuthenticationExtensions
{
    public static IUmbracoBuilder AddGoogleAuthentication(this IUmbracoBuilder builder)
    {
        builder.Services.ConfigureOptions<GoogleBackOfficeExternalLoginProviderOptions>();
        
        builder.AddBackOfficeExternalLogins(logins =>
        {
            logins.AddBackOfficeLogin(backOfficeAuthenticationBuilder =>
            {
                var schemeName = BackOfficeAuthenticationBuilder.SchemeForBackOffice("Google");
                
                backOfficeAuthenticationBuilder.AddGoogle(schemeName, options =>
                {
                    options.ClientId = "YOUR_CLIENT_ID";
                    options.ClientSecret = "YOUR_CLIENT_SECRET";
                });
            });
        });
        
        return builder;
    }
}

public class GoogleBackOfficeExternalLoginProviderOptions : IConfigureNamedOptions<BackOfficeExternalLoginProviderOptions>
{
    public void Configure(string? name, BackOfficeExternalLoginProviderOptions options)
    {
        if (name != BackOfficeAuthenticationBuilder.SchemeForBackOffice("Google"))
            return;
            
        options.AutoLinkOptions = new ExternalSignInAutoLinkOptions(
            autoLinkExternalAccount: true,
            defaultUserGroups: ["editor"],
            allowManualLinking: true
        );
        
        // NEW: Frontend manifest configuration
        options.AutoRedirect = false;
        options.DefaultView = new ExternalLoginDefaultView
        {
            Icon = "icon-google",
            Color = "positive",
            Look = "primary"
        };
        
        // Optional: Custom login button
        // options.CustomView = new ExternalLoginCustomView
        // {
        //     Element = "/App_Plugins/MyCompany/google-login.js",
        //     ElementName = "my-company-google-login"
        // };
    }
    
    public void Configure(BackOfficeExternalLoginProviderOptions options) => Configure(null, options);
}

Backend to Frontend Property Mapping

Backend Property	Frontend Property	Type	Notes
scheme.DisplayName	meta.label	string	Display name for the provider
AutoRedirect	meta.behavior.autoRedirect	bool	Auto-redirect to provider on login page
AutoLinkOptions.AllowManualLinking	meta.linking.allowManualLinking	bool	Allow users to manually link accounts
DefaultView.Icon	meta.defaultView.icon	string	Icon for default button (e.g., "icon-google")
DefaultView.Color	meta.defaultView.color	string	Button color: "default", "positive", "warning", "danger"
DefaultView.Look	meta.defaultView.look	string	Button look: "default", "primary", "secondary", "outline"
PopupBehavior.PopupTarget	meta.behavior.popupTarget	string	Window target (e.g., "_blank", "umbracoAuthPopup")
PopupBehavior.PopupFeatures	meta.behavior.popupFeatures	string	Window.open features string
CustomView.Element	element	string	JS file path: "/App_Plugins/MyPlugin/login.js"
CustomView.ElementName	elementName	string	Custom element tag name (optional if default export)

Frontend Type Reference

From src/Umbraco.Web.UI.Client/src/packages/core/auth/auth-provider.extension.ts:

export interface ManifestAuthProvider extends ManifestElement {
    type: 'authProvider';
    forProviderName: string;
    meta?: MetaAuthProvider;
}

export interface MetaAuthProvider {
    label?: string;
    defaultView?: {
        icon?: string;
        color?: UUIInterfaceColor;
        look?: UUIInterfaceLook;
    };
    behavior?: {
        autoRedirect?: boolean;
        popupTarget?: string;
        popupFeatures?: string;
    };
    linking?: {
        allowManualLinking?: boolean;
    };
}

Considerations

1. Opt-Out for Advanced Scenarios

• Set options.AutoRegisterManifest = false to disable auto-generation
• Allows full manual control when needed

2. Custom Views Require Explicit Configuration

• Backend cannot implement custom elements (JavaScript code)
• Must provide element (JS file path) and optionally elementName
• Default behavior (no CustomView) uses framework's built-in button UI

3. Element Loading

• Critical: element property references a JavaScript file, not a globally available element
• Frontend loads the module via the element path
• elementName specifies the custom element tag to instantiate (optional if default export)

4. Backward Compatibility

• Existing frontend-only authProvider registrations continue to work
• Extension registry handles duplicates (last-wins or merge strategy)
• No breaking changes - purely additive feature

5. Default Values

• If properties not specified, frontend uses sensible defaults
• Matches existing frontend behavior for missing meta properties

Phase 2: Type Safety (Future Enhancement)

Create strongly-typed C# interfaces instead of dynamic manifest objects:

public interface IAuthProviderManifest
{
    string Type { get; }
    string Alias { get; }
    string Name { get; }
    string ForProviderName { get; }
    AuthProviderMeta? Meta { get; }
    string? Element { get; }
    string? ElementName { get; }
}

public class AuthProviderMeta
{
    public string? Label { get; set; }
    public DefaultViewOptions? DefaultView { get; set; }
    public BehaviorOptions? Behavior { get; set; }
    public LinkingOptions? Linking { get; set; }
}

Phase 3: Architectural Cleanup (Related Issue)

Consider moving login app into backoffice after cookie-based auth changes:

• Login screen is currently a separate app
• Auth providers need frontend registration primarily for timeout modal (which is already in backoffice)
• After V17 cookie changes, separation is less justified
• Could simplify manifest loading and context sharing

Related Work

• External login provider documentation updated in CMS: Updates code examples for external login providers for V17 UmbracoDocs#7764
• Cookie-based authentication implemented in V17
• IPackageManifestReader infrastructure already exists

Success Criteria

• Implement AuthProviderManifestReader : IPackageManifestReader
• Extend BackOfficeExternalLoginProviderOptions with new properties
• Add ExternalLoginCustomView, ExternalLoginDefaultView, ExternalLoginPopupBehavior classes
• Register manifest reader in DI
• Update documentation with new Options pattern
• Add integration tests for manifest generation
• Verify backward compatibility with existing frontend registrations
• Update external login provider examples in documentation

[madsrasmussen]

I definitely see the benefit of an improved DX in this case. The majority of the work happens on the server, and the client-side manifests are just annoying to add.

I am a bit concerned about the Management API starting to know about “elements,” “api,” etc., which is really only something we use in the Backoffice UI.

Would it be possible to do the auth provider -> manifest automapping on the client? If the Management API had an endpoint for all the Auth Provider “registrations,” then we could automap to a manifest on the client with a default implementation. Only if you needed something really advanced would you have to bring your own manifest/element.

We currently do the same for Health Checks. Most logic happens server-side, and then we turn it into a manifest client-side. If we want to go down the server generates manifests routes, I think we should start considering it a secondary product rather than the Management Api. Maybe it would be closer to what UI Builder could support 🤔

[iOvergaard]

Yeah, this has nothing to do with the Management API necessarily. While we usually communicate through that API, this was not possible in this case. So we are in a hybrid approach, which does not provide good DX for anyone. My thoughts are mainly towards using the Extension API, which is great still, and provides a lot of flexibility while also giving the developer a good experience.

Would it be possible to do the auth provider -> manifest automapping on the client?

Yes, but we would use the IPackageManifestReader, which picks up the manifests. I mean, we could map on the client, but then the auth providers are not necessarily available on the login screen, or at least we would have to add a spinner just in case there are login providers to show. And suddenly, you could be redirected because one of them stipulates that you cannot show local login. But manifests are, of course, also async, so they could cause a load, too.

I think we should pull out the configuration to "skip local login" and add it to a server setting, so the client knows up front.

[iOvergaard]

The concern specifically for auth providers is mainly that in 90% of cases, you don’t need a custom element. You only need to tell the frontend what is there. It could have been a management API endpoint, honestly. But since you have the added ability to create a custom element, we went with a manifest instead. However, in those 90% of the cases where you don’t need a custom element, it only adds noise that you have to register it manually in a JSON file and have to remember to copy over the same values that you just wrote in C#.

If you set up the backend to “skip local login”, you must remember to copy that to the umbraco-package.json file, too

If you change the name of the provider on the backend, you must remember to change the “forProviderName” in the umbraco-package.json file, too