Support for SMTP OAuth authentication

[aguyfromdenmark]

Lately, we have been contacted by multiple clients who would like to use OAuth for SMTP authentication. As it is, Umbraco CMS only supports Basic Auth. As Microsoft is deprecating Basic Authentication for SMTP by September 2025, I only expect more of these inquiries.

For now, you can implement your own IEmailSender. But if this is going to be prevalent, Ithink it will make sense for Umbraco CMS to support this out of the box.

[bergmania]

Sounds like a good idea, if you can make the current implementation of IEmailSender support it, we will like the contribution.

[aguyfromdenmark]

I don't think I will be able to do it, but I found this that I think could be implemented in a way: https://github.com/jstedfast/MailKit/blob/master/ExchangeOAuth2.md

[kasparboelkjeldsen]

@bergmania I got a client requesting this, as their IT department is going to shut down Basic Auth start of 2025, so I'll take a stab at making whatever here-and-now solution I'm building into a suitable pull request.

[kasparboelkjeldsen]

@bergmania follow up question:
For my client I'm just gonna roll a solution using Microsoft.Identity.Client but I'm curious what the prefered approach would be for the CMS? Would Microsoft.Identity.Client be ok, or would you prefer a minimal http client implementation to get the token or another library?

[bergmania]

Preferable no new external dependencies.

[kasparboelkjeldsen]

@bergmania @aguyfromdenmark
TLDR;
I don't think SMTP/OAuth2 is implementable without doing a massive amount of work - I've made IEmailSenderClient and extract the current SMTP client to a BasicSmtpEmailSenderClient, allowing to easily roll your own client without having to implement all the code Umbraco has to create the MimeMessage.

I've made a pull request here #17484

Longer Read:

So it turns out this is complicated.

MailKit has a rudementary OAuth2 implementation where you hand it a username and a token and it goes off and does it's thing, and I now understand why it doesn't help you get the token.

It turns out we would have to write -many- oauth options and implementations to be able to get an access token, and even then it would most of the time not accomplish what an user was actually hoping to do, which is to send an e-mail.

Microsofts Azure/Exchange solution is neigh impossible to set up correctly, and definitely currently not possible to set up following Microsoft's documentation. They are leaning heavily towards you using Microsoft Graph as a means of sending e-mails, which means abandoning SMTP. (If ANYONE has gotten this to work without giving the app registration godlike powers, write me)

Google's api's for authorization (Google.Apis.Auth) as of this date, returns service worker access tokens that are too big to send over SMTP and will get rejected by Google's own servers. Again. leaning towards you using their APIs to send the email instead of SMTP.

Sendgrid/Mailchimp/Mailgun etc. currently don't support SMTP with OAuth, so the case for actually using OAuth2 for authorization in SMTP is right now very small.

Even assuming all of the above actually worked, and wasn't hard/impossible to do right now, we are still left with way too many variables as to how you fetch your original access token to be able to make a general solution that would support pretty much anything, as it can be based of client-id/secret, client-id/secret-as-json-file or client-id/p12-certificate and I'm sure and bunch of others.
All of them seeming hard to fit into a SMTP setting in the global config, and would be a -lot- to support.

Instead I lean towards supporting basic SMTP authentication with username/password like now, and instead making integration to other providers solutions easier. There is still nothing preventing anything from rolling their own client, but with my pull request, now you can add your own "IEmailSenderClient" to your solution and only have to implement a single method to be in control of how Umbraco sends out your e-mail.

I have updated EmailSender to use a default implementation of IEmailSenderClient (that is the Mailkit SMTP client) and it will then be trivial to support other sending-methods by just applying your own implementation, without having to also implement all the logic Umbraco already has in constructing the MimeMessage.

Following quick example would send the e-mail through Microft Graph and could also make for a bunch of small packages for Umbraco so people can quickly get up to speed with a new email solution.

public class MicrosoftGraphEmailClientComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddTransient<IEmailSenderClient, MicrosoftGraphEmailClient>();
    }
}
public class MicrosoftGraphEmailClient : IEmailSenderClient
{
    private ClientSecretCredential? credentials;
    public MicrosoftGraphEmailClient()
    {
        var tenantId = "<tenant-id>";

        // Values from app registration
        var clientId = "<client-id>";
        var clientSecret = "<client-secret>";

        // using Azure.Identity;
        var options = new TokenCredentialOptions
        {
            AuthorityHost = AzureAuthorityHosts.AzurePublicCloud
        };

        credentials = new ClientSecretCredential(
            tenantId, clientId, clientSecret, options);

        if (credentials == null)
        {
            throw new ArgumentNullException(nameof(credentials));
        }
    }

    public async Task SendAsync(MimeMessage? mimeMessage)
    {
        if (mimeMessage == null)
        {
            throw new ArgumentNullException(nameof(mimeMessage));
        }

        var scopes = new[] { "https://graph.microsoft.com/.default" };

        var graphClient = new GraphServiceClient(credentials, scopes);

        var stream = new MemoryStream();
        mimeMessage.WriteTo(stream);

        var base64content = Convert.ToBase64String(stream.ToArray());
        var ri = graphClient.Users[mimeMessage.From.ToString()].SendMail.ToPostRequestInformation(new SendMailPostRequestBody());

        ri.Headers.Clear();// replace the json content header
        ri.SetStreamContent(new MemoryStream(Encoding.UTF8.GetBytes(base64content)), "text/plain");

        var result = await graphClient.RequestAdapter.SendAsync<Message>(ri, Message.CreateFromDiscriminatorValue);
    }
}

This will allow some the community to easliy roll packages that implements cloud/vendor-specific email-clients

[aguyfromdenmark]

Nice and thorough! Great!

While reading it, I had a thought. Could this be possible/feasible/simplified by utilizing the Umbraco Authorized Services package for the authentication part?

[AKQAPeterKirk]

Hi - is there an implementation to replace or upgrade the form workflow "send email with template" so it uses OAuth2 instead of basic authentication when communicating with Microsoft office 365 - for Umbraco 13 on cloud.

[kasparboelkjeldsen]

@AKQAPeterKirk I did a pull request that would make that easier, but I believe it's only available in v15+

That being said, I've had to change the email to OAuth2 in V13 as well, and just had to rip out the Umbraco IEmailSender and provide my own, which sadly means re-implementing almost all of their logic too.

We ended up using the graph api in Azure for sending the e-mails since their OAuth2 implementation is almost impossible to get working right, but this is the minimal version of what I ended up having running in production on a v13 site.

public class CustomEmailSenderComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        var serviceDescriptor = ServiceDescriptor.Singleton<IEmailSender, CustomEmailSender>();
        builder.Services.Replace(serviceDescriptor);
    }
}
public class CustomEmailSender : IEmailSender
{
    private readonly IEventAggregator _eventAggregator;
    private readonly ILogger<Umbraco.Cms.Infrastructure.Mail.EmailSender> _logger;
    private readonly bool _notificationHandlerRegistered;
    private readonly GlobalSettings _globalSettings;
    private ClientSecretCredential? credentials;
    public CustomEmailSender(
    ILogger<Umbraco.Cms.Infrastructure.Mail.EmailSender> logger,
    IOptionsMonitor<GlobalSettings> globalSettings,
    IEventAggregator eventAggregator
    )
    {
        _logger = logger;
        _globalSettings = globalSettings.CurrentValue;
        _eventAggregator = eventAggregator;
        _notificationHandlerRegistered = false;
        _eventAggregator = eventAggregator;

        var tenantId = "<your tenant>";

        // Values from app registration
        var clientId = "<your client id>";
        var clientSecret = "<your secret>";

        // using Azure.Identity;
        var options = new TokenCredentialOptions
        {
            AuthorityHost = AzureAuthorityHosts.AzurePublicCloud
        };

        credentials = new ClientSecretCredential(
            tenantId, clientId, clientSecret, options);

        if (credentials == null)
        {
            throw new ArgumentNullException(nameof(credentials));
        }
    }
    public bool CanSendRequiredEmail()
    {
        return _globalSettings.IsSmtpServerConfigured
                                        || _globalSettings.IsPickupDirectoryLocationConfigured
                                        || _notificationHandlerRegistered;
    }

    public Task SendAsync(EmailMessage message, string emailType)
    {
        return SendAsyncInternal(message, emailType, false);
    }

    public Task SendAsync(EmailMessage message, string emailType, bool enableNotification)
    {
        return SendAsyncInternal(message, emailType, enableNotification);
    }

    private async Task SendAsyncInternal(EmailMessage message, string emailType, bool enableNotification)
    {
        if (enableNotification)
        {
            var notification =
                new SendEmailNotification(message.ToNotificationEmail(_globalSettings.Smtp?.From), emailType);
            await _eventAggregator.PublishAsync(notification);

            // if a handler handled sending the email then don't continue.
            if (notification.IsHandled)
            {
                if (_logger.IsEnabled(Microsoft.Extensions.Logging.LogLevel.Debug))
                {
                    _logger.LogDebug(
                    "The email sending for {Subject} was handled by a notification handler",
                    notification.Message.Subject);
                }
                return;
            }
        }

        if (!_globalSettings.IsSmtpServerConfigured && !_globalSettings.IsPickupDirectoryLocationConfigured)
        {
            if (_logger.IsEnabled(Microsoft.Extensions.Logging.LogLevel.Debug))
            {
                _logger.LogDebug(
                "Could not send email for {Subject}. It was not handled by a notification handler and there is no SMTP configured.",
                message.Subject);
            }
            return;
        }

        if (_globalSettings.IsPickupDirectoryLocationConfigured &&
            !string.IsNullOrWhiteSpace(_globalSettings.Smtp?.From))
        {
            // The following code snippet is the recommended way to handle PickupDirectoryLocation.
            // See more https://github.com/jstedfast/MailKit/blob/master/FAQ.md#q-how-can-i-send-email-to-a-specifiedpickupdirectory
            do
            {
                var path = Path.Combine(_globalSettings.Smtp.PickupDirectoryLocation!, Guid.NewGuid() + ".eml");
                Stream stream;

                try
                {
                    stream = System.IO.File.Open(path, FileMode.CreateNew);
                }
                catch (IOException)
                {
                    if (System.IO.File.Exists(path))
                    {
                        continue;
                    }

                    throw;
                }

                try
                {
                    using (stream)
                    {
                        using var filtered = new FilteredStream(stream);
                        filtered.Add(new SmtpDataFilter());

                        FormatOptions options = FormatOptions.Default.Clone();
                        options.NewLineFormat = NewLineFormat.Dos;

                        await message.ToMimeMessage(_globalSettings.Smtp.From).WriteToAsync(options, filtered);
                        filtered.Flush();
                        return;
                    }
                }
                catch
                {
                    System.IO.File.Delete(path);
                    throw;
                }
            }
            while (true);
        }

        await SendAsync(message.ToMimeMessage(_globalSettings.Smtp!.From));
    }

    public async Task SendAsync(MimeMessage? mimeMessage)
    {
        if (mimeMessage == null)
        {
            throw new ArgumentNullException(nameof(mimeMessage));
        }
        var scopes = new[] { "https://graph.microsoft.com/.default" };

        var graphClient = new GraphServiceClient(credentials, scopes);

        var stream = new MemoryStream();
        mimeMessage.WriteTo(stream);

        var base64content = Convert.ToBase64String(stream.ToArray());
        var ri = graphClient.Users[mimeMessage.From.ToString()].SendMail.ToPostRequestInformation(new SendMailPostRequestBody());

        ri.Headers.Clear();// replace the json content header
        ri.SetStreamContent(new MemoryStream(Encoding.UTF8.GetBytes(base64content)), "text/plain");

        var result = await graphClient.RequestAdapter.SendAsync<Message>(ri, Message.CreateFromDiscriminatorValue);

    }
}

internal static class EmailMessageExtensions
{
    public static MimeMessage ToMimeMessage(this EmailMessage mailMessage, string configuredFromAddress)
    {
        var fromEmail = string.IsNullOrEmpty(mailMessage.From) ? configuredFromAddress : mailMessage.From;

        if (!InternetAddress.TryParse(fromEmail, out InternetAddress fromAddress))
        {
            throw new ArgumentException(
                $"Email could not be sent.  Could not parse from address {fromEmail} as a valid email address.");
        }

        var messageToSend = new MimeMessage { From = { fromAddress }, Subject = mailMessage.Subject };

        AddAddresses(messageToSend, mailMessage.To, x => x.To, true);
        AddAddresses(messageToSend, mailMessage.Cc, x => x.Cc);
        AddAddresses(messageToSend, mailMessage.Bcc, x => x.Bcc);
        AddAddresses(messageToSend, mailMessage.ReplyTo, x => x.ReplyTo);

        if (mailMessage.HasAttachments)
        {
            var builder = new BodyBuilder();
            if (mailMessage.IsBodyHtml)
            {
                builder.HtmlBody = mailMessage.Body;
            }
            else
            {
                builder.TextBody = mailMessage.Body;
            }

            foreach (EmailMessageAttachment attachment in mailMessage.Attachments!)
            {
                builder.Attachments.Add(attachment.FileName, attachment.Stream);
            }

            messageToSend.Body = builder.ToMessageBody();
        }
        else
        {
            messageToSend.Body =
                new TextPart(mailMessage.IsBodyHtml ? TextFormat.Html : TextFormat.Plain) { Text = mailMessage.Body };
        }

        return messageToSend;
    }

    public static NotificationEmailModel ToNotificationEmail(
        this EmailMessage emailMessage,
        string? configuredFromAddress)
    {
        var fromEmail = string.IsNullOrEmpty(emailMessage.From) ? configuredFromAddress : emailMessage.From;

        NotificationEmailAddress? from = ToNotificationAddress(fromEmail);

        return new NotificationEmailModel(
            from,
            GetNotificationAddresses(emailMessage.To),
            GetNotificationAddresses(emailMessage.Cc),
            GetNotificationAddresses(emailMessage.Bcc),
            GetNotificationAddresses(emailMessage.ReplyTo),
            emailMessage.Subject,
            emailMessage.Body,
            emailMessage.Attachments,
            emailMessage.IsBodyHtml);
    }

    private static void AddAddresses(MimeMessage message, string?[]? addresses, Func<MimeMessage, InternetAddressList> addressListGetter, bool throwIfNoneValid = false)
    {
        var foundValid = false;
        if (addresses != null)
        {
            foreach (var address in addresses)
            {
                if (InternetAddress.TryParse(address, out InternetAddress internetAddress))
                {
                    addressListGetter(message).Add(internetAddress);
                    foundValid = true;
                }
            }
        }

        if (throwIfNoneValid && foundValid == false)
        {
            throw new InvalidOperationException("Email could not be sent. Could not parse a valid recipient address.");
        }
    }

    private static NotificationEmailAddress? ToNotificationAddress(string? address)
    {
        if (InternetAddress.TryParse(address, out InternetAddress internetAddress))
        {
            if (internetAddress is MailboxAddress mailboxAddress)
            {
                return new NotificationEmailAddress(mailboxAddress.Address, internetAddress.Name);
            }
        }

        return null;
    }

    private static IEnumerable<NotificationEmailAddress>? GetNotificationAddresses(IEnumerable<string?>? addresses)
    {
        if (addresses is null)
        {
            return null;
        }

        var notificationAddresses = new List<NotificationEmailAddress>();

        foreach (var address in addresses)
        {
            NotificationEmailAddress? notificationAddress = ToNotificationAddress(address);
            if (notificationAddress is not null)
            {
                notificationAddresses.Add(notificationAddress);
            }
        }

        return notificationAddresses;
    }
}

There isn't really a happy implementation for you where you don't strip out all of their emailsender and implement your own unless you upgrade.

[bjarnef]

Has anybody a workaround to handle this in Umbraco 8 using smtp.office365.com as it isn't possible to override default implementation of email sender #13750 using for e.g. invite user flow from backoffice.

It seems the deprecation has been postponed to March/April 2026:
https://techcommunity.microsoft.com/blog/exchange/exchange-online-to-retire-basic-auth-for-client-submission-smtp-auth/4114750

[kasparboelkjeldsen]

@bjarnef https://github.com/umbraco/Umbraco-CMS/blob/release-8.18.0/src/Umbraco.Core/EmailSender.cs EmailSender looks perfectly overridable to me in v8 ? Implementation and Interface are both public ?

If it's because some part of Umbraco V8 only uses the EmailSender directly and not the IEmailSender then I guess you are left with the dangerous option of patching the method - which I did a talk about recently and stressed we probably shouldn't do it, ever, but here we are :D

You could use Harmony to prefix the public async Task SendAsync(MailMessage message) and implement your own instead.

V15 example of doing something like that here, but I've done it V8 as well, and the process is the same.
https://github.com/kasparboelkjeldsen/maytalk/blob/main/MayTalk/Patches/PatchUmbracoServicesExtension.cs

[bjarnef]

#13750 mention it still use default implementation, e.g. for invite user. So if it doesn't use the custom implementation throughout the application, I don't think it worth spending too much time trying to solve.
I would probably recommend the customer to use another SMTP service like Mailgun, SendGrid, Postmark or focus on migration of the project.