Office 365 mailboxes

Solution:

When setting up mailboxes to use OAuth to connect to Office365 mailboxes you must first create an App Registration on Microsoft's Azure Active Directory.  

Follow the steps below before you proceed with the steps in our documentation, Configure OAuth Authentication Settings. afterward follow the steps to Configure a mailbox to use OAuth.

There are several settings particular to our mailboxes outlined below.  For assistance outside of what is listed below please work with your IT department or support from your Office365 vendor.

Registration name
The registration name is simply a descriptive name for the app. Users may have multiple apps granting permissions for various Microsoft products to any number of third party entities therefore we suggest something like "Oracle B2C Service Email".

Account types (single or multitenant)
This setting determines what type of mailboxes can use OAuth for authentication. 

Single tenant supports only mailboxes for the Azure domain in which the app registration is created. For example, if the Azure account is example.onmicrosoft.com, then only mailboxes in the form of user@example.onmicrosoft.com can use OAuth for authentication. Single tenant is the most straightforward option for most users. 

As the name implies, multitenant allows any Azure AD account to use OAuth for authenticating. Select multitenant if you have mailboxes from multiple Azure domains that you want to allow Oracle B2C Service to authenticate. Multitenant account type requires registration with the Microsoft Partner Network, please consult the Microsoft documentation for full details.

Redirect URI
The redirect url is based on the interface accessed by the Oracle B2C Service administrator when authenticating the mailbox in step 8 below (this may not necessarily be the interface associated with the mailbox). It should be of the form <interface>/AgentWeb/Bookmark/Mailboxes/Auth
(e.g. https://phone-support.custhelp.com/AgentWeb/Bookmark/Mailboxes/Auth). 
This can be found within the Authentication area by adding a Web platform configuration:  App Registrations > "Registration name from above, such as Oracle B2C Service Email" > Authentication > Platform Configuration > Add a platform > Web > Redirect URIs

Delegated API permissions
This setting determines the permissions granted to the App. For Oracle B2C Service mailbox authentication, users must add "Microsoft Graph - POP.AccessAsUser.All" as a delegated permission. "User.Read" should also be included by default.

Client secret
Users must create a client secret under "Certificates & secrets". Make sure to use the Client Secret value, not the Secret ID. Oracle B2C Service will use this to prove its identity during the OAuth process. This value is entered in the CUSTOM_CFG_MAILBOX_OA_CLIENT_SECRET configuration.  Client secrets have an expiration and will need to be updated periodically both in Azure and CUSTOM_CFG_MAILBOX_OA_CLIENT_SECRET.  When adding a new client secret, the mailbox needs to be authenticated again (Step 8 below) to ensure it is using the new client secret.

Client ID 
The client ID is the unique identifier assigned to this app registration. The client ID is automatically generated and can be found in the "Overview" section of the app registration as "Application (client) ID".  This value is entered in the CUSTOM_CFG_MAILBOX_OA_CLIENT_ID configuration.

Tenant ID
The tenant ID is the unique identifier assigned to the Azure AD account. The tenant ID is also automatically generated and can be found in the "Overview" section of the app registration as "Directory (tenant) ID".  This value is entered in the CUSTOM_CFG_MAILBOX_OA_TENANT configuration.

Configure a mailbox to use OAuth
After setting up App Registration and setting the configurations in the product you must enable your mailboxes to use OAuth.

1. Verify that the custom configurations are set appropriately.
2. Open the mailbox editor in the Browser UI client or in .NET after enabling it as in Enabling the mailboxes editor for OAuth in .NET.
3. Open the Office365 mailbox. 
4. Set SSL Method to "pop3 ssl port" on the security tab.
5. Set Pop Server to "outlook.office365.com" on the incoming tab.
6. Set Pop Account to the relevant microsoft account (e.g. somebody@somecompany.onmicrosoft.com). Note that if you use multiple domains you must have set account type to multitenant.
7. Set Authentication Type to "OAuth".
8. Click the Authenticate button.
   • This will open a new tab where the user can enter the credentials for the mailbox and grant Oracle B2C Service access.   Ensure the login you use has the correct permissions. 
   • In most implementations entering the mailbox credentials will be needed, however, you may need to click Authenticate twice - once with an Office365 Admin account and then again with the mailbox account.  If you are authenticating multiple mailboxes on your site you should only need to enter the Office365 Admin credentials once, but the second Authenticate with mailbox credentials is needed for each mailbox individually (there is no bulk authenticate option).  
   • Please note that for aliased mailboxes the alias login should be used.
   • Refer to https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#application-permissions for more information. For further assistance on Azure account permissions please work with your IT team or Microsoft support. 
9. If successful, you will see Mailbox Authenticated and then need to scroll down to click the button for 'OK' which will close this tab.  Clicking OK is required for the completion of this Authentication process.
10. You should now see a green box for 'Authenticated' next to the gray 'Authenticate' button.
    • Warning: If you enter valid credentials without the correct permissions you can authenticate the mailbox successfully, but techmail not be able to access the mailbox and will report a password error.  A green 'Authenticated' flag does not necessarily mean the authentication step has appropriate access tokens for the mailbox.