NLog.MailKit.Oauth2 6.0.2-oauthfork

NLog.MailKit

Alternative Mail target for NLog using MailKit. Compatible with .NET standard 2+

Including this package will replace the original mail target and has the same options as the original mail target, see docs of the original mailTarget

Currently not implemented:

• NTLM auth

This library is integration tested with the SmtpServer NuGet package

How to use

1. Install the package:

   Install-Package NLog.MailKit or in your csproj:

   <PackageReference Include="NLog.MailKit" Version="6.*" />
   

2. Add to your nlog.config:

   <extensions>
       <add assembly="NLog.MailKit"/>
   </extensions>
   

   Alternative register from code using fluent configuration API:

   LogManager.Setup().SetupExtensions(ext => ext.RegisterTarget<NLog.MailKit.MailTarget>());
   

See the NLog Wiki for available options and examples.

Note that the option skipCertificateValidation="true" can prevent AuthenticationException if your remote certificate for smtpServer is invalid - not recommend!

OAuth2 Support (SMTP Client Credentials Flow)

NLog.MailKit now supports authenticating with SmtpAuthenticationMode.OAuth2 so you can send mail through servers such as Office 365 / Exchange Online using the Azure AD (Entra ID) Client Credentials grant. It might work with other OAuth2 services but was only tested with Azure / Exchange Online.

For Exchange Online, your Application (Service Principal) must have the proper application permissions (full access) as described in Microsoft documentation:
Use client credentials grant flow to authenticate SMTP, IMAP and POP connections

Parameters for nlog.config / app.config

SmtpAuthentication = SmtpAuthenticationMode.OAuth2,
SmtpServer = "smtp.office365.com",
SmtpPort = 587,
SmtpUserName = "",
To = "",
From = "",
ApplicationId = "",
// Use SecretId or Thumbprint
SecretId = "",
SecretWindowsStoreCertificateThumbprint = "",
OAuthTokenUrl = "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
OAuthScope = "https://outlook.office365.com/.default",
RequireTLS = true

Key notes:

• Provide either SecretId (client secret) OR SecretWindowsStoreCertificateThumbprint (certificate in local Machine\My) for credential authentication (not both unless fallback is supported).
• OAuthTokenUrl usually contains your tenant id: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token. Insert tenant id if needed.
• OAuthScope for SMTP with application permissions is typically https://outlook.office365.com/.default.
• SmtpUserName is the mailbox you are sending from. Note it can differ from the From email, as long as it has Send-As permissions.
• OAuthTokenUrl is the URL where you retrive Token. Replace the tenantId for Azure.
• Ensure SMTP AUTH is enabled for the mailbox/tenant if your organization security settings have disabled it.

Example nlog.config target (OAuth2)

<target xsi:type="Mail"
        name="mail-oauth2"
        SmtpAuthentication="OAuth2"
        SmtpServer="smtp.office365.com"
        SmtpPort="587"
        RequireTLS="true"
        From=""
        To=""
        Subject="My OAuth2 Test Log ${longdate}"
        Body="Log Message: ${message}${newline}Level: ${level}${newline}Logger: ${logger}"
        ApplicationId=""
        SecretId=""
        SecretWindowsStoreCertificateThumbprint=""
        OAuthTokenUrl="https://login.microsoftonline.com//oauth2/v2.0/token"
        OAuthScope="https://outlook.office365.com/.default"
        SmtpUserName="">
</target>

Fluent configuration (C#) example

LogManager.Setup().SetupExtensions(ext => ext.RegisterTarget<NLog.MailKit.MailTarget>());

var mailTarget = new NLog.MailKit.MailTarget
{
    Name = "mail-oauth2",
    SmtpAuthentication = NLog.MailKit.SmtpAuthenticationMode.OAuth2,
    SmtpServer = "smtp.office365.com",
    SmtpPort = 587,
    RequireTLS = true,
    From = "",
    To = "",
    Subject = "My OAuth2 Test Log ${longdate}",
    Body = "Log Message: ${message}${newline}Level: ${level}${newline}Logger: ${logger}",
    ApplicationId = "",
    SecretId = "", // Or leave empty if using certificate
    SecretWindowsStoreCertificateThumbprint = "",
    OAuthTokenUrl = "https://login.microsoftonline.com//oauth2/v2.0/token",
    OAuthScope = "https://outlook.office365.com/.default",
    SmtpUserName = ""
};

var config = LogManager.Configuration ?? new NLog.Config.LoggingConfiguration();
config.AddTarget(mailTarget);
config.AddRuleForAllLevels(mailTarget);
LogManager.Configuration = config;

Security considerations

• Do NOT commit secrets; store them in environment variables, secret managers, or Azure Key Vault.
• Prefer certificate authentication (SecretWindowsStoreCertificateThumbprint) over client secrets where possible.
• Verify tenant policies: SMTP AUTH and application permissions must be appropriately configured.

License

BSD. License of MailKit is MIT