Workspace & Identity

Connect Microsoft with your own app registration

Connect Ploy to Microsoft by creating your own app registration in Microsoft Entra. This gives you full control over exactly which permissions Ploy receives, and Ploy authenticates using short-lived, cryptographically signed tokens via workload identity federation — no client secret is ever shared.

Which mode should you choose?

Ploy supports two ways to connect to Microsoft:

  • Ploy managed app — quick setup with a single admin consent. See the Ploy managed app setup guide.

  • Your own app registration (this guide) — full control over the access you grant Ploy. You create the app, pick the capabilities, and manage the federation yourself.

Before you start

  • An Entra admin who can create app registrations, grant admin consent, and assign directory roles.

Step 1: Choose your connection mode

In Ploy, go to the Microsoft integration setup and choose Your own app registration on the How should Ploy connect to Microsoft? screen, then continue.

If Microsoft is already connected through the Ploy managed app, your existing connection keeps working while you set this up — nothing switches over until the final step.

Step 2: Select capabilities

On the Select the capabilities to grant Ploy screen, choose which capabilities Ploy should have. Core identity read access is always required. Every other capability is optional — choosing fewer capabilities means fewer permissions granted to your app.

The available capabilities are:

  • Core identities (always required): Directory (Read), Domains (Read), Users (Read), Organization (Read)

  • Account lifecycle: Manage user accounts (Read/Write)

  • Groups & membership: Groups (Read), Manage group membership (Read/Write), Create groups (Read/Write)

  • MFA & auth methods: Auth methods (Read), Manage auth methods (Read/Write)

  • Access packages: Access packages (Read), Manage access packages (Read/Write)

  • Apps & OAuth consent: Apps & grants (Read), Manage OAuth grants (Read/Write)

  • Devices: Devices (Read), Manage devices (Read/Write)

  • Mail & calendar: Mail & calendar (Read), Manage calendars (Read/Write)

  • Sign-in activity & usage: Sign-in & usage reports (Read)

  • AI agent usage: Copilot interaction usage (Read)

  • Directory roles: Directory role assignments (Read)

  • Conditional access: Conditional access policies (Read)

  • SharePoint: SharePoint sites (Read)

  • Custom security attributes: Custom security attributes (Read)

Use Enable all if you want to select every optional capability at once. When you are finished, continue to the next step.

Step 3: Create the app registration and paste the permissions manifest

  1. In the Microsoft Entra admin center, go to App registrations and click New registration.

  2. Keep Supported account types set to Accounts in this organizational directory only (single tenant).

  3. Register the app, then open its Manifest.

  4. Find the requiredResourceAccess property. A new app has a default User.Read entry there — replace the entire value with the JSON array that Ploy provides on this step, then click Save.

Each id in that JSON is a Microsoft Graph application permission. You'll be able to review the permissions in the next step before granting admin consent.

The manifest requests permissions but does not grant them. In your app registration:

  1. Go to API permissions.

  2. Click Grant admin consent for your tenant.

  3. Wait for the permissions to show a green Granted status.

Admin consent can take a few minutes to propagate through Microsoft. If a later step fails, wait a couple of minutes and retry.

Step 5: Assign a directory role for reset actions (conditional)

If you selected Manage user accounts or Manage auth methods, the app needs a Microsoft Entra directory role in addition to its API permissions. App permissions alone cannot reset passwords or authentication methods.

  1. In the Entra admin center, go to Roles and administrators.

  2. Search for Authentication Administrator and open it.

  3. Click Add assignments, search for your app registration by name, and assign the role to its service principal.

To reset admin accounts too, use Privileged Authentication Administrator instead.

Step 6: Add a federated credential

Still in your app registration:

  1. Go to Certificates & secrets, then Federated credentials.

  2. Click Add credential and choose Other issuer as the scenario.

  3. Paste the Issuer and the Subject identifier that Ploy displays on this step.

  4. Leave the Audience as its pre-filled default.

  5. Save the credential.

This lets Ploy authenticate with a signed token instead of a shared secret.

Step 7: Enter the client ID, confirm your scan settings, and switch

  1. From your app registration's Overview page, copy the Application (client) ID and paste it into Ploy.

  2. Under Confirm your tenant domain, enter the domain of the Microsoft tenant your app registration lives in, for example acme.com. It must be a verified domain (or the root domain) of the tenant.

  3. Answer the three scan settings (all required). Include users without mailboxes? — choose Yes to include ALL users, including service accounts, shared accounts, and users without Exchange licenses. Include guest accounts as unmanaged users? — choose Yes to include ALL external users as unmanaged users. Include apps without a website as resources? — choose Yes to include ALL enterprise applications as resources, even internal machine-to-machine apps with no website.

  4. Click Verify & switch. Ploy verifies the connection against your tenant and, on success, the integration is connected.

If you were previously connected with the Ploy managed app, this final step is the moment your connection switches over to your own app registration — the wizard shows a note saying so, and your existing connection keeps working until then.

Troubleshooting

The message reads: "Ploy authenticated, but Microsoft hasn't granted access to your tenant's domains yet." You have not consented the permissions yet, or consent is still propagating. Go to API permissions in your app registration, click Grant admin consent for your tenant, wait a few minutes, and retry.

Your federated credential is still propagating

Microsoft Entra can take a minute or two to register a new federated credential. Wait briefly and retry.

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.

What's next

After connecting, you can configure additional Microsoft features like Microsoft Exchange or Teams notifications.

Was this helpful?
Was this helpful?