Overview:
Connecting Microsoft 365 to Thoropass enables automated compliance data collection including user and group directory sync, audit logs, vendor discovery, and optional SharePoint document sync. This guide outlines the full initial setup.
Prerequisites:
Global Admin account in MSFT 365 / MSFT Entra ID (formerly Azure AD).
A Global Admin is required to complete the OAuth flow because Thoropass needs to grant admin consent for organization-wide API permissions.A non-admin account cannot complete this setup.
Dedicated service account recommended. Thoropass stores a refresh token issued by Microsoft — not your password. If the service account's password is changed or reset, Microsoft automatically revokes all active refresh tokens, which will break the integration and require reconnection.
For this reason, we strongly recommend using a dedicated service account with a static password and no interactive login requirements to keep the connection stable long-term.
Permissions Granted During Setup:
During the OAuth flow, you will need to grant the following Microsoft Graph API permissions to Thoropass.
All permissions are read-only — Thoropass does not write to, modify, or delete anything in your Microsoft environment.
openid, profile, User.Read — Authenticate the user and read basic profile information.
offline_access — Maintain access using refresh tokens without requiring repeated re-authentication.
User.Read.All — Read full profile details for all users in the directory. Required for Access Reviews and User Monitors.
Directory.Read.All — Read directory objects including users, groups, devices, and apps across your organization.
GroupMember.Read.All — Read group membership information across the organization.
Files.Read.All — Read all files the signed-in user has access to. Required for Audit-Connected Documents.
Sites.Read.All — Read content across SharePoint sites. A specific site is selected during the wizard for document sync.
Mail.Read — Read email data. Required for Vendor Discovery.
AuditLog.Read.All — Read directory and security audit logs for compliance monitoring.
Note: Each permission is displayed individually during the OAuth flow. If your organization is not comfortable granting specific permissions, you may proceed without them — however, the Thoropass features tied to those permissions will produce errors.
You can disable the affected monitors and document the intentional restriction as a justification at audit, which is a supported approach.
Note: Only one Microsoft 365 connection is supported per workspace. If there are multiple Microsoft 365 accounts to be connected, please consult with your CSM for further guidance.
Steps to connect:
Log in to Thoropass with an account that has admin access.
In the left navigation bar, click Integrations.
On the My Integrations page, click +Browse Integrations (top-right corner).
Locate +add and select Microsoft 365 in the integration catalog.
You can use the search bar to find it quickly.
Click Connect to begin the setup wizard.
The wizard will redirect you to Microsoft's OAuth consent screen.
Sign in with your Global Administrator Microsoft 365 account if prompted.
If you are already signed in with a non-admin account, click Use a different account and sign in as a Global Admin.
Review the list of requested permissions on the Microsoft consent screen.
Check the box labeled Consent on behalf of your organization.
This is required for full compliance data collection.
Click Accept to authorize the connection.
You will be redirected back to the Thoropass wizard. Follow any remaining configuration steps, which may include:
SharePoint site selection — If you want to sync documents from SharePoint, select the specific SharePoint site to connect. Only one site can be selected.
Naming the connection — Give the integration a recognizable name.
(e.g., "Contoso M365")
Click Finish or Save to complete the connection.
The integration will appear in your My Integrations list.
Initial data sync may take a few minutes.
What Happens After Connecting?
Once connected, Thoropass will begin syncing data from your Microsoft 365 environment to power the following features:
Access Reviews — User and group data from your directory is used to populate and automate access review campaigns.
Automated Monitors — Compliance monitors populate with data from your user directory, group memberships, and audit logs to support continuous compliance evidence collection.
Vendor Discovery — Mail data is scanned to identify SaaS vendors in use across your organization.
Audit-Connected Documents (SharePoint only) — If a SharePoint site was connected during setup, files tagged for sync will be automatically attached to evidence requests in Thoropass.
Note: Microsoft 365 does not populate the Thoropass People Management table. Employee records are sourced from HR/payroll integrations (e.g., Rippling, BambooHR, Workday) for accurate headcount data.
Troubleshooting:
Integration disconnects after a password change: Thoropass authenticates using a refresh token issued by Microsoft, not your password. When a service account password is changed or reset, Microsoft automatically revokes all active refresh tokens as a security measure, which breaks the integration.
To resolve, reconnect the integration using a Global Admin account.
To prevent recurrence, use a dedicated service account with a static password.
Admin consent was not granted: If you did not check "Consent on behalf of your organization" during the OAuth flow, the integration may only sync data for your individual account.
Disconnect and reconnect, ensuring a Global Admin completes the flow and checks the consent checkbox.
Monitors showing errors after successful connection: This typically means one or more permissions were not granted during setup. Each monitor is tied to a specific permission scope.
Either reconnect with full permissions, or disable the affected monitors and document the intentional restriction as a justification for audit.
Connection shows as Unhealthy: This can occur if the service account used during setup has been removed, disabled, or had its permissions changed.
Reconnect using an active Global Admin account.
Data not appearing after connecting: Allow up to 24 hours for the initial sync to complete. If data is still missing, check the integration health status on the My Integrations page and contact Thoropass support if needed.