# User migration

This step onboards your existing Microsoft 365 users to Peig while Microsoft still handles authentication. Users sign in with their existing Microsoft credentials during this phase. Once everyone is onboarded, the migration configuration is removed and you proceed to federation.

{% hint style="warning" %}
This phase is time-sensitive. Plan a clear onboarding window and communicate the deadline to your team before starting. All users must be onboarded before you proceed to Step 5.
{% endhint %}

## Phase 1: Set up the Migration App

A temporary migration application in Microsoft Entra allows users to sign in with their existing Microsoft credentials while onboarding to Peig.

### Retrieve your Peig server details

{% stepper %}
{% step %}

### Open the Configuration app

Open the **Configuration** app in Peig.
{% endstep %}

{% step %}

### Open SAML IDP Info

Click **SAML IDP Info**.
{% endstep %}

{% step %}

### Note the server value

Note the **\[SERVER]** value from the IDP Entity ID URL — it appears in the format `https://[SERVER]/idp/shibboleth`
{% endstep %}
{% endstepper %}

### Create the Migration App in Microsoft Entra

{% stepper %}
{% step %}

### Visit Microsoft Entra

Visit [https://entra.microsoft.com](https://entra.microsoft.com/)
{% endstep %}

{% step %}

### Open Enterprise applications

Navigate to **Identity → Applications → Enterprise applications**.
{% endstep %}

{% step %}

### Create a new application

Click **New application → Create your own application**.
{% endstep %}

{% step %}

### Name the application

Set the name to `PeigMigrationManager`.
{% endstep %}

{% step %}

### Select a non-gallery application

Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
{% endstep %}

{% step %}

### Register the app

Click **Register**.
{% endstep %}
{% endstepper %}

### Configure SAML for the Migration App

{% stepper %}
{% step %}

### Open Single Sign-On

Go to **Single Sign-On** and select **SAML**.
{% endstep %}

{% step %}

### Enter the SAML configuration values

Enter the following SAML configuration values, replacing `[SERVER]` with the value noted above:

* **Identifier (Entity ID):** `https://[SERVER]/aducid-onboard/m365/metadata`
* **Reply URL (ACS URL):** `https://[SERVER]/aducid-onboard/m365/acs`
  {% endstep %}

{% step %}

### Save the configuration

Click **Save**.
{% endstep %}

{% step %}

### Download the certificate

Open **SAML Certificates** and download the **Certificate (Base64)**.
{% endstep %}

{% step %}

### Copy the certificate contents

Open the certificate file and copy its full contents.
{% endstep %}

{% step %}

### Save the Application ID

From the **Overview** page, copy and save the **Application ID**.
{% endstep %}
{% endstepper %}

### Set the Migration Configuration in Peig

{% stepper %}
{% step %}

### Open the Migration section

Open **Configuration** in Peig and find your Microsoft 365 Active Provider.
{% endstep %}

{% step %}

### Enter the Application ID

Open the **Migration** section and enter the **Application ID** from the Entra migration app.
{% endstep %}

{% step %}

### Paste the IDP Certificate

Paste the **IDP Certificate** contents you copied.
{% endstep %}

{% step %}

### Validate and save

Click **Validate**, then **Save**.
{% endstep %}
{% endstepper %}

## Run the onboarding window

With the migration configuration in place, users can now onboard to Peig using their existing Microsoft credentials.

{% stepper %}
{% step %}

### Communicate the onboarding details

Share clear instructions, the workspace name, and the onboarding deadline with your team.
{% endstep %}

{% step %}

### Have users onboard

Users download Peig, join the workspace, and sign in with their Microsoft 365 credentials.
{% endstep %}

{% step %}

### Monitor the onboarding window

Monitor **Users & Access** throughout the window — check for pending requests, users with **Not Onboarded** status, and any requests with mismatched email addresses.
{% endstep %}
{% endstepper %}

## Phase 2: Handle users who did not onboard (if needed)

If some users did not complete onboarding during Phase 1, use the **MS365 Identifiers** tool to manually create their accounts:

{% stepper %}
{% step %}

### Open MS365 Identifiers

Open **MS365 Identifiers** in Peig.
{% endstep %}

{% step %}

### Open the Microsoft 365 Accounts tab

Go to the **Microsoft 365 Accounts** tab.
{% endstep %}

{% step %}

### Create Peig accounts

For each Microsoft 365 user without a Peig account, click **Create Peig Account**.
{% endstep %}
{% endstepper %}

If all users completed onboarding in Phase 1, skip this phase.

{% hint style="info" %}
For more detail on resolving account mismatches and identifier issues, see [Managing MS365 Identifiers](broken://pages/e7ba2b01438b6ebce47a4809b702a906834e1023).
{% endhint %}

## Close the migration

Once all users are onboarded, remove the migration configuration:

{% stepper %}
{% step %}

### Open Configuration

Open **Configuration** in Peig.
{% endstep %}

{% step %}

### Find your Microsoft 365 Active Provider

Find your Microsoft 365 Active Provider.
{% endstep %}

{% step %}

### Open the Migration section

Open the **Migration** section.
{% endstep %}

{% step %}

### Delete the migration configuration

Delete the migration configuration.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Only delete the migration configuration after confirming that all users are onboarded and their accounts are correctly linked. This action cannot be undone.
{% endhint %}

## Confirm your setup

Before moving to Step 5, verify:

* [ ] All users have been onboarded to Peig
* [ ] All accounts are correctly created and linked
* [ ] Phase 2 was completed if any users missed the onboarding window
* [ ] The migration configuration has been deleted

{% hint style="success" %}
Next: [Step 5 — Federation Setup](/welcome-to-peig-documentation/deployment-guides/microsoft-365/federation-setup.md)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.peig.io/welcome-to-peig-documentation/deployment-guides/microsoft-365/user-migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.