How to configure Microsoft 365

Overview

This guide walks you through creating a Microsoft 365 app registration that Dex can use to manage a customer tenant. At the end you will have three values to paste into the Add tenant dialog:

1. Directory (tenant) ID
2. Application (client) ID
3. Client secret value

The automated script takes about 3 minutes; the manual route 5–10 minutes. Either way, it must be performed by someone with Global Administrator (or Privileged Role Administrator + Cloud Application Administrator) on the customer's Microsoft 365 tenant.

Run the setup script

Instead of clicking through the Entra portal, run one script that creates the app registration, the client secret, all required Microsoft Graph permissions, and grants admin consent — then prints the three values you need for the Dex Add tenant dialog. Takes about 3 minutes per tenant and requires a Global Administrator account on the customer's tenant.

Download: https://download.dex365.ai/windows/Setup-DexTenant.ps1

Option A — Azure Cloud Shell (nothing to install)

Cloud Shell runs in the browser with the Microsoft Graph modules already available, so this works the same on any computer.

1. Open a private/incognito window (so you don't mix up tenants) and go to https://shell.azure.com.
2. Sign in with a Global Administrator account of the customer's tenant. If prompted, choose PowerShell (not Bash) and No storage account required if offered.
3. Paste these two lines and press Enter:

Invoke-WebRequest -Uri "https://download.dex365.ai/windows/Setup-DexTenant.ps1" -OutFile Setup-DexTenant.ps1
./Setup-DexTenant.ps1

4. When prompted, sign in with the same Global Admin account and accept the requested permissions (Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All). This consent is for running the script, not for Dex itself.
5. When the script finishes, copy the three printed values — Tenant ID, Client ID, and Client Secret — and continue to Add the tenant in Dex below.

Option B — Local PowerShell (Windows, macOS, or Linux)

PowerShell 7+ recommended (Windows PowerShell 5.1 also works). The script auto-installs the Microsoft.Graph.Authentication and Microsoft.Graph.Applications modules to your user profile if missing. No admin rights are needed on the computer — only on the tenant.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Invoke-WebRequest -Uri "https://download.dex365.ai/windows/Setup-DexTenant.ps1" -OutFile Setup-DexTenant.ps1
./Setup-DexTenant.ps1

Sign in with a Global Administrator of the customer's tenant when the browser prompt appears, then copy the three printed values into the Dex Add tenant dialog.

Optional parameters

What the script does

1. Signs in to Microsoft Graph as you (Global Admin), requesting only Application.ReadWrite.All and AppRoleAssignment.ReadWrite.All for the session.
2. Creates a single-tenant app registration named Dex.
3. Creates a client secret (24 months by default).
4. Adds all 27 Microsoft Graph application permissions required by Dex (full list below).
5. Creates the service principal (Enterprise Application).
6. Grants admin consent for every permission.
7. Prints the Tenant ID, Client ID, and Client Secret and disconnects.

The script makes no other changes to the tenant and stores nothing. Once it finishes, continue to Add the tenant in Dex below.

Add the tenant in Dex

1. In the Dex MSP dashboard, click Add tenant.
2. Enter an Organization name (this is the label that will show in your MSP dashboard — it does not need to match the M365 tenant name).
3. Select Microsoft 365.
4. Paste the three values you collected:
   • Tenant ID → printed by the script
   • Client ID → printed by the script
   • Client Secret → printed by the script (shown only once)
5. Click Add Tenant.

Dex will:

Permissions the script granted

For reference — these are the 27 Microsoft Graph application permissions Setup-DexTenant.ps1 added and consented to, and why Dex needs each one.

Troubleshooting

Rotating the secret later

Client secrets expire. To rotate without downtime:

1. In the app's Certificates & secrets page, create a new client secret.
2. In the Dex MSP dashboard, open the tenant and update its credentials with the new secret Value.
3. Once Dex confirms the new secret works, delete the old secret in Entra.

Or create the new secret from PowerShell in the customer tenant (then continue from step 2 above):

Connect-MgGraph -Scopes "Application.ReadWrite.All" -NoWelcome
$app = Get-MgApplication -Filter "displayName eq 'Dex'"
$new = Add-MgApplicationPassword -ApplicationId $app.Id -PasswordCredential @{
    DisplayName = "Dex integration (rotated)"
    EndDateTime = (Get-Date).AddMonths(24)
}
$new.SecretText