Getting Started

Welcome to Primera Labs! This guide will help you get started with migrating your Microsoft 365 groups, distribution lists, and security groups between tenants.

Overview

Primera Labs provides a comprehensive migration solution that handles:

• Distribution Lists (DLs)
• Security Groups
• Dynamic Distribution Lists
• Group memberships and permissions
• Group settings
• Group proxy addresses

Prerequisites

Before you begin, ensure you have:

1. Administrative Access: Global Administrator or Exchange Administrator role in both source and target tenants
2. API Credentials: Application registration with appropriate Microsoft Graph permissions
3. Network Access: Ability to connect to both Microsoft 365 endpoints
4. License: Active Primera Labs subscription

Quick Start

Note: Before starting your first migration, it's important to plan and scope your project. Review group memberships, permissions, and dependencies to avoid surprises during migration. For a detailed guide on scoping, planning, and managing the migration process, see Migration Planning & Management.

Step 1: Creating your first workspace

Use the Primera Labs management site to create your first workspace and start your migration.

Once logged into the management site, select Workspaces and create your first workspace

If you haven't created an Azure AD application yet, first complete the “Register App” steps below. Otherwise, skip down to "Add connection in the management site" and use your existing app credentials.

Register an Azure AD application (if needed):

1. Open the Azure portal and go to Azure Active Directory → App registrations.
2. Click New registration.
   • Name: enter Primera Labs Migration - <your org>
   • Supported account types: choose Accounts in this organizational directory only (Single tenant)
   • Leave Redirect URI blank
3. Click Register. After the app is created, copy the Application (client) ID and Directory (tenant) ID from the app Overview page.
4. In the app, go to Certificates & secrets → New client secret. Give it a description and expiration, then click Add and copy the secret value immediately (you won't be able to see it again).
5. Go to API permissions → Add a permission → Microsoft Graph → Application permissions and add:
   • Group.ReadWrite.All
   • Directory.ReadWrite.All Then click Grant admin consent for your tenant.
6. For Exchange Online operations, ask your Exchange admin to assign the application the Organization Management role. (If you manage Exchange via PowerShell, the admin can run: New-ManagementRoleAssignment -Role "Organization Management" -App <AppId>.)

Add the connection in the Primera Labs management site (UI steps):

1. Sign in to the management site and open Settings → Tenant Connections.
2. Click Add connection (or Connect tenant).
3. Choose Use existing Azure AD app (or Register new app if you want the site to guide you through registration).
4. Fill these fields exactly:
   • Client ID: paste the Application (client) ID from Azure
   • Client Secret: paste the client secret value you created
   • Source Tenant (Primary domain): e.g. source.onmicrosoft.com
   • Destination Tenant (Primary domain): e.g. destination.onmicrosoft.com
   • Tenant ID (optional): paste the Directory (tenant) ID if prompted
5. Click Save.
6. On the new connection row, click Test connection. Wait for the status — you should see Connected and a green check if credentials and permissions are correct.

Tips & troubleshooting:

• If the Test connection fails with permission errors, confirm you granted Application permissions in Azure Graph and clicked Grant admin consent.
• If Exchange operations fail, confirm the app has been assigned the Organization Management role in Exchange.
• Never store client secrets in source control — use the management site's secure secrets storage or an external secrets manager.

If you prefer CLI or automated configuration, you can provide the same values as environment variables or in a JSON config file; see the API Authentication guide for token examples and details: /docs/api-reference/authentication.

Step 2: Run Discovery

Scan your source tenant to identify all groups and distribution lists:

Start-PrimeraDiscovery -TenantId "source.onmicrosoft.com"

This process typically takes 5-15 minutes depending on the size of your environment.

Step 3: Review Migration Plan

Review the generated migration plan:

Get-PrimeraMigrationPlan -PlanId "your-plan-id"

Step 4: Execute Migration

When you're ready, execute the migration:

Start-PrimeraMigration -PlanId "your-plan-id"

What's Next?

• Learn about Migration Planning
• Explore the API Reference
• Review Best Practices
• Check out Common Issues

Getting Help

If you need assistance:

• Documentation: Browse our comprehensive docs
• Support: Contact support@primeralabs.tech
• Community: Join our community forum

System Requirements

Supported Environments

• Microsoft 365 (all plans)
• Exchange Online
• Azure Active Directory

Required Permissions

• Microsoft Graph: Group.ReadWrite.All, Directory.ReadWrite.All
• Exchange Online: Organization Management role

Recommended Tools

• PowerShell 7.0 or later
• Azure PowerShell module
• Exchange Online Management module

Next Steps

Ready to dive deeper? Continue to our detailed Migration Guide or explore specific topics in the sidebar.