Microsoft 365 Modern Authentication For Email (OAuth)

From RangerMSP Wiki - PSA software for MSPs and IT services providers
Jump to: navigation, search
Important: RangerMSP version 30 or above is required for configuring access to Microsoft 365 mail servers using OAuth.



Prerequisites

Open your default browser and go to https://login.microsoftonline.com


If you are logged in with any of your users, click the user avatar and Sign out.


365 log out.png

This step is IMPORTANT and will prevent accidentally granting access to the wrong mailbox, e.g., yours.


Configuring RangerMSP with OAuth

To configure RangerMSP to connect to Microsoft 365 mail servers, follow the steps below:

  1. Run <Installation_DIR>\RangerMSP\Server\ServerConfig.exe.>

  2. Under the ‘Outgoing Mail Server’ tab, select the option ‘Use OAuth 2 to connect to Microsoft 365’.

    Smtp oauth settings.png

  3. You must authorize RangerMSP in Microsoft 365.
    For this to work:
    1. Click the ‘Send Test Email’ button.
    2. Specify the ‘To’ email address that will be used for sending the test email message.
    3. Click the ‘Send Test Email Now’ button:

      Send test email smtp.png

    4. Follow the Microsoft 365 flow in your browser to log into your Microsoft 365 using the SAME 365 user account that owns the mailbox you are trying to use (i.e., defined as the username in ServerConfig utility).
      Note: if you are already logged into 365 using another account, please log out - BEFORE starting the entire test-email process.

      Ms365 signin.png

      Case1 sample.png


    5. The following page is displayed.
      Click the ‘Accept’ button whenever you are ready to authorize RangerMSP.

      365 permissions request.png
      Authorization success.png

    6. The SMTP send-email test should show that it completed successfully:

      Smtp test completed.png

  4. Under the ‘Email Connector’ tab, you configure the same for inbound email under the ‘Incoming Email Settings’ section.

    Select Use OAuth 2 to connect to Microsoft 365.

    Next - click the ‘Test Server Settings’ button.

    Pop test server settings.png

    NOTE: If you have not authorized RangerMSP in Microsoft 365 yet, a browser window will open asking you to approve RangerMSP, as explained above.

    A connection attempt to your mailbox at Microsoft 365 will run, and if everything is configured correctly, you will be prompted about a successful connection to Microsoft 365 POP3 servers.Pop test completed.png

  5. Click OK to save your new settings.

    Serverconfig save settings.png

  6. Finally, you must RESTART the ‘CRM Server’ Windows service on your server for the changes to apply and take effect immediately.

DONE!

Troubleshooting

Case 1

The browser shows “Successfully connected” however:

POP3 connection test fails with error:

500 -ERR Authentication failure: unknown user name or bad password

And/or SMTP test fails with error:

535 5.7.3 Authentication unsuccessful

This error might show when the username set in the ServerConfig utility for sending emails (SMTP) or receiving emails (POP3) does NOT match and is different from the 365 user account, which was for signing into the 365 portal and authenticating RangerMSP access to the mailbox.

Microsoft's website includes detailed information about such errors.



Solution:

  1. Open your default browser and visit https://login.microsoftonline.com.
    If you are logged in with any 365 user account, click the user avatar and select the Sign out option.

  2. Run RangerMSP’s ServerConfig utility -

    If testing an outbound email failed with the above error - Visit the Outgoing Mail Server tab and click the Send Test Email button.

    If testing an inbound email connection failed with the error above - Visit the Email Connector tab and click the Test Server Settings button.

  3. If you completed the 365 authorization process using an incorrect 365 account (e.g., you used the already-logged-in account vs. the one owning the mailbox), you need first to use the ServerConfig utility to Reset the existing authorization. You should now be able to start the authorization process with 365 from scratch.

    365 auth reset.png

  4. Follow the Microsoft 365 flow in your browser to log into your Microsoft 365.
    Important: You MUST sign in with the SAME 365 user account that owns the mailbox you are trying to use, and - it should be the SAME one defined in ServerConfig utility.

    Case1 sample.png

  5. In case you were not prompted to sign in, and the browser used a previously logged-in user, you should sign out and try again. In case this does not help, clearing the browser cache may be required.



Case 2

The browser shows “Successfully connected” however, testing SMTP by sending a test email fails with the following error -

535 5.7.139 Authentication unsuccessful, SmtpClientAuthentication is disabled for the tenant. Visit https://aka.ms/smtp_auth_disabled for more information.


Solution:

The error means that SMTP authentication is disabled for this mailbox.

This article (also here) explains how to enable SMTP authentication for the whole organization or only for some mailboxes.

The article will guide you to the following settings where the ‘Authenticated SMTP’ option should be selected (see below). After enabling it, try again.

Smtp auth.png

Case 3

The error is shown in the application or POP3 connection test fails with error:

POP3 needs OAuth2 authentication token


Solution:

This error means that 365 requires re-authorization.

  1. Open your default browser and visit https://login.microsoftonline.com.
    If you are logged in with any 365 user account, click the user avatar and select the Sign out option.

  2. Run RangerMSP’s ServerConfig utility - visit the Email Connector tab and click the Reset button.

    You should now be able to start the authorization process with 365 from scratch.

    365 auth reset.png

  3. Follow the Microsoft 365 flow in your browser to log into your Microsoft 365.
    Important: You MUST sign in with the SAME 365 user account that owns the mailbox you are trying to use, and - it should be the SAME one defined in ServerConfig utility.
  4. In case you were not prompted to sign in, and the browser used a previously logged-in user, you should sign out and try again. In case this does not help, clearing the browser cache may be required.