Microsoft
There are two ways to connect Ploy to Microsoft. This guide covers the quick default: the Ploy managed app, where Ploy's own Microsoft app handles authentication and you grant access with a single admin consent. If you prefer to create your own app registration and control its permissions directly, see Connect Microsoft with your own app registration.
Ploy managed app (this guide) — the quickest setup. Ploy's Microsoft app handles authentication; you grant access with a single admin consent.
Your own app registration — full control over the access you grant Ploy. You create the Entra app registration and manage its permissions yourself, and Ploy authenticates via workload identity federation with no shared secret.
The first page of the setup wizard asks How should Ploy connect to Microsoft? — you must pick a connection mode before you can continue. You can change it later via Change connection method.
What Ploy syncs
Once connected, Ploy scans your Microsoft tenant on a rolling schedule and keeps the following in sync:
Users, their profile details, photos, and account status
Guest accounts and guest invitations
Enterprise applications and app registrations, including recently deleted ones
Which users are assigned to which apps, and the OAuth permissions users have granted to apps
Groups and group memberships
Directory roles and role assignments
Sign-in activity for users and service principals, plus Microsoft 365 usage reports
Users' authentication (MFA) methods
Licenses and which users hold them
Entitlement management access packages and their assignments
Devices registered in Entra (not available in read-only mode)
Managed identities and other non-human identities
Conditional access policies
Copilot agents and how employees use them
Mailbox metadata (message subjects and senders), which Ploy's detection engine uses to spot sign-ups to other SaaS apps
Prerequisites
A Microsoft admin account that can grant tenant-wide admin consent. This does not have to be the account you signed up to or log in to Ploy with.
Your Microsoft tenant domain. This must be a verified domain (or the root domain) of your tenant — you can check your domains here.
Connect Microsoft to Ploy
Navigate to Ploy's integration page in your Ploy account: https://app.joinploy.com/integrations
Click "Add" on the Microsoft integration widget
On How should Ploy connect to Microsoft?, select Ploy managed app and continue
Enter your Tenant domain, for example
acme.comSet Read-only mode (Yes/No, required). Choose Yes to connect with reduced permissions — Ploy will not be able to perform actions like disabling accounts or resetting passwords. Choose No to grant the full permission set, including actions
Continue to the next page
Under Give Ploy access to your Microsoft account, click the Microsoft admin console button and complete the Microsoft authentication. Be sure to authenticate with your admin account — it doesn't have to be the account you signed up or logged in to Ploy with
Answer the three scan settings (all required): Include users without mailboxes?, Include guest accounts as unmanaged users?, and Include apps without a website as resources? — each is explained below
Optionally, under Do you want Ploy to have access to reset users' passwords?, click Grant access and grant Ploy the Authentication Administrator role in the Microsoft portal. Otherwise, skip this step
Name the connection something useful e.g. Ploy Microsoft Integration
Click Test
Click Save
Include users without mailboxes?
Choose Yes to include ALL users — including service accounts, shared accounts, and users without Exchange licenses. This may increase noise but ensures complete visibility. Choose No to limit scanning to users with mailboxes.
Include guest accounts as unmanaged users?
Choose Yes to include ALL external (guest) users in your tenant as unmanaged users in Ploy. Choose No to leave guest accounts out.
Include apps without a website as resources?
Your Microsoft tenant may contain many apps without a website — internal machine-to-machine apps such as Power Platform connectors, Dataverse plugins, and automation service principals.
No (default): Only apps with a website (a homepage, sign-in or reply URL) become resources in Ploy. Apps without one are still scanned and tracked as non-human identities — they just don't appear in your resource inventory.
Yes: Every enterprise application becomes a resource, including internal machine-to-machine apps, so your resource inventory and access reviews cover all app access. In tenants with many internally-registered apps this can add thousands of resources.
You can change any of these scan settings at any time by editing the integration. After enabling Include apps without a website as resources?, the newly included apps appear as resources on the next full scan, within 24 hours. If an app is later deleted from your tenant, its resource is archived like any other.
What Ploy can change
When connected without read-only mode, Ploy can also take actions in Microsoft on your behalf — for example as part of onboarding, offboarding, and access request flows:
Enable and disable user accounts
Create, update, and remove users
Reset user passwords and create temporary access passes (requires the Authentication Administrator role step above)
Remove MFA/authentication methods
Revoke sign-in sessions and refresh tokens
Add and remove group members, and create new groups
Assign licenses
Manage access package assignments
Invite external (guest) users
Remove app assignments
Modify directory role assignments
Delete devices
Update calendar permissions
If you enabled Read-only mode, none of these actions are available — Ploy only reads data.
Troubleshooting
"Invalid domain supplied"
The full message is: "Invalid domain supplied. Please ensure the domain provided is verified and either a root domain or verified domain." Enter a domain that is verified in your Microsoft tenant, or the tenant's root domain.
"That domain isn't a verified domain on this tenant"
Ploy could see your tenant's domains, but the one you entered isn't verified there. The message lists the verified domains it found — use one of those.
"Enter your tenant domain before testing"
The Test button needs the tenant domain from the setup wizard. Go back through the wizard, enter your tenant domain, and try again.
"MS authentication failed"
Consent may still be propagating on Microsoft's side. Wait a minute or two and retry the authentication step. If it persists, re-run the Microsoft admin console consent step with an admin account.