Office365 MailProxy 2.0.111

This software is intended for use as a mail proxy between legacy mail clients and Office 365, which requires an OAuth authentication since 2022. The proxy serves transparent in between and handles POP3 and SMTP procotol. The proxy can be used integrated in ET-Connector or standalone.

Setup office 365

The following steps show how to enable an application access through OAuth mechanism in Office 365. The principal is explained at https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth but documentation has some caveats.

Login into Entra Admin Center https://entra.microsoft.com/#view/Microsoft_AAD_IAM/TenantOverview.ReactView?Microsoft_AAD_IAM_legacyAADRedirect=true with administrative right

Goto the organization overview and note the organization-id or tenant-id

grafik.png

Register a new app

grafik.png

Give a useful name, i.e. O3654ET

grafik.png

Note the application-id of the new app!

grafik.png

Create a new secret and note the client secret value, not the client id!

Note: The client secret has an expiration date, take care of this date. If the service cannot login anymore, the server returns an error "unknown user name or bad password"

grafik.png

Add API permission

grafik.png

Type in "offi" to filter the list to point to "Office 365 Exchange Online"

grafik.png

Select app permissions for POP and SMTP

grafik.png

You need to have administrative rights to apply the "Administrator consent":

grafik.png

If it is approved, state shows approval.

grafik.png

Goto to organization applications overview and note down the object-id of the app. This object-id differs from the object-id in the application overview page. Be sure to use this id in the following scripts

grafik.png

Now we have to go to the PowerShell command line to apply the service principal.

Open PowerShell and install necessary modules

PS C:\Windows\system32> Install-Module -Name ExchangeOnlineManagement

Der NuGet-Anbieter ist erforderlich, um den Vorgang fortzusetzen.
PowerShellGet erfordert die NuGet-Anbieterversion 2.8.5.201 oder höher für die Interaktion mit NuGet-basierten
Repositorys. Der NuGet-Anbieter muss in "C:\Program Files\PackageManagement\ProviderAssemblies" oder
"C:\Users\andreas.DEVC\AppData\Local\PackageManagement\ProviderAssemblies" verfügbar sein. Sie können den
NuGet-Anbieter auch durch Ausführen von 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'
installieren. Möchten Sie den NuGet-Anbieter jetzt durch PowerShellGet installieren und importieren lassen?
[J] Ja  [N] Nein  [H] Anhalten  [?] Hilfe (Standard ist "J"):

Nicht vertrauenswürdiges Repository
Sie installieren die Module aus einem nicht vertrauenswürdigen Repository. Wenn Sie diesem Repository vertrauen, ändern
 Sie dessen InstallationPolicy-Wert, indem Sie das Set-PSRepository-Cmdlet ausführen. Möchten Sie die Module von
'PSGallery' wirklich installieren?
[J] Ja  [A] Ja, alle  [N] Nein  [K] Nein, keine  [H] Anhalten  [?] Hilfe (Standard ist "N"): j

PS C:\Windows\system32> Import-module ExchangeOnlineManagement

Connect to Office 365 by using the tenant-id:

PS C:\Windows\system32> Connect-ExchangeOnline -Organization be275558-e254-44fc-9fee-6db8<Snip>

Check, if tenant does not has SMTP disabled for organization:

PS C:\Windows\system32> Get-TransportConfig | Format-List SmtpClientAuthenticationDisabled


SmtpClientAuthenticationDisabled : False

Otherwise set it to $False

PS C:\Windows\system32> Set-TransportConfig -SmtpClientAuthenticationDisabled $false

Create a new service principal for the application by using the application-id and the object-id:

PS C:\Windows\system32> New-ServicePrincipal -AppId 2316b87a-03e5-4486-8d9c-760513<Snip> -ObjectId 856c6740-5fe3-4a25-87e2-c817569<Snip>

DisplayName                              ObjectId                                AppId
-----------                              --------                                -----
                                         856c6740-5fe3-4a25-87e2-c817569<Snip>    2316b87a-03e5-4486-8d9c-760513<Snip>

Optional: Give the service principal a nice name

PS C:\Windows\system32> Set-ServicePrincipal -Identity "856c6740-5fe3-4a25-87e2-c817569<Snip>" -DisplayName "O3654ETServicePrincipal"

Check, if service principal has been created

PS C:\Windows\system32> Get-ServicePrincipal

DisplayName                              ObjectId                                AppId
-----------                              --------                                -----
O3654ETServicePrincipal                  856c6740-5fe3-4a25-87e2-c817569<Snip>    2316b87a-03e5-4486-8d9c-760513<Snip>

Add the mailbox permission for each user setting the service principal as user by object-id with full rights. Repeat that for every user in the organization.


PS C:\Windows\system32> Add-MailboxPermission -Identity "firstname.lastname@example.com" -User "856c6740-5fe3-4a25-87e2-c817569<Snip>" -AccessRights FullAccess

Identity             User                 AccessRights                                                IsInherited Deny
--------             ----                 ------------                                                ----------- ----
3981b9ea-5550-4f0... S-1-5-21-16049184... {FullAccess}                                                False       False

Check if the user has not SMTP disabled:

PS C:\Windows\system32> Get-CASMailbox -Identity "<Mailboxidentifier>"

Name        ActiveSyncEnabled OWAEnabled PopEnabled ImapEnabled MapiEnabled SmtpClientAuthenticationDisabled
----        ----------------- ---------- ---------- ----------- ----------- --------------------------------
<Mailboxidentifier> True              True       True       True        True

In this case, there´s no value set, so set to $False

PS C:\Windows\system32> Get-CASMailbox -Identity "<Mailboxidentifier>"

Name        ActiveSyncEnabled OWAEnabled PopEnabled ImapEnabled MapiEnabled SmtpClientAuthenticationDisabled
----        ----------------- ---------- ---------- ----------- ----------- --------------------------------
<Mailboxidentifier> True              True       True       True        True        False

Well done!

Installation & running in ET-Connector

Installation & settings

Skripts

All scripts are available in a server_config.xml at https://downloads.devculture.eu

Start proxy

// ------------------------
// (C) by devculture.eu 
// ------------------------
// Starting O365Proxy
// ------------------------

import com.devc.o3654et.*;
import com.devc.logging.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.logging.Handler;
import com.sbs.data.*;
import com.sbs.server.*;

// Bridge class to log to transaction log
class ProxyLogHandler extends java.util.logging.Handler {
  private static java.util.logging.Formatter _F = new java.util.logging.SimpleFormatter();
  private static com.sbs.utils.logging.Log _LOG = com.sbs.utils.logging.LogManager.getManager().getLog(O365Proxy.class, "O365Proxy");
  public void publish( java.util.logging.LogRecord record ) {
    _LOG.log(com.sbs.utils.logging.Level.INFO, _F.formatMessage(record));
  }
  public void flush() {
  }
  public void close() throws SecurityException {
  }
}

// Enable logging to ET-Connector
Logger log = Logging.getInstance().getLogger(O365Proxy.class);
Handler[] lha = log.getHandlers();
for (int h=0;h<lha.length;h++) {
  log.removeHandler(lha[h]);
}
ProxyLogHandler tlh = new  ProxyLogHandler();
log.addHandler(tlh);
log.setLevel(Level.INFO); // Change log level here to get more details

O365Proxy p = O365Proxy.getInstance();
p.setLogger(log);
p.start();

Starting up the proxy is documented in system log

[ 2023-11-21 16:57:39.617 ] INFO: [ Server ] Call for workflow 'O365PROXY START' ...
[ 2023-11-21 16:57:39.852 ] INFO: [ O365Proxy ] +++ O365MailProxy 2.0.75 +++
[ 2023-11-21 16:57:39.852 ] INFO: [ O365Proxy ] Reloading configuration from C:/ET-Connector/modules/ext ...
[ 2023-11-21 16:57:39.867 ] INFO: [ O365Proxy ] Listen port for POP3 is 110
[ 2023-11-21 16:57:39.867 ] INFO: [ O365Proxy ] Listen port for SMTP is 25
[ 2023-11-21 16:57:39.867 ] INFO: [ O365Proxy ] Added account for andreas.schaefer@....
[ 2023-11-21 16:57:39.867 ] INFO: [ O365Proxy ] Added account for edi@....
[ 2023-11-21 16:57:39.867 ] INFO: [ O365Proxy ] Configuration applied

Stop proxy

// ------------------------
// (C) by devculture.eu 
// ------------------------
// Stopping O365Proxy
// ------------------------

import com.devc.o3654et.*;
import com.devc.logging.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.logging.Handler;
import com.sbs.data.*;
import com.sbs.server.*;

O365Proxy p = O365Proxy.getInstance();
p.stop();


Reload accounts

// ------------------------
// (C) by devculture.eu 
// ------------------------
// Reload accounts in O365Proxy
// ------------------------

import com.devc.o3654et.*;
import com.devc.logging.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.logging.Handler;
import com.sbs.data.*;
import com.sbs.server.*;

O365Proxy p = O365Proxy.getInstance();
p.reloadAccounts();

Show settings

// ------------------------
// (C) by devculture.eu 
// ------------------------
// Reload accounts in O365Proxy
// ------------------------

import com.devc.o3654et.*;
import com.devc.logging.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.logging.Handler;
import com.sbs.data.*;
import com.sbs.server.*;

O365Proxy p = O365Proxy.getInstance();
p.showSettings();

Check if O365 Proxy is running

If proxy is running, a thread is available in System-Manager

grafik.png

Configuration for POP3 service

In the POP3 service just remove the current password and set as server the localhost 127.0.0.1 and for port 110.

grafik.png

Configuration for SMTP service

In Options -> System notifcation settings set host to 127.0.01 and port to 25. Set the user and password.
Set the Office265 mail address in the From field ( [PRODUCTION|TEST] - From).

grafik.png

Installation & running standalone

Installation & settings

Check log messages in ./log directory for errors. Enjoy!

Troubleshooting

Error message "unknown user name or bad password"

The error can appear during runtime without any issue. If the next retrieval is successful, there´s nothing to worry about.

If the error message keeps every time, the client secret has an expiration date, take care of this date. If the service cannot login anymore, the server returns an error "unknown user name or bad password"

 

How is the proxy started with ET-Connector?

The proxy is started by a scheduler entry like this. Take care that proxy is only started in mode (here in PRODUCTION) mode

grafik.png

How can the GUI be accessed?

The GUI s accessible via the system tray. Therefore a console session is not sufficient for editing the configuration.

Permission denied

On startup the proxy reports a permission denied, which can have the following causes: