Add or edit an Exchange Online connection

Follow these steps to add a connection from Exchange Online (Microsoft 365) to your Google Workspace account.

Important: These steps apply to Google Workspace version 2.4.18.0 or later. If you are using an earlier version of Google Workspace, refer to the instructions here.

Before you begin

If you have existing Exchange Online connections that you created using a Google Workspace Migrate version earlier than 2.4.18.0, delete the connections and re-create them using these steps. For more information, go to Deprecation of the ApplicationImpersonation role in Exchange Online.

Add an Exchange Online connection

The specific Microsoft steps might vary depending on your Azure portal version and updates made by Microsoft. Refer to Microsoft's documentation for the latest guidance on app registration and authorization.

Step 1: Register a new application

For security reasons, we recommend that you register the new app as a single tenant.

1. As an admin, sign in to your Microsoft Azure portal.
2. In Azure Active Directory (Azure AD), navigate to App registrations.
3. Click New registration and enter a name for your application.
4. For supported account type, select Accounts in this organizational directory only (single tenant).
5. Leave the Redirect URI field blank and click Register.

Step 2: Configure API permissions

1. In the left navigation, for Manage, select Manifest.
2. Locate the requiredResourceAccess property in the manifest, and add the following inside the square brackets (if there is already a value present in the square brackets, add a comma and the new value):

   {

       "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",

       "resourceAccess": [

           {

               "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",

               "type": "Role"

           }

       ]

   }

3. Select Save.
4. Click API permissions, and confirm that the full_access_as_app permission is listed.

Step 3: Grant admin consent

1. Click Grant admin consent for name of organization.
2. Review the permissions and click Yes to confirm.

Step 4: Generate the client secret

1. Click Certificates & secretsNew client secret.
2. Enter a description and select an expiration periodAdd.
3. Copy the client secret value and store it securely. The value is displayed only once.

Step 5: Collect the app credentials

Important: Store the app credentials securely. If the credentials are leaked, hackers could access all of your Exchange data.

Click Overview and securely note the following app credentials:

• Application (client) ID
• Directory (tenant) ID

Step 6: Set up the connection

1. In the Google Workspace Migrate platform, click New Connection.
2. For Name, enter a connection name.
3. For Admin's email address, enter the email address of the Global or Application Administrator of your Azure AD tenant. For more information, go to Exchange admin requirements.
4. For Account, select your account or take the following steps:
   1. Click Add new account.
   2. Enter the client ID, client secret, and tenant ID copied from step 5 (earlier on this page).
5. (Optional) For List, select your user list.
6. Click Create.

   Google Workspace Migrate validates your credentials, creates the connection, and adds an account using the client ID, client secret, and tenant ID.

Troubleshoot connections

Connection errors

Error message	Steps to troubleshoot
Client ID is invalid or unauthorized	The application (client) ID is invalid or isn't installed in your tenant. Make sure that you copied the correct client ID from the app overview page and that the admin has granted their consent for the app.
Client Secret is invalid	The client secret is invalid. Make sure that you copied the client secret and not the client secret ID. If you forgot to copy the client secret, create a new secret and add it.
Tenant ID is invalid	The tenant ID is wrong or invalid. Make sure that you copied the correct tenant ID from the overview page.
Client application is not installed in the provided tenant ID	The app is not installed or the admin hasn't granted their consent for the tenant ID. Make sure the client ID, client secret, and tenant ID are correct and belong to your tenant. Check that the admin has granted their consent for the app.
Admin account does not have access or is not an admin account	The admin email address doesn't have sufficient permissions. Make sure the admin is a Global or Application Administrator and check that they have the correct roles. For details, go to Exchange admin requirements.
Admin email is invalid or has no mailbox associated with it	The admin email address is invalid, doesn't have a mailbox, or isn't part of your organization. Make sure that the admin belongs to your organization and that you have entered the correct admin email address. Verify that the admin has the correct roles. For details, go to Exchange admin requirements.
The request failed. The remote server returned an error: (403) Forbidden	The credentials you entered are incorrect. Make sure that the app has been created in your tenant with the correct permissions and that the admin has granted their consent for the app.

Other errors

Expired authentication token

The authentication token associated with an Exchange Online connection expires if the connection is unused for 90 days. If the issue occurs, edit the connection, then repeat the steps to add an Exchange Online connection.

An unexpected error occurred on a "send" error

If you get this error, check that the Google Workspace Migrate platform and nodes can access the required URLs. For details, go to Additional requirements for Exchange Online.