CoolSpools Email with Microsoft 365 and OAUTH 2.0

Background

While CoolSpools allows you to send email messages directly from your IBM i server to remote mail servers, you can also relay email messages via your corporate mail server (e.g. Domino, On-Premise Exchange, Microsoft 365). This is achieved using SMTP, the industry standard mechanism for email communications.

Historically, it was possible to establish an SMTP connection to the Microsoft 365 cloud mail server using Basic Authentication (i.e. by providing a valid username and password), but since 2022 Microsoft have been revoking Basic Authentication for various services, and are now doing the same for SMTP, meaning that it will no longer be possible for CoolSpools to relay email messages via the Microsoft 365 mail server by using a simple username and password.

It is still possible for CoolSpools to connect to the Microsoft 365 mail server, but authentication must now use an OAUTH 2.0 token.

Use of OAUTH 2.0 authentication requires CoolSpools V7R1 fix pack 078 or above, and IBM i operating system 7.3 or above. Unfortunately, it also requires some relatively complex configuration within the Microsoft 365 environment, including changes within Entra ID and the execution of PowerShell commands, so it is recommended that the Microsoft Configuration steps be conducted by an administrator with Microsoft systems knowledge.

Microsoft Configuration

There are a few values of which you will need to make a note, as they will be needed later in the CoolSpools configuration.

Directory/Tenant ID	<tenantid>	abcd1234-ef56-gh78-9123-45ijklm67890
Application/Client ID	<clientid>	abcd1234-ef56-gh78-9123-45ijklm67890
Enterprise Application Object ID	<objectid>	abcd1234-ef56-gh78-9123-45ijklm67890
Client Secret Value	<clientsecret>	abcd123-4ef56.gh789123~45ijkl

Open Entra ID

Check Microsoft documentation for the latest instructions, but at the time of writing you can navigate to Entra ID at https://entra.microsoft.com/ and log on as a user with admin rights.

From the left-hand menu select Overview – this page displays information about your site, including the Tenant ID – take a note of this value as you will need it later.

Create App Registration

Now select Applications > App Registrations from the left-hand menu. This displays the different applications registered on your site – we are going to create a new app registration named COOLSPOOLS.

Select New registration then complete the form as follows:

Name: COOLSPOOLS

Who can use this application or API: Accounts in this organizational directory only

Redirect URI: Leave this as the default

Click on Register and then note the Application (Client) ID from the confirmation screen. You also need to note an Object ID, but not the one displayed in the App Registration page.

Instead, open Applications > Enterprise Applications and select COOLSPOOLS – make a note of the Object ID displayed here.

Add Client Secret

Now, return to the COOLSPOOLS App Registration page. We are going to add a Client Secret, which forms the basis of OAUTH authentication. Open Manage > Certificates & secrets, and then click New client secret. Populate the form as follows:

Description: CoolSpools SMTP

Expires: Select an expiry period that meets your business policies. Note that you will need to update configuration in MS Entra ID and in CoolSpools at the end of the expiry period, when the Client secret is updated.

Click on Add. It is very important that you make a note of the Secret value that is displayed (not the Secret ID) as this is the only time it will be shown and you will not be able to display it later.

Add API Permissions

Now we need to enable SMTP access to Microsoft 365 via the COOLSPOOLS application.

From the COOLSPOOLS App registration select Manage > API Permissions.

Click Add a permission then choose APIs my organization uses.

In the search bar enter Office 365 Exchange Online and click on it when it is displayed in the list. You will be asked What type of permissions does your application require? – select Application permissions.

Either search for, or scroll down to, the SMTP category and expand it to see SMTP.SendAsApp click the checkbox to select and then Add permissions.

SMTP.SendAsApp should now be listed in your API Permissions, but it may have a status of Admin Consent Required. An administrative user will need to click the Grant admin consent option (next to the Add a permission option) and select Yes.

Your COOLSPOOLS app will now permit an incoming SMTP connection.

Register Service Principal

You now need to update your Exchange environment to recognise the COOLSPOOLS application’s service principal. This step cannot be achieved through the Entra ID or Exchange web interface, and requires execution of PowerShell commands. You are also going to need some of those IDs that you noted down earlier.

You may want to check the latest Microsoft documentation, in case this step has been made any easier. Launch Windows PowerShell ISE as administrator and run the following:

Install-Module -Name ExchangeOnlineManagement
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantid>

At this point you will be prompted to log on to your Microsoft 365 environment. Log on as a user with admin rights, then run the following to set up the service principal.

New-ServicePrincipal -AppId <clientid> -ObjectId <objectid>

Don’t come out of PowerShell yet – you’re going to need it for the next step.

Permission Access to User Mailbox – Two Options

Now we need to give the new Service Principal permission to access one or more user mailboxes. There are two possible approaches to granting user permissions.

Option 1 – SMTP Connection Uses Single Dedicated User Authorised to Send As Others

You can authorise a single user to be used for the SMTP connection, and then authorise that user to "send as" other email
addresses. This requires you to run the PowerShell command below for just one user, which may have been created specifically for this purpose:

Add-MailboxPermission -Identity [email protected] -User <objectid> -AccessRights FullAccess

You can now close PowerShell and use Microsoft 365 Admin to grant [email protected] SendAs permission on any other users to be used as the sender on CoolSpools emails.

As new team members join the organization you will need to grant the SendAs permission for their email address to be used as the sender of a CoolSpools email.

Option 2 – SMTP Connection is Authorised Using Each Individual Sender

Alternatively you can authorise SMTP connectivity separately for each and every user who will be sending CoolSpools emails
from their email address by running the Powershell command below for each user’s email address.

Add-MailboxPermission -Identity [email protected] -User <objectid> -AccessRights FullAccess

There is no need to grant SendAs permissions in this configuration option, but you will need to return to PowerShell and run the Add-MailboxPermission command again as new team members join the organization.

Sending as a Dummy Email Address

You may wish to send emails using a dummy email address such as [email protected]. With most mail servers this is permitted so long as the domain names of the mail server and the sender email address match, but with Microsoft 365 and OAUTH 2.0 this is only possible if there is a user or group in the system named [email protected].

There is a workaround available so long as you have used SMTP connection Option 1 above – you can create a group named noreply and delegate sending of email messages from that group’s email address. Go to Exchange Admin Centre and open Recipients > Groups, selecting the new noreply group, then Settings > Edit manage delegates and click Add a delegate selecting the user that is used in the CoolSpools SMTP connection, then Permission Type Send on behalf.

IBM i and CoolSpools Configuration

Apply Latest CoolSpools Fix Pack

Microsoft OAUTH 2.0 authentication is only available in CoolSpools Version 7 fix pack 078 or above. You can check your CoolSpools version and fix pack by running CoolSpools command DSPPRDINF and pressing F11. See the CoolSpools Maintenance Guide for fix pack instructions.

Note that due to Java and TLS version requirements MS OAUTH 2.0 connectivity requires Operating System IBM i 7.3 or above.

Update CoolSpools SMTP Configuration

Ensure that the CoolSpools library COOLSPV7R1 is in your library list, then run one of the two commands below, stopping and starting your SMTP server with ENDSMTPSVR / STRSMTPSVR after making the configuration change.

Option 1 – Using a Single User to Authenticate All SMTP Connections

CFGSMTPSVR MAILSERVER('smtp-mail.outlook.com' 587) SVRAUTH(*MSOAUTH) SVRLOGIN(*NONE) OAUTH('[email protected]' '<tenantid>' '<clientid>' '<secretvalue>')

Option 2 – Using Each Sender’s Address as Authentication User for SMTP Connections

CFGSMTPSVR MAILSERVER('smtp-mail.outlook.com' 587) SVRAUTH(*MSOAUTH) SVRLOGIN(*NONE) OAUTH(*SENDER '<tenantid>' '<clientid>' '<secretvalue>')

Ensure Certificate Attached in DCM

The SMTP connection uses a TLS certificate to encrypt communications. If you have not already done so, you should ensure that a CA Certificate and Server Certificate exist on your IBM i server and have been associated with CoolSpools SMTP. This can be done in the Digital Certificate Manager (DCM).

We would recommend referring to the latest IBM instructions for working with DCM, but the steps involved are as follows:

Open your IBM i server’s DCM in your browser: //<ibmiserver>:2006/dcm/login

Open the *SYSTEM certificate store, or create it if it does not exist.

Create or import a CA certificate and a server certificate, if they do not already exist.

Open Manage Application Definitions and ensure that the application named ARIADNE_SMTP_SERVER has your server certificate assigned.

What About When Client Secrets or Security Certificates Expire?

When your client secret approaches its expiry date, you should return to the COOLSPOOLS App registration in Entra ID and create a new client secret. Once again you should make a note of the client secret’s value and then apply it to the CoolSpools SMTP configuration using CFGSMTPSVR. This will allocate a new OAUTH 2.0 Token.

When your Server Certificate approaches its expiry date you can create or import a new one in DCM and associate it with the ARIADNE_SMTP_SERVER application.