KBA-01693: How to Set Up Email using Microsoft Office 365

Procedure:

  1. Decide what email address you want to use for your site and set it up with your email provider.
  2. Go to ICTool and select the SMTP tab to set up outbound email.
  3. In the SMTP Server field, enter smtp.office365.com.
  4. In the Port field, enter 587.
  5. Check the Use SMTP with TLS… checkbox.
  6. Enter the email address in both the SMTP User and Mail From field (Office365 typically uses the email address as the account id)
    1. For classic authentication, specify a long strong password
    2. For oAuth authentication, specify oAUTH (case sensitive)
  7. Go to the sfATC tab to set up inbound email (see also KBA-01263).
  8. In the POP Server field, enter outlook.office365.com.
  9. In the Port field, enter 995.
  10. In the SSL field, select Yes.
  11. In the POP/User and Password fields, specify the same values you provided for SMTP in step 6 above.
  12. Review the email address on the SEND ROUTE tab (not shown) – this email address should either match the Office 365  account name or be listed as an alias for the account.
  13. Go to the Finish tab and click the Publish Configuration button.

Types of Office 365 Accounts

Since Spitfire sfPMS does not use Office applications, you can assign a “Business Essentials” or E1 type license.

We recommend that you use a mailbox-only account rather than an AD Integrated account – that way if the account were to be compromised it would not allow access to your network, just the single mailbox.    This means that you may have an AD account without a mailbox for use by IT and Spitfire Support to connect to the IIS server, and a separate email only account.

Do not enable multi-factor authentication (MFA) for this account, or setup an “app password” and provide this to ICTool.

Enable SMTP and POP “apps” for this mailbox

In https://admin.microsoft.com, access the user mailbox

  1. Change to the Mail “tab”
  2. Click Manage email apps
  3. Be sure that POP and Authenticated SMTP are checked

 

Enable SMTP AUTH for specific mailboxes

Some Office 365 accounts may see the following failure when trying to send email:

Error: 535 5.7.139 Authentication unsuccessful, SmtpClientAuthentication is disabled for the Tenant.

The per-mailbox setting to enable (or disable) SMTP AUTH is available in the Microsoft 365 admin center or Exchange Online PowerShell.

Please see the “Enable SMTP AUTH” section of
https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission

Using oAuth for Authentication

Since June 2022, Microsoft has said they would be phasing out “legacy authentication” for POP and SMTP beginning in October 2022, but we have reports from sites using APP passwords that APP passwords are already being removed and once removed it becomes impossible to use legacy authentication for POPS (meanwhile SMTPS will work with the actual account password…probably until October).  

Beginning in build 8222, Version 2021 supports oAuth for authentication for POPS and SMTPS   

On an Azure Admin Workstation 

Perform these steps from a workstation with a browser authenticated to Azure as a tenant administrator

  1. If you do not know your Azure tenant id (which is a GUID), see https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant
  2. Copy the URL below and replace {tenant-id} (including the { and }) with your Azure tenant-id
    https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=04ff9146-3c10-4f62-b098-1f9ca5d97ff9
  3. Visit the completed URL in a browser that is authenticated to Azure as a tenant administrator
  4. Complete oAUTH authorization.
  5. You will end at a  “site can’t be reached” page (because your admin workstation is not running the service — this is OKAY)

Manual steps are discussed in https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent

On the IIS or ATC Server 

Perform these steps on the Windows Server that has sfATC and ICTool

  1. Set the password on the “ATC | Read Mail” and SMTP tabs in ICTool to oAUTH (in exactly the indicated mixed-case).
  2. Verify that XTS is enabled.  XTS is required in order to manage oAuth connection tokens.
    1. on the XTS tab, Intro sub tab, be sure Enabled is checked
      1. if you have just enabled: Publish the site to add in the XTS engine.
    2. On the XTS Setup sub tab, 
      1. Do NOT check Enable ERP (unless you have the appropriate license
      2. Scroll down, click Edit XTS Config.  Three rows should appear.  Click save.  Close
  3. Republish the site from ICTool
  4. STOP the sfATC Service
  5. Get the POP Tool (See KBA-01478)
  6. Run the tool and use the first toolbar button to find and open your ATC configuration for your site… an authentication page should open in your browser.  
    1. Critically Important: be certain that this browser is authenticated to https://www.office.com/ using the exact same identity as specified as the SMTP sender.  if you are not certain, visit Office.com and LOGOUT.  Then authenticate again with the intended identity.  
  7. Complete oAuth authentication.  If you get a message that administrator review is required, see the “Azure Admin” steps above.
  8. Back in the POP Tool, the status should say “connected”
  9. On the Client Tools menu, export the refresh token
  10. Open C:\Spitfire\RefreshTokenExport.txt and copy the entire content to your clipboard
  11. Log into your site in Chrome
  12. Open the Chrome Inspector and change to the CONSOLE tab (clear if necessary)
  13. Paste the clipboard and hit enter to run
  14. You should get a 204 result.   This has saved the an encrypted refresh token to your database (dbo.xtsConfig)
  15. START the sfATC service

 


KBA-01693; Last updated: July 12, 2022 at 11:42 am