Websphere-outlook-store (Kalisto)

Deprecation of BASIC authentication in Exchange Online

In MS Office 365, BASIC authentication is now disabled in all tenants. Before December 31, 2022, you could enable BASIC authentication for IMAP, POP3, and SMTP protocols if users and applications in the tenant could not connect. Now, no one (neither you nor Microsoft Support) can re-enable BASIC authentication. Read the article Deprecation of Basic authentication in Exchange Online to fully understand the changes Microsoft has made and how these changes may affect you.

Websphere-outlook-store (Kalisto) is a response to the need to implement communication mechanisms via IMAP, POP3 and SMTP protocols with MS Office 365 mailboxes using "modern authentication".

Kalisto is a library containing an implementation of the pl.slawas.mail.outlook.store.OutlookStore class, which is extended by the standard implementation of the com.sun.mail.imap.IMAPStore checkout from com.sun.mail » javax.mail » 1.6.2. The functionality included in this implementation allows you to configure the email data source in communication with the Ofiice365 IMAP service using "modern authentication".

Application in any Java project

The name of the product suggests that its only application is the IBM WebSphere Application Server application server environment, BUT THAT IS NOT TRUE.

The library implements the standard API developed by Sun Microsystems and can be used in any Java project.

This document contains steps for installing and configuring the mechanism for using e-mail in the environment of the IBM WebSphere Application Server, 8.5.x.

Installation

The installation package is an archive containing files necessary to run the "Modern authentication" mechanism for email. It contains the "Kalisto" library named 0_outlook-store-<version>.jar (e.g. 0_outlook-store-0.0.3-jdk1.7.jar) and libraries on which the implementation depends.

The libraries should be placed in the $WAS_INSTALL/BPM/Lombardi/lib directory, e.g. /opt/IBM/BAW/20.0.0.1/BPM/Lombardi/lib.

Attention!

If the mail.jar file (standard library with API for communication with email) exists in the target directory, it should be removed.

Cache configuration

Configuration path in WebSphere console: Resources > Cache instances > Object cache instances

You need to configure the object cache, which will store the necessary data to improve the performance of the solution. Example:

Then set the cache parameter values ​​accordingly:

• Name - the name of the cache, e.g. tokenO365
• JNDI Name - the JNDI name of the cache, e.g. services/cache/tokenO365 - this name will be used as the value of the email session configuration parameter.
• Scope - the scope of the cache should be defined as a cluster, e.g. Cluster=SingleCluster

Microsoft O365 Application Configuration

Before configuring email, you need to create an application through which the authentication mechanism will obtain the OAuth2 token.

Tip

Before we move on to the next steps, it is worth supplementing your knowledge of building applications in the Azure Portal. Below are links to pages worth visiting:

• Authenticate an IMAP, POP or SMTP connection using OAuth
• Configuring a Microsoft Azure application for POP and IMAP
• Granting permissions to the application
• Add-MailboxPermission

Application in Azure Portal registry

Go to Azure Portal page at: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade. Add (register) application or select previously created, pre-configured (in the example below the application is called outlook-oauth).

Important data about the application (Overview)

Remember the following data about the application:

• Application (client) ID – clientId, AppId
• Object ID – serviceId, ServiceId
• Directory (tenant) ID – directoryId, tenant, Organization

Authentication parameters

Set the authentication parameters:

• Supported account types - select Accounts in this organizational directory only (<company_name> only - Single tenant)
• Advanced settings - Allow public client flows - set to "Yes"

Client secret

Add the client secret and remember its value.

Note!

The value is available only right after the key is created. The recommended key lifetime is 24 months.

Microsoft Graph application permissions

Add the necessary permissions to the Microsoft Graph application:

• IMAP.AccessAsUser.All – read and write to mailboxes via the IMAP protocol.
• POP.AccessAsUser.All – read and write to mailboxes via the POP protocol.
• SMTP.Send – send mail from mailboxes via SMTP AUTH.

Attention!

Permissions must be added with "Grant admin consent for <company_name>".

Add ServicePrincipal to the application

To add ServicePrincipal to the application we will use the PowerShell console.

Attention!

Before you start you must have the ExchangeOnlineManagement module installed on your computer. Installation commands in the console:

Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement

Command to add ServicePrincipal:

New-ServicePrincipal `
 -AppId <AppId> `
 -ServiceId <ObjectId> `
 -Organization <tenant>

Sample:

New-ServicePrincipal `
 -AppId ddd1f64e-f67a-49ff-9cdc-387d173f3028 `
 -ServiceId c64cea69-2bf4-4570-8b86-2666ce9f9716 `
 -Organization 161ee23e-798c-481d-975a-3a345e760161

Sample email provider configuration

Configuration path in WebSphere console: Resources > Mail

Email provider configuration

Configuration path in WebSphere console: Resources > Mail > Mail Providers

Create a mail provider object with the example name outlook-store:

Attention!

It is important to check the Isolate this mail provider option when configuring the mail provider object, as shown in the illustration below.

We perform the appropriate provider configuration. Depending on which protocols for communication with the e-mail server we want to use, we set the appropriate class name implementing the provider for them.

Configuration path in the WebSphere console: Resources > Mail > Mail Providers > outlook-store > Protocol providers

For example, we configure support for the following protocols: IMAP, IMAPS (IMAP with SSL encryption), SMTP and SMTPS (SMTP with SSL encryption).

Protocol	Class Name	Type
imap	pl.slawas.mail.outlook.store.OutlookStore	STORE
imaps	pl.slawas.mail.outlook.store.OutlookSSLStore	STORE
pop3	com.sun.mail.pop3.POP3Store	STORE
pop3s	com.sun.mail.pop3.POP3SSLStore	STORE
smtp	pl.slawas.mail.outlook.smtp.OutlookTransport	TRANSPORT
smtps	pl.slawas.mail.outlook.smtp.OutlookSSLTransport	TRANSPORT

Configuring an email session

Configuration path in the WebSphere console: Resources > Mail > Mail Sessions

Add a mail session with the example name outlook-store:

Note!

When creating a session object, select the previously created mail provider.

Set the fields:

• Name - the name of the mail session, e.g. outlook-store
• JNDI Name - the JNDI name through which you will establish connections in BPM email integrations. E.g. mail/office365
• Server - outgoing mail, server name: smtp.office365.com
• Protocol - outgoing mail, select value: smtp
• User - outgoing mail, mailbox username e.g. scichy@<domain_name>
• Server - incoming mail, server name: outlook.office365.com
• Protocol - incoming mail, select value: imap
• User - incoming mail, mailbox username e.g. scichy@<domain_name>

Set your own values for the required session parameters (you can learn the meaning of parameters named mail.* by reading the description of Package javax.mail The JavaMail™ API provides classes that model a mail system.):

Required

Parameter	Parameter description	Example value
websphere.cache	Name The JNDI name of the cache. See the section on Configuring caches.	services/cache/tokenO365
security.encoder.class	Default Set the value as in the example.	com.ibm.ws.security.util.WSEncoderDecoder
o365.user	Name The mailbox username.	scichy@<domain_name>
o365.password	Password The password of the mailbox user.	secret
o365.oauth.tenant	Identifier The organization ID, the app tenant in O365.	161ee23e-798c-481d-975a-39345f76032a
o365.oauth.clientId	Identifier The app client ID in O365.	782d2e03-9066-4d59-ab6a-a2cfbc0212a1
o365.oauth.clientSecret	Key O365 application secret key.	secret
mail.smtp.user	Name The mailbox username.	scichy@<domain_name>
mail.store.protocol	Default Set the value as in the example.	imap
mail.imap.class	Default Set the value as in the example.	pl.slawas.mail.outlook.store.OutlookStore
mail.imap.mailbox.timeout	Default Set the value as in the example or something else.	10000
mail.transport.protocol	Default Set the value as in the example.	smtp
mail.smtp.class	Default Set the value as in the example.	pl.slawas.mail.outlook.smtp.OutlookTransport

Optional

Parameter	Parameter description	Example value
o365.oauth.url	Default Set the value as in the example.	https://login.microsoftonline.com/%s/oauth2/v2.0/token
o365.oauth.scope	Default Set the value as in the example.	https://outlook.office.com/.default
mail.imap.ssl.enable	Default Set the value as in the example.	true
mail.imap.ssl.protocols	Default Set the value as in the example.	TLSv1.2
mail.imap.sasl.enable	Default Set the value as in the example.	true
mail.imap.sasl.mechanisms	Default Set the value as in the example.	XOAUTH2
mail.imap.auth.login.disable	Default Set the value as in the example.	true
mail.imap.auth.plain.disable	Default Set the value as in the example.	true
mail.imap.host	Default Set the value as in the example.	outlook.office365.com
mail.imap.port	Default Set the value as in the example.	993
mail.smtp.starttls.enable	Default Set the value as in the example.	true
mail.smtp.socketFactory.fallback	Default Set the value as in the example.	true
mail.smtp.ssl.enable	Default Set the value as in the example.	false
mail.smtp.ssl.protocols	Default Set the value as in the example.	TLSv1.2
mail.smtp.auth	Default Set the value as in the example.	true
mail.smtp.sasl.enable	Default Set the value as in the example.	true
mail.smtp.sasl.mechanisms	Default Set the value as in the example.	XOAUTH2
mail.smtp.auth.login.disable	Default Set the value as in the example.	true
mail.smtp.auth.plain.disable	Default Set the value as in the example.	true
mail.smtp.host	Default Set the value as in the example.	smtp.office365.com
mail.smtp.port	Default Set the value as in the example.	587

Digression

If the parameter is not set in the email session configuration, the library will set the value from the table.

Support

In case of problems, please contact me by e-mail at info@scisoftware.pl. In the subject of the message, please include the prefix: [Websphere-outlook-store].

Companies that have already used the product