CC.UmbracoProxy 1.1.0

CC.UmbracoProxy

Drop-in outbound HTTP/SMTP proxy and ForwardedHeaders support for Umbraco.

A single AddProxySupport() call wires:

• HttpClient.DefaultProxy (eagerly, so SDKs that bypass IHttpClientFactory — e.g. Azure SDK's BlobServiceClient — still route through your proxy)
• A singleton SocketsHttpHandler used as the primary handler for every IHttpClientFactory client
• ForwardedHeadersOptions (X-Forwarded-For / Proto / Host, with KnownProxies and CIDR KnownNetworks)
• A proxy-aware IEmailSender implementation that tunnels SMTP through the configured proxy via MailKit's HttpProxyClient

Requirements

• Umbraco 17.x (targets net10.0)

Install

dotnet add package CC.UmbracoProxy

Wire it up

In Program.cs:

using CC.UmbracoProxy.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddProxySupport()   // <-- one call
    .Build();

var app = builder.Build();

app.UseForwardedHeaders();   // only needed if Proxy:Forwarding:Enabled = true

// ... rest of pipeline

Configure

Add a Proxy section to appsettings.json:

{
  "Proxy": {
    "Forwarding": {
      "Enabled": false,
      "ForwardedHeaders": "XForwardedFor,XForwardedProto,XForwardedHost",
      "KnownProxies": [],
      "KnownNetworks": [ "10.0.0.0/8" ]
    },
    "Outbound": {
      "Enabled": true,
      "UseProxy": true,
      "HttpProxy": "http://10.2.2.241:3128",
      "HttpsProxy": "http://10.2.2.241:3128",
      "BypassOnLocal": true,
      "NoProxy": [ "localhost", "127.0.0.1" ],
      "UseDefaultCredentials": false,
      "Username": "",
      "Password": "",
      "AllowInvalidCertificates": false
    }
  }
}

Options

Proxy:Forwarding — inbound X-Forwarded-* header handling. Configures ASP.NET Core's ForwardedHeadersMiddleware. Leave Enabled: false if you are not behind a reverse proxy / load balancer.

Proxy:Outbound — routing for outbound HTTP/SMTP. Set Enabled: true and UseProxy: true to activate. HttpsProxy is preferred over HttpProxy when both are set. AllowInvalidCertificates: true disables TLS validation on SocketsHttpHandler — use only for corporate proxies with MITM cert inspection.

What gets registered

AddProxySupport() performs the following in this order:

1. Binds ProxyOptions from the Proxy configuration section (override the section name via the configSection parameter).
2. Sets HttpClient.DefaultProxy synchronously (for SDKs that bypass IHttpClientFactory).
3. Configures ForwardedHeadersOptions (parses KnownProxies IPs and KnownNetworks CIDR ranges).
4. Registers a singleton SocketsHttpHandler carrying the proxy + cert settings.
5. Wires HttpClientFactoryOptions.HttpMessageHandlerBuilderActions so every IHttpClientFactory-created client uses that handler as its primary handler.
6. Registers ProxiedUmbracoEmailSender as the unique IEmailSender (replaces Umbraco's default sender).

License

MIT