Graph connection setup (Entra app registration)

This guide walks through connecting a customer Microsoft Entra tenant to Policytab. You work in the customer's Entra directory (where their users and Conditional Access policies live), not in Policytab's own login.

Policytab does not use a shared multitenant "Connect with Microsoft" app today. Each customer gets a dedicated single-tenant app registration in their directory. You create that app once, then paste three values into Policytab: Directory (tenant) ID, Application (client) ID, and client secret.

Who can do this

• Policytab role: admin or owner in your MSP workspace
• Microsoft role in the customer tenant: Global Administrator or Application Administrator

You need both. Policytab login is email/password; Entra work uses the customer's Microsoft admin account.

Before you start

1. In Policytab: Customers → Add customer → enter a display name → you land on Connect.
2. Confirm you are signed into the customer Entra admin center (check the directory name in the top-right corner).
3. Set aside ~15 minutes. You will create an app, add permissions, grant consent, and copy a secret.

Step 1 - Open App registrations

1. Go to Microsoft Entra admin center.
2. Switch to the customer directory if needed.
3. Navigate to Identity → Applications → App registrations.
4. Click New registration.

Step 2 - Register the app

Click Register.

Step 3 - Copy Directory (tenant) ID and Application (client) ID

On the app Overview page (right after Register), copy both GUIDs:

Keep this tab open - you still need a secret and API permissions.

Step 4 - Create a client secret

1. Open Certificates & secrets.
2. Client secrets → New client secret.
3. Description: e.g. Policytab; choose an expiry per your security policy.
4. Click Add.
5. Immediately copy the secret Value (not the Secret ID). Microsoft never shows it again.

If you lose the secret, create a new one and paste the new value on Connect.

Step 5 - Add Microsoft Graph application permissions

1. Open API permissions → Add a permission.
2. Choose Microsoft Graph → Application permissions (not Delegated).
3. Search for and add every permission listed on the Policytab Connect page (also in lib/tenants/graph-app-permissions.ts). Common ones include:
   • Policy.Read.All
   • Policy.ReadWrite.ConditionalAccess
   • Group.ReadWrite.All
   • Directory.Read.All
   • AuditLog.Read.All
   • (and the rest of the Connect checklist)
4. Click Grant admin consent for [Customer Name] and confirm Yes.
5. Verify each permission row shows Granted for [Customer Name] with a green status.

Missing admin consent is the most common cause of Graph token failed on Connect.

Step 6 - Save credentials in Policytab

1. Return to Connect for this customer in Policytab.
2. Paste Directory (tenant) ID, Application (client) ID, and Client secret Value.
3. Click Save & continue onboarding.

Policytab verifies credentials against Graph, stores the secret encrypted in Vault, and moves you to import/baseline setup.

The tenant ID is required. Policytab cannot discover it from the client ID and secret alone. Use the Directory (tenant) ID GUID from Entra - not the Policytab customer ID in your browser URL.

Troubleshooting

Removing a customer during setup

If you added the wrong customer or want to start over before Graph is connected:

1. Open Customer settings in the tenant nav (available before Summary appears).
2. Owner role: type the customer display name and Delete customer permanently.

Related

• Onboarding a customer
• Entra app registration (operator)
• Credential rotation