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
- In Policytab: Customers → Add customer → enter a display name → you land on Connect.
- Confirm you are signed into the customer Entra admin center (check the directory name in the top-right corner).
- Set aside ~15 minutes. You will create an app, add permissions, grant consent, and copy a secret.
Step 1 - Open App registrations
- Go to Microsoft Entra admin center.
- Switch to the customer directory if needed.
- Navigate to Identity → Applications → App registrations.
- Click New registration.
Step 2 - Register the app
| Field | Value |
|---|---|
| Name | e.g. Policytab Graph Access |
| Supported account types | Accounts in this organizational directory only (Single tenant) |
| Redirect URI | Leave blank |
Click Register.
Step 3 - Copy Directory (tenant) ID and Application (client) ID
On the app Overview page (right after Register), copy both GUIDs:
| Entra label | Paste into Policytab |
|---|---|
| Directory (tenant) ID | Directory (tenant) ID |
| Application (client) ID | Application (client) ID |
Keep this tab open - you still need a secret and API permissions.
Step 4 - Create a client secret
- Open Certificates & secrets.
- Client secrets → New client secret.
- Description: e.g.
Policytab; choose an expiry per your security policy. - Click Add.
- 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
- Open API permissions → Add a permission.
- Choose Microsoft Graph → Application permissions (not Delegated).
- 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.AllPolicy.ReadWrite.ConditionalAccessGroup.ReadWrite.AllDirectory.Read.AllAuditLog.Read.All- (and the rest of the Connect checklist)
- Click Grant admin consent for [Customer Name] and confirm Yes.
- 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
- Return to Connect for this customer in Policytab.
- Paste Directory (tenant) ID, Application (client) ID, and Client secret Value.
- 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
| Symptom | What to check |
|---|---|
| Graph token failed | Admin consent granted? Secret expired? App created in customer tenant (single tenant)? |
| Invalid client secret | Paste the secret Value, not Secret ID; create a new secret if needed |
| Tenant could not be verified | App is in the wrong directory; add tenant hint |
| Connect page errors after save | Wait a minute and retry; confirm no typo in client ID |
Removing a customer during setup
If you added the wrong customer or want to start over before Graph is connected:
- Open Customer settings in the tenant nav (available before Summary appears).
- Owner role: type the customer display name and Delete customer permanently.