Help the legacy email application that does not support OAUTH to send and retrieve email from Office 365/Outlook/Hotmail by EA Oauth Service - Tutorial

Because Office 365 has disabled basic authentication in SMTP/POP/IMAP services, if you have a legacy email application that doesn’t support modern authentication (OAUTH), then you cannot use it to send and retrieve email from Office 365 account anymore.

For developers, you can add new codes to support OAUTH. However, if your code is too complex or out of maintenance, and you don’t want to change anything in your source codes, then EA Oauth Service can help the application to implement OAUTH.

This tutorial gives you a quick overview of how to use EA Oauth Service which can help the legacy email application to connect Office 365/Outlook/Hotmail without changing any codes.

How EA Oauth Service works?

  • Install "EA Oauth Service" on your machine.
  • Create a local user in "EA Oauth Service Manager", and add a mapped Office 365 user access token.
  • Change the email server address to localhost, and use local user and password in your application to login local SMTP/POP/IMAP services.
  • After "EA Oauth Service" accepts the connection from local user, it connects Office 365 server by the associated access token in background.
  • Finally, "EA Oauth Service" transfers data between the email application and Office 365 server under SSL/TLS encryption.
  • The access token is refreshed by "EA Oauth Service" automatically.
how eaoauth service works

You just need to change the server address, user and password in the email application, then the application can connect Office 365 without changing other things.

Install EA Oauth Service

You can download EA Oauth Service Installer and install it on your machine.

Double click the installer file and the installation will be executed automatically. The installer requires .NET framework 4.5 or later version to be installed. If no corresponding .NET framework is detected in your operating system, Setup will be aborted.

After the installation is completed, click “EA Oauth Service Manager” from Windows Start menu -> All Programs -> “EA Oauth Service” to begin the setup.

Note

Installation Permission

An account with Administrative Privileges is required to run the installer for installing “EA Oauth Service” on the machine.

Check local SMTP/POP/IMAP services

After EA Oauth Service is installed, it provides SMTP/POP/IMAP services on the local machine. You can open EA Oauth Service Manager -> Services to check the service status.

By default, the following inbound ports is used:

  • SMTP Service: 25, 465
  • POP Service: 110, 995
  • IMAP Service: 143, 993
eaoauth SMTP, POP, IMAP services

Note

If the service is failed to start, it is likely that other application on the machine used the port, you should change the listening port and start the service again.

Create local user in Oauth Service Manager

Now you need to create a local user in EA Oauth Service Manager -> Users:

  • Input your Office 365 email address as local user name.
  • Set a local password, this password is not your Office 365 password, it is used to connect local SMTP/POP/IMAP service.
  • Select permission (SMTP, POP/IMAP).
set local user in eaoauth service

Now you need to add a mapped Office 365 email account access token. There are two options:

Connect Office 365 by user login

With this option, you can use default setting for client id, tenant, then click Save. This option can also work with personal outlook.com/hotmail.com account.

Note

This option is recommended to the user who doesn’t have permission to create the application in Azure Portal.

Office 365 oauth by user login

Then you will be asked to login your Office 365 account by web browser.

login office365 by web browser

After the access token is retrieved successfully, you can see the token creation time and expiration time.

retrieve Office 365 access token

Note

It requires you re-login the Office 365 account before the refresh token is expired (about every 3 months).

Change server setting in the email application

After you create the local user and get the associated access token, the next step is changing your server settings in the application.

Use the following server address and port in the email application:

Protocol Server Address Port Encryption
SMTP localhost 25 None/STARTTLS/Auto
SMTP localhost 465 SSL/TLS
POP localhost 110 None/STARTTLS/Auto
POP localhost 995 SSL/TLS
IMAP localhost 143 None/STARTTLS/Auto
IMAP localhost 993 SSL/TLS

Here is the example setting in Outlook:

User setting in outlook

Then use the local user and local password (not your Office 365 password) for user authentication in the email application.

After the application connects local SMTP/POP/IMAP service successfully provided by EA Oauth Service, the service will connect Office 365 server by associated access token, and transfer data back to the application under SSL/TLS encryption.

Now the email application can send and retrieve email from Office 365 even it doesn’t support OAUTH.

Example code for C# application

Here is an example code for sending email using System.NET.Mail with OAUTH service:

using System;
using System.Net.Mail;

public static void SendEmail()
{
    var mailMessage = new MailMessage();

    // local user
    string office365OrGmailAddress = "test@o365orgmail.com";

    mailMessage.From = new MailAddress(office365OrGmailAddress);
    mailMessage.To.Add(new MailAddress("support@emailarchitect.net"));

    mailMessage.Subject = "Test from Oauth Service";
    mailMessage.IsBodyHtml = false;
    mailMessage.Body = "This is a test";

    var basicCredential = new System.Net.NetworkCredential(office365OrGmailAddress, "local password");

    var smtp = new SmtpClient("localhost");
    smtp.Port = 25;
    smtp.DeliveryFormat = SmtpDeliveryFormat.International;
    smtp.EnableSsl = true;
    smtp.DeliveryMethod = SmtpDeliveryMethod.Network;

    smtp.UseDefaultCredentials = false;
    smtp.Credentials = basicCredential;

    smtp.Send(mailMessage);
}

Accept remote connections from other machine

The legacy email application also can access the SMTP/POP/IMAP service from a remote machine.

  • Add access rule in Windows Firewall to allow inbound 25, 465, 110, 143, 993, 995 port;
  • Change listening address from localhost to * ;
  • Ignore the SSL certificate error in your application.

EA Oauth Service installed a self-signed certificate for SSL/TLS connection, the certificate is issued to localhost. If the application accesses the service from a remote machine, a certificate error will be reported.

You can use other SSL certificate by selecting certificate from EA Oauth Service Manager -> SMTP/POP/IMAP service -> Ssl Certificate.

Troubleshooting

Authentication is failed

If you get error about “Authentication”:

  • Check if the local password is set to the email application correctly;
  • Go to EA Oauth Service Manager -> Users -> Check if there is any token error.
check token error in EAOauth Service Manager

If there is token error, edit this user and try to:

  • Re-login your Office 365 account to retrieve new access token.
  • Check if the client secret value is expired, and create a new secret value in Azure Portal to replace current one.

Full Debug Log

If the email application cannot connect local SMTP/POP/IMAP service, you can enable full debug log like this:

  • Go to EA Oauth Service Manager -> Journal -> change Log Level to Full Debug.
  • Connect the SMTP/POP/IMAP service from the email application.
  • You can find log file in Journal shortly after the email application disconnects the service, check log content or send the log to our support email address for assistance.
  • Change log level back to “Only Error” to reduce the log file size.

The operation has timed out error in EA Oauth Service Manager

Please check if EAOauth Service is running from Administrative Tools -> Services, if this service is not running, start it.

Restart EAOauth Service

EAOauth background service can be restarted from Administrative Tools -> Services or use the following cmdlet in PowerShell:

Restart-Service "EAOauthSvc"

Free Email Support

Not enough? Please contact our technical support team.

Support@EmailArchitect.NET

Remarks

We usually reply emails within 24hours. The reason for getting no response is likely that your SMTP server bounced our reply. In this case, please try to use another email address to contact us. Your Gmail, Hotmail or Office 365 email account is recommended.