Dotcom-Monitor can monitor Microsoft 365 (Exchange Online) mailboxes using OAuth-based Modern Authentication. To monitor a mailbox, Dotcom-Monitor needs delegated access to the mailbox on behalf of the user. The GetOAuthToken utility helps you authorize Dotcom-Monitor to access the account and generate the authentication script required by the monitoring target.

For an overview of OAuth 2.0, delegated access, tokens, scopes, and how Modern Authentication works, see OAuth Token Acquisition in Dotcom-Monitor: Microsoft 365, Google and Custom Identity Providers.

Dotcom-Monitor offers a utility app designed to simplify the generation of the required script. You can download the app here: GetOAuthToken.zip.

Once downloaded, start the GetOAuthToken app. If you don’t see “Your browser is up to date” on the right-hand side, download the Microsoft Edge WebView2 component from the official MS website: https://developer.microsoft.com/en-us/microsoft-edge/webview2/.

Click MS OAuth to login into the Office 365 account you want to monitor.

Login into the Office 365 account you want to monitor using modern auth. Note that the username must match the username provided in the Login Information fields of the Basic target settings on the Dotcom-Monitor website.

If you have Administrator access to the target account, the app will automatically populate the Dotcom-Monitor settings field with the data required to access the account, including a refresh token and a list of scopes for the Dotcom-Monitor app in your AD.

If you do not have Administrator access to the account, the corresponding message will appear in the app. Please send a “Grant Permission” request to your mail server administrator.

After the necessary permissions have been granted, restart the GetOAuthToken application and begin the setup process from the very beginning.

To convert the code into prepare script, click To Prepare Script.

Then click To Clipboard and paste the script in to the Prepare Script field of the monitoring target settings in your Dotcom-Monitor account.

Limiting OAuth 2.0 Token Scope to a Specific Protocol

If you want to limit the scope of your token to a specific protocol, you can use the OAuth2Target enum when initializing authorization in your Prepare Script:

public enum OAuth2Target { All, Http, Smtp, Pop3, Imap, ActiveSync, WebSocket, Media };

Example: Restricting OAuth Token to POP3 Only

string TokenUrl = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
string ClientID = "XXXXXXX-XXX-XXX-XXX-XXXXXXXXXX";
string ClientSecret = "";
string scope = "offline_access https://outlook.office.com/POP.AccessAsUser.All";
string RefreshToken = "1.ARcA9xOJL73FLkaXXXXXXXXXXO-M-EMqsz__WrVw";

SandboxOAuth2Token rToken = new SandboxOAuth2Token(TokenUrl, ClientID, ClientSecret, scope, RefreshToken);

// Initialize authorization specifically for POP3
currentTask.InitOAuth2Authorization(rToken, OAuth2Target.Pop3);