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:

Mode

Best for

Ploy managed app

Quick setup with a single admin consent. See the Ploy managed app setup guide.

Your own app registration

Full control over the access you grant Ploy. You create the app, pick the capabilities, and manage the federation yourself.

This guide covers the Your own app registration flow.

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.

Ploy Microsoft connection mode selection showing Ploy managed app and Your own app registration options

Connection mode selection in Ploy

Step 2: Select capabilities

Ploy shows a list of capability groups. Core identity read access is always required and selected automatically. Every other capability is optional—choosing fewer capabilities means fewer permissions granted to your app.

The capability groups are:

  • Core identities

  • Account lifecycle

  • Groups & membership

  • MFA & auth methods

  • Access packages

  • Apps & OAuth consent

  • Devices

  • Mail & calendar

  • Sign-in activity & usage

  • Directory roles

  • Conditional access

  • SharePoint

  • Custom security attributes

Several groups include a separate manage/actions toggle for write access in addition to read. Use the Enable all or Disable all controls if you want to select or clear everything 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.

Ploy wizard showing the generated JSON permissions manifest to paste into the Entra app registration manifest

Ploy provides the exact JSON array to paste into your app registration manifest

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

  1. Go to API permissions.

  2. Click Grant admin consent for <tenant>.

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

Entra app registration API permissions page showing where to click to grant Admin consent

API permissions page where admin consent is granted

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 Account lifecycle (create, update, disable users) or MFA & auth methods manage actions, 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 → 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.

Entra federated credential form with Other issuer selected, showing Issuer and Subject identifier fields

Federated credential form in Entra with the issuer and subject identifier pasted in

Step 7: Enter the client ID and tenant domain, then test

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

  2. Enter your tenant domain, for example yourcompany.onmicrosoft.com or a custom domain.

  3. Click Test connection. On success, the integration is connected.

Troubleshooting

Your federated credential is still propagating

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

What’s next

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

Was this helpful?