Microsoft 365 OAuth setup#

To let Reportworq talk to Microsoft 365, you register one application in your tenant's Microsoft Entra ID (Azure AD) portal, then authenticate the running Reportworq instance to it. That single registration is the trust anchor for every Microsoft 365 capability, it is not per-feature.

When to use it. Any deployment that uses Entra sign-in, Microsoft-native distribution (email, SharePoint, or Teams), or email-based data collection.

One registration lights up everything, and breaks everything. A single successful setup enables the Microsoft Entra authentication provider, the SharePoint report provider, the Email, SharePoint, and Teams distributors, and email data collection all at once. There is no per-feature registration. If you break the one registration (an expired secret, a wrong redirect URI), all of these fail together.

Before you start#

• You need app-registration rights in your Azure / Entra tenant, and Administrator rights in Reportworq.
• Know the instance's advertised address (scheme, host, and port). The redirect URIs must match it exactly, including the https scheme, which Microsoft 365 requires. On a single-box install the advertised address is https://localhost:8600: 8600 is the default listen port, and a fresh Windows install serves HTTPS. If the instance runs behind a reverse proxy, see the note after the redirect-URI table.
• Decide the Microsoft account to authenticate with. Use a dedicated service account (see the warning at the end), not a person's mailbox.

Register the Azure application#

1. In the Entra ID portal, create a new app registration. For directory type, choose Accounts in this organizational directory only (single tenant).
2. Do not set a redirect URI on the creation screen. Redirect URIs are added later on the platform step.
3. From the registration Overview, record the Application (client) ID and the Directory (tenant) ID.

Create a client secret#

1. Go to Certificates & secrets ▸ New client secret, give it a description and an expiry, and create it.
2. Record the Secret value shown immediately, not the Secret ID. The Secret ID cannot authenticate, and the value is unrecoverable once you leave the screen.
3. Note the expiry date. When the secret lapses, the whole Microsoft 365 integration stops working, so rotate it in Reportworq's Microsoft 365 settings before expiry. Set a calendar reminder.

Add the Web platform and redirect URIs#

1. Go to Authentication ▸ Add a platform and choose Web. Any other platform type (SPA, mobile, desktop) silently fails the callback.

2. Enable Access tokens.

3. Add these three redirect URIs, all pointing back at your Reportworq server. Replace the default host below with your instance's actual advertised address if it is not a single-box localhost:8600 install:

   Redirect URI (default host)	Purpose
   https://localhost:8600/signin-oidc	Entra sign-in callback
   https://localhost:8600/server/v0/get-office365-smtp-token	Outlook / SMTP token callback
   https://localhost:8600/server/v0/get-office365-sharepoint-token	Graph / SharePoint token callback

Behind a reverse proxy. If Reportworq runs behind a TLS-terminating reverse proxy and its callback URLs come back as http instead of https, set BehindReverseProxy in settings.json so it honors the X-Forwarded-Proto header. See Deployment topology.

Authenticate Reportworq (two flows)#

1. In Reportworq, go to Administration ▸ Microsoft 365. Enter the Tenant ID, Client ID, and the Secret value, then save.
2. In the Graph API area, select Authenticate, sign in as the Microsoft 365 account, tick Consent on behalf of your organization if prompted, and Accept. This grants the Graph-family scopes (Teams, SharePoint, Graph email, and the user directory).
3. In the Outlook API area, select Authenticate again. This is a separate flow granting the legacy Outlook POP, IMAP, and SMTP scopes.

The two flows are distinct token grants: authenticating one does not authenticate the other, so complete both.

Scopes each flow requests#

Reportworq requests a fixed set of scopes per flow. The Graph API flow requests the Microsoft Graph scopes below; the Outlook API flow requests the legacy Outlook scopes. Both flows also request openid and offline_access, which cover sign-in and silent token refresh. If your tenant requires admin consent, an administrator consents to these on the first Authenticate.

The Graph API flow requests these scopes:

The Outlook API flow requests these scopes:

Only the features you use need their scopes. If the deployment uses Entra sign-in and email only, you can remove the Teams and SharePoint scopes, as described next.

Tighten the scopes (optional)#

• In Administration ▸ Microsoft 365 ▸ Advanced Options, delete unwanted scopes from the Graph API and Microsoft 365 groups scope lists. Reset restores the defaults. After editing a group's scopes, Sign out and Authenticate that group again so the new consent takes effect.
• To tighten the Azure side as well, in the registration under API permissions choose per scope Remove permission (the scope can be re-added later) or Revoke admin consent (blocks re-adding until an administrator re-consents).

Notes and limits#

• The redirect URIs are host-specific. A server move or port change requires re-registering the URIs to the new advertised address.
• The client secret is time-bombed. Unmonitored expiry silently breaks every Microsoft 365 feature.
• The platform must be Web.

Use a dedicated service account. The Microsoft account you authenticate with is, by default, also the Email distributor's sending account. Every burst email goes out as that identity. If you use a person's mailbox, all outbound mail appears to come from that person and breaks when they leave. Register with a dedicated Microsoft 365 service account instead.

Going deeper. This registration is what enables the Microsoft Entra authentication provider (Sign-in and SSO) and the Microsoft email, SharePoint, and Teams destinations (Destinations).