Workspace Setup
Create the source and target app registrations, grant the right permissions and roles, and connect both tenants in a workspace.
A workspace is one migration project: one source tenant paired with one target tenant. It holds the connection details for both tenants, plus everything you discover and migrate.
Primera Labs connects to each tenant through an app registration that you create in that tenant. You need two: one in the source tenant and one in the target tenant.
Choose a setup method
In the management site, go to Workspaces and click New Workspace. You get two options:
- Guided Setup (Recommended). A step-by-step wizard that walks you through creating each app registration, then asks you to name the workspace. Use this if you haven't created the app registrations yet.
- Manual Entry. One form for both tenants, with a Test Connection button for each. Use this if your app registrations already exist.
Guided Setup doesn't test the connection. After you create a workspace with it, open the workspace for editing (it opens in the Manual Entry form) and use Test Connection for each tenant before your first migration. See Pre-Migration Checks.
Step 1: Create the app registration
Do this once in the source tenant and once in the target tenant.
- Sign in to the Microsoft Entra admin center for the tenant and open App registrations.
- Click New registration.
- Enter a name. The wizard suggests
PrimeraLabs-M365-Migration-SourceandPrimeraLabs-M365-Migration-Target. - Under supported account types, select Accounts in this organizational directory only.
- Leave Redirect URI blank and click Register.
- From the app's Overview page, copy the Directory (tenant) ID and the Application (client) ID.
Step 2: Add API permissions
All permissions are Application permissions, not Delegated.
In the app registration, open API permissions and click Add a permission.
Source tenant app
From Microsoft Graph → Application permissions, add:
Group.Read.AllGroupMember.Read.AllUser.Read.AllDomain.Read.All
Then click Add a permission again, choose APIs my organization uses, search for Office 365 Exchange Online, choose Application permissions, and add:
Exchange.ManageAsApp
Target tenant app
From Microsoft Graph → Application permissions, add:
Group.ReadWrite.AllGroup.Read.AllGroupMember.Read.AllUser.Read.All
From Office 365 Exchange Online → Application permissions, add:
Exchange.ManageAsApp
Grant admin consent
After adding the permissions, click Grant admin consent for [your tenant] and confirm. Every permission should then show Granted in the Status column. Without admin consent, every call Primera Labs makes will fail.
Step 3: Create a client secret
Primera Labs authenticates with a client secret. Certificates are not supported.
- Open Certificates & secrets and click New client secret.
- Enter a description such as
PrimeraLabs Migrationand choose an expiry. 24 months is recommended so the secret doesn't expire mid-project. - Click Add, then copy the secret's Value straight away. You can't see it again after you leave the page.
Warning
Copy the Value, not the Secret ID. Pasting the Secret ID is the most common setup mistake.
Step 4: Assign a directory role
The app also needs an admin role so it can run Exchange Online commands.
- Target tenant app: Exchange Administrator. Primera Labs needs this to create distribution groups and change their settings.
- Source tenant app: Global Reader, the least-privileged option. Exchange Recipient Administrator also works.
To assign the role:
- In the Entra admin center, open Roles & admins.
- Search for and select the role.
- Click Add assignments, search for your app by name, select it and click Add.
Role assignments can take up to an hour to take effect.
Warning
If the source app is missing its role or Exchange.ManageAsApp, migrations still run, but owners and Exchange settings can't be read from the source. Groups are then created without their owners and without those settings.
Step 5: Enter the details in the workspace
For each tenant, enter:
- Tenant ID: the Directory (tenant) ID
- Tenant Name: optional, a friendly name shown in the app
- App Client ID: the Application (client) ID
- App Client Secret: the secret Value
With Manual Entry, also give the workspace a Name and optional Description, then click Test Connection for each tenant and fix any errors before clicking Create Workspace. Guided Setup asks for the name at the end, under Finalize Workspace.
Client secrets are stored encrypted and are never shown again in the management site.
Select the workspace
The workspace you're working in is shown in the header, and the migration pages always act on it. To switch, use the workspace switcher in the header, or click Select on a workspace card on the Workspaces page.
Edit a workspace
Click the edit icon on the workspace card. The form opens with your saved details, except the secrets. Leave a secret blank to keep the stored one, or enter a new one to replace it. You'll need to do this when a client secret expires.
Only the workspace Owner and Admins can edit a workspace.
Delete a workspace
Click the delete icon on the workspace card and confirm. Only the workspace Owner can delete it.
Deleting a workspace permanently removes its stored credentials, discovered groups, user mappings and job history. Groups that were already migrated stay in the target tenant. Deleting a workspace also frees the licenses its groups were using. See Billing and Licenses.
How many workspaces can I have?
- No plan, or the Starter plan: one workspace
- Professional and Elite plans: no limit
Next steps
Was this page helpful?
Something wrong or out of date?