Identity Providers

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

  1. Navigate to Ploy's integration page in your Ploy account: https://app.joinploy.com/integrations

  2. Click "Add" on the Microsoft integration widget

  3. On How should Ploy connect to Microsoft?, select Ploy managed app and continue

  4. Enter your Tenant domain, for example acme.com

  5. Set 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

  6. Continue to the next page

  7. 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

  8. 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

  9. 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

  10. Name the connection something useful e.g. Ploy Microsoft Integration

  11. Click Test

  12. 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.

Was this helpful?
Was this helpful?