How to use OAuth2 for SMTP with Microsoft 365 without any end user interaction? - Just for background processing

[xcITs-Xian]

Hi Space!

We are in the process of integrating MailKit into one of our software projects.
We only have the need for SMTP (no IMAP, no POP3).

As Microsoft is going to discontinue SMTP AUTH in 2025 (see details here https://techcommunity.microsoft.com/t5/exchange-team-blog/exchange-online-to-retire-basic-auth-for-client-submission-smtp/ba-p/4114750), we are wondering how to use MailKit correctly without Basic Authentication for background processing.

We have searched a lot and found many examples how to use MailKit and Basic Auth, but there is (almost) no example showing the whole process of using MailKit with OAuth2 only.
The only good example we have found is this one from the examples folder: https://github.com/jstedfast/MailKit/blob/master/Documentation/Examples/OAuth2ExchangeExample.cs but it is not indented for background processing. (What we mean is, that there cannot be any user interaction in the software to authenticate the user to get a token. We need a solution that can be handled 100% in configuration files only.)

So we have the following questions / suggestions:

• Does anyone have the link/code to an example that shows the whole process of using MailKit with OAuth2 for SMTP with Microsoft 365 which does not require an user interaction? (We mean end user, it is clear that there need to be some configuration steps in Azure.)
  And I mean really a complete example, including the necessary configuration steps in Microsoft 365, etc.

• It would be great to have exactly this use case as an example in the MailKit documentation (maybe based on this code: https://github.com/jstedfast/MailKit/blob/master/Documentation/Examples/OAuth2ExchangeExample.cs). As I think 80% of developers using MailKit will/need to use Microsoft 365 exactly in that way. Such an example would help a lot of developers.

Or are we missing something here and not understanding the OAuth2 process correctly?

Thank you in advance for any helpful input!

[jstedfast]

Hi Xian,

I should probably update the examples in the Documentation directory (I forgot I even had a sample there), but the canonical documentation for MailKit+OAuth2 with Exchange can be found here: https://github.com/jstedfast/MailKit/blob/master/ExchangeOAuth2.md

That details 2 different methods of OAuth2, 1 that requires user interaction and 1 that is meant for (web) services where interaction is not possible.

[xcITs-Xian]

Hi Jeffrey,

thank you very much for the link. I hadn't seen this wiki page before, but it's exaclty what I was looking for!
Perfect!

And thank you for all your hard work in creating MailKit!

[Jceggbert5]

jstedfast,

I'm setting up something similar, and I'm following the steps on the page you listed. I'm getting stuck at the part where I do New-ServicePrincipal after logging in with Connect-Exchangeonline, and I'm concerned that some documentation may be missing since the migration to Entra and the deprecation of a lot of AAD. I'm getting the following error:

Write-ErrorMessage : |System.Exception|Error: AADServicePrincipalNotFound. No ServicePrincipal with Object Id
'redacted' for Client Application Id 'alsoredacted' is registered
in this tenant. Exchange Service Principals must refer to an existing Service Principal found in your tenant in Azure
Active Directory. Please verify you have correctly entered the ID parameters in this commandlet and that this Service
Principal is registered in your tenant.

I've verified a bunch of times, and I've even tried recreating my application on the web and again via commandline. I'm not sure what I'm missing.

I am grateful for any assistance you can provide.

(also, I'm replying here since this is a very recent topic about the documentation I'm specifically looking at. If this needs to be its own discussion, I'm happy to repost)

[jstedfast]

@Jceggbert5 I would recommend contacting Microsoft Support for help with this. Based on the error you got, it seems to me that you need to create the ServicePrincipal in your Tenant. If you are 100% sure you did that and are using the correct GUIDs, there's not really anything I can do to help.

In case it helps, this seems to be the docs you need: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal

[Jceggbert5]

@jstedfast Thank you so much for that extra info. It didn't get me 100% there, but it put me on the right track. Here's what I ended up needing to do, feel free to use any of this for your documentation:

1. Set up the new app using the "Registering..." and "Configuring..." sections of the article
2. On the custom app's page in Entra, go to App Roles and create an App Role, which spawns the security principal
   
3. Go to portal.azure.com, find Enterprise Applications, and select your application.
4. Here, there's a new Object ID that you use with the New-ServicePrincipal command instead of the one generated in Entra. You'll use the Entra one in the application, but this new one for this powershell command.
5. when doing Add-MailboxPermission, the service principal ID appears to be the SID from the Get-ServicePrincipal command.
6. You must use this command to allow the app to send as well: Add-RecipientPermission -Identity "mailbox@contoso.com" -Trustee SIDHERE -AccessRights SendAs

[xcITs-Xian]

@Jceggbert5 and everyone else in the space, the documentation steps from https://github.com/jstedfast/MailKit/blob/master/ExchangeOAuth2.md are totally correct.

The only tricky thing is, that you use the correct Object ID in this command:

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]

and then use the correct "Identity" property from this command Get-ServicePrincipal | fl for this command:

Add-MailboxPermission -Identity "john.smith@example.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

If you read carefully the steps in https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#register-service-principals-in-exchange, then it you get the idea.

It is not necessary to create a role as Jceggbert5 showed. You can skip this step.

The <OBJECT_ID> is the one shown in the Azure Portal under "Enterprise applications".

And the <SERVICE_PRINCIPAL_ID> is the "Identity" property of the created Exchange Online Service Principal.

The Add-MailboxPermission command is enough, you don't need the Add-RecipientPermission command.

Hope this helps someone in the future.