Connecting to a SharePoint Site or Server
The same connection methods and options can be used for a normal connection to SharePoint and a read-only connection to SharePoint. The below steps can be used for both connection types. The read-only connection can be used to help users keep their source and target connection separate (and it can help ensure that users do not accidentally migrate any data to a source connection).
NOTES:
·When making a secure connection to a SharePoint URL that is configured with TLS, Content Matrix can use any version of TLS that is compatible with .NET Framework 4.7.2. The default version of TLS used by the operating system on the machine from which you are connecting will be used by Content Matrix.
·Currently, connections to a SharePoint server cannot be made for SharePoint 2019 in a FIPS-enabled environment. (See Errors Connecting to SharePoint 2019 or SharePoint Server Subscription Edition in a FIPs-Enabled Environment for more information.)
To connect to a SharePoint site or server:
In the Content Matrix ribbon, choose Connection > Connect to SharePoint.
To complete the Connection Options tab:
1.For Address, enter either the URL or IP address of the SharePoint site or server to which you want to connect.
Note that the drop-down menu displays a list of previous connections.
2.For Target Type, select the connection type. Use the information in the following table for guidance.
|
If you want to connect |
Select |
|---|---|
|
directly to a SharePoint site |
Site.
|
|
to a specific Web application on a SharePoint server |
Web App.
NOTE: This option can only be used if using the Local or Metalogix Extensions Web Service connection type. |
|
to a SharePoint instance at the Farm/server level (which will allow you to see all site collections for all Web Application on the selected server) |
Farm.
NOTE: This option can only be used if using the Local or Metalogix Extensions Web Service connection type. |
3.Select a Connection Type from the drop-down. Use the information in the following table for guidance.
|
If |
Select |
Notes |
|---|---|---|
|
you want to have Content Matrix choose the connection adapter type that makes the most sense for the target SharePoint instance |
Auto Detect |
·If the SharePoint instance is local (installed on the same machine as the Content Matrix Console), the Local Connection (SharePoint Object Model) will be used ·If the SharePoint instance is remote (installed on another machine), and the Metalogix Extensions Web Service is installed, the Remote Connection (Metalogix Extensions Web Service) type will be used. |
|
Content Matrix Console is installed locally (that is, on the same SharePoint server or one of its Web Front Ends (WFEs) |
Local Connection (SharePoint Object Model) |
This connection type ·is generally recommended for the target SharePoint instance if possible, to help with performance and to help provide the product with greater leverage into SharePoint. AND ·the account used for the connection. must be the logged in user and have the following permissions: ·Farm Administrator ·Site Collection Administrator ·DB_Owner on the Content Database (to allow the connecting user access to the local SharePoint Object Model). |
|
·Content Matrix Console is not installed locally AND ·Metalogix Extensions Web Service (MEWS) is installed on the SharePoint server/WFE to which you are connecting |
Remote Connection (Metalogix Extensions Web Service) |
The connecting account requires Full Control over the content being connected to and migrated. Additional permissions are provided through the use of the Metalogix Extensions Web Service. NOTE: Although it is strongly recommended that the version of the Metalogix Extensions Web Service (MEWS) match the installed version of Content Matrix, you can override it to use an earlier MEWS version. |
NOTE: As of version 9.5, Content Matrix no longer supports CSOM connections to SharePoint on premises. The option will work for backward compatibility with existing jobs, but if you select it for a new connection, a pop-up warning will display.
4.For Authentication Type, select the method to use when trying to connect to the specified SharePoint instance.
Use the information in the following table for guidance.
|
If |
Select . |
Notes |
|---|---|---|
|
you want Content Matrix to automatically check against the SharePoint environment |
Auto Detect |
Content Matrix will check for non-Microsoft 365 authentication types listed in the drop-down (in order), and use the first method that is found. |
|
you want to connect to the SharePoint environment using the currently logged in Windows users credentials |
Windows Authentication |
·The logged in user credentials are used by default; however, other credentials that use this authentication method can also be entered. ·This is the authentication type that most environments use. |
|
·you selected Metalogix Extensions Web Service as the Connection Type AND ·you want to connect using Forms Based Authentication |
Forms Based Authentication |
·Most setups for Forms Based Authentication are supported. ·This method is limited to the Metalogix Extensions Web Service connection type because it authenticates through IIS and not Active Directory (AD). NOTE: This authentication type is not supported for running a job using a PowerShell script. Refer to the Quest Support Knowledge Base article Connections that will work with PowerShell and Connections that doesn't work with PowerShell for complete details. |
|
Web Browser Authentication (Not Auto Detected) |
This option is not searched for within the Auto Detect option, and needs to be manually set. In order for the Content Matrix Console to logon to the system, users must have logged on to the system being connected to through the web browser on that system first (only before the initial connection). Since this is all done using the Web browser for authentication, the credentials section of the window will be grayed out (since it is not needed), and it is limited to the Metalogix Extensions Web Services Connection Type because it authenticates through IIS and not the Active Directory (AD).
NOTES: ·Because this authentication type uses cookies from the browser, it may require multiple logins when running a single migration. However, this is only likely if the migration is running for a long session; this is mainly determined by the web browser settings for authentication. In the event that a login is required, a dialog box appears that lets users log in. After the user logs in, the migration will continue from where it left off.
·This authentication type is not supported for running a job using a PowerShell script. Refer to the Quest Support Knowledge Base article Connections that will work with PowerShell and Connections that doesn't work with PowerShell for complete details. |
5.For Connect As, enter/select the login credentials you want to use to connect to the SharePoint site/server. Use the information in the following table for guidance.
NOTE: This option is disabled if you selected Local Connection (SharePoint Object Model) or Web Browser Authentication (Not Auto Detected).
|
If you want to |
Then |
|---|---|
|
use the current Windows user's authentication credential |
Select the (default) <Domain>\<user> radio button. |
|
use different authentication credentials |
·Select the Different User radio button, and ·Enter the applicable user name and Password. In cases where alternate credentials are entered, it is recommended that you select the Remember my password check box so Content Matrix will automatically remember that user account password. This is especially important if you chose Web Browser Authentication, as credentials must be stored in the Credential Manager vault before the connection is made. |
6.If you need to configure proxy settings:
a)Select the Proxy Options tab.
b)Follow the procedure for Configuring Proxy Settings.
7.If you want to Add or Remove certificates to be included when connecting to SharePoint:
a)Select the Included Certificates tab.
Please see the Connecting with Certificates for more details on connecting to SharePoint instances that require certificates.
b)After all of the desired connection options have been set, for all options tabs, click [OK] to establish the connection.
If you selected a connection type other than Site, the Limit Site Collections dialog displays, giving you the option to limit the site collections to include in your connection (when importing an xml file with the list of URLs you want to include). This is useful if the environment you are connecting to includes a very large number of site collections. In this case, limiting displayed site collections can improve performance.
NOTE: If you want to View Sample xml, click the link on the dialog. The xml file you import must follow the same format as this sample.
8.Either:
§Click [Yes Import from XML] to specify the URLs of the sites you want to include in the connection, then browse/upload the file
OR
§Click [No Continue with Connection] to add all sites within the selected scope to the connection.
If Content Matrix successfully makes the connection, a new node will appear in the Explorer View, and you can expand this node and navigate through the SharePoint objects.
Connecting to SharePoint Online
Content Matrix Console can make a tenant or site level connection to a SharePoint Online environment.
To connect to SharePoint Online:
In the Content Matrix ribbon, choose Connection > Connect to SharePoint.
To complete the Connection Options tab:
1.For Address, enter either the URL or IP address of the SharePoint site or tenant to which you want to connect.
Note that the drop-down menu displays a list of previous connections.
2.For Target Type, select the connection type. Use the information in the following table for guidance.
|
If you want to connect |
Select |
Notes |
|---|---|---|
|
directly to a SharePoint site |
Site.
|
This option must be used for a site-level connection to a Microsoft 365 tenant NOTE: If you want to connect to a Microsoft 365 tenant root node, use the Microsoft 365 Tenant connection type. |
|
to the root of a Microsoft 365 Tenant environment (comparable to a farm-level connection in an on premises environment) |
Microsoft 365 Tenant. |
This connection type has most of the limitations of the CSOM connection adapter, but can run Site Collection migrations. |
3.For Connection Type, select Remote Connection (SharePoint Client Side Object Model O365).
NOTE: If you accept the default (Auto Detect), this option will be detected automatically.
4.For Authentication Type, select the method to use when trying to connect to the specified SharePoint instance. When connecting to Microsoft 365, the two main Authentication Types will be Microsoft 365 OAuth/Standard/ADFS Authentication and Microsoft 365 Web Browser Authentication (Not Auto Detected). Use the information in the following table for guidance.
For a SharePoint Online connection that uses "modern" (not "legacy") authentication, you must select one of the Microsoft 365 OAuth Authentication options or Microsoft 365 Web Browser. If the account is also part of a SharePoint Online Multi-Factor Authentication Policy, Microsoft 365 Web Browser or Microsoft 365 OAuth with MFA Authentication must be used.
NOTE: Microsoft 365 Web Browser Authentication is not supported for jobs run from a PowerShell script.
For more information about legacy vs. modern authentication, refer to the Microsoft article Microsoft 365 feature descriptions.
|
If |
Select . |
Notes |
|---|---|---|
|
you want Content Matrix to automatically check against the SharePoint environment |
Auto Detect |
Content Matrix will check for authentication types listed in the drop-down (in order), and use the first method that is found. NOTE: At the time you click [OK] to complete the connection, a pop-up box will display that asks if you want to use Microsoft 365 OAuth. See Using Microsoft 365 OAuth Authentication to Connect to SharePoint Online for details. |
|
·you want to connect to Microsoft 365 OAuth, Microsoft 365 Standard editions, or systems with ADFS AND ·MFA is not being used |
Microsoft 365 OAuth/Standard/ADFS Authentication* |
By default the logged in user credentials will be unavailable, since this uses the Windows authentication method, and the Microsoft 365 credentials will need to be entered. NOTE: At the time you click [OK] to complete the connection, a pop-up box will display that asks if you want to use Microsoft 365 OAuth. See Using Microsoft 365 OAuth Authentication to Connect to SharePoint Online for details. |
|
your account requires the use of Multi-Factor Authentication (MFA) |
Microsoft 365 OAuth with MFA Authentication (Not Auto Detected)* |
With this authentication type, you do not have to enter account credentials in Content Matrix, and the Connect As options will be disabled. |
|
you want to connect through a Web browser |
Web Browser Authentication (Not Auto Detected) |
This option is not searched for within the Auto Detect option, and needs to be manually set. In order for the Content Matrix Console to logon to the system, users must have logged on to the system being connected to through the web browser on that system first (only before the initial connection). Since this is all done using the Web browser for authentication, the credentials section of the window will be grayed out (since it is not needed), and it is limited to the Metalogix Extensions Web Service Connection Type because it authenticates through IIS and not the Active Directory (AD).
NOTES: ·Because this connection method uses cookies from the browser, it may require multiple logins when running a single migration. However, this is only likely if the migration is running for a long session; this is mainly determined by the web browser settings for authentication. In the event that a login is required, a dialog box appears that lets users log in. After the user logs in, the migration will continue from where it left off. ·For migrations from SharePoint Online to SharePoint Online, web browser authentication is currently not supported for a source connection. ·This authentication type is not supported for running a job using a PowerShell script. Refer to the Quest Support Knowledge Base article Connections that will work with PowerShell and Connections that doesn't work with PowerShell for complete details. |
|
you want to connect through a Web browser using authentication for Microsoft 365 |
Microsoft 365 Web Browser Authentication |
This option works the same as Web Browser Authentication (Not Auto Detected) except: ·it looks for more specific Microsoft 365 cookies ·it requires that users first log into Microsoft 365 through the browser ·instead of allowing multiple logins, only one "request" for data can be made at a time, which ensures that no data is missed or lost due to the system locking from too many requests (but which may result in a slower connection). NOTE: This authentication type is not supported for running a job using a PowerShell script . Refer to the Quest Support Knowledge Base article Connections that will work with PowerShell and Connections that doesn't work with PowerShell for complete details. |
|
you want to make a site-level connection to a GCC High site using Microsoft 365 User Provided Authentication |
Microsoft 365 User Provided Authentication (hidden by default) |
You must first run a utility provided by Quest Support and enable the setting EnableUserProvidedAuthentication. Refer to the Quest Support Knowledge Base article Enabling User Provided Authentication in Content Matrix for details. |
* If you are connecting to SharePoint Online using OAuth authentication and you used a custom domain as the Address, you will also need to check the Override SharePoint Online Tenant Domain Name and enter the default tenant domain name (which can be found at https://admin.microsoft.com/Adminportal#/Domains) to allow Content Matrix to route the request to the proper region.
5.For Connect As, enter/select the login credentials you want to use to connect to the SharePoint site/server. Use the information in the following table for guidance.
NOTE: This option is disabled if you selected Microsoft 365 OAuth with MFA Authentication, or Web Browser Authentication (Not Auto Detected).
|
If you want to |
Then |
|---|---|
|
use the current Windows user's authentication credential |
Select the (default) <Domain>\<user> radio button. |
|
use different authentication credentials |
·Select the Different User radio button, and ·Enter the applicable user name and Password. In cases where alternate credentials are entered, it is recommended that you select the Remember my password check box so Content Matrix will automatically remember that user account password. This is especially important if you chose Web Browser Authentication, as credentials must be stored in the Credential Manager vault before the connection is made. |
6.If you want to Add or Remove certificates to be included when connecting to SharePoint:
a)Select the Included Certificates tab.
Please see the Connecting with Certificates for more details on connecting to SharePoint instances that require certificates.
b)After all of the desired connection options have been set, for all options tabs, click [OK] to establish the connection.
If you are making a tenant-level connection, the Limit Site Collections dialog displays, giving you the option to limit the site collections to include in your connection (which by importing an xml file with the list of URLs you want to include). This is useful if the environment you are connecting to includes a very large number of site collections. In this case, limiting displayed site collections can improve performance. Additionally, the Include Microsoft 365 tenant my site host connection allows One Drives to display under their own top-level connection node (alongside the main tenant node) with the following URL format: http://[Tenant URL]-my.sharepoint.com. It is selected by default, but if you want to exclude them from the connection, uncheck this box.
NOTE: If you want to View Sample xml, click the link on the dialog. The xml file you import must follow the same format as this sample.
7.Either:
§Click [Yes Import from XML] to specify the URLs of the sites you want to include in the connection, then browse/upload the file
OR
§Click [No Continue with Connection] to add all sites within the selected scope to the connection.
If Content Matrix successfully makes the connection, a new node will appear in the Explorer View (two if you opted to include One Drives), and you can expand the node(s) and navigate through the SharePoint objects.
NOTE: Should the log file ever show a "could not find site on remote SharePoint server" exception message when working with CSOM connections, simply restart the CSOM service on all machines running the Content Matrix console and then rerun the action.
Using Office Microsoft 365 OAuth Authentication to Connect to SharePoint Online
Microsoft 365 OAuth Authentication is a token-based authentication method that can be used as an alternative to Standard/ADFS Authentication to reduce throttling.
If Multi-Factor Authentication is set up for the tenant and enabled for the account (as described in the Microsoft TechNet article SharePoint Online - Microsoft 365: Set up Multi-Factor Authentication), you can connect using M365 OAuth with MFA Authentication as an alternative to Microsoft 365 Web Browser authentication.
Registering the Content Matrix SharePoint Client Application for OAuth Authentication
The very first time OAuth Authentication is selected, the application Content Matrix SharePoint Client must be registered for the tenant.
IMPORTANT: Prior to version 9.2, the Metalogix SharePoint Migration Client application was used for OAuth Authentication. Jobs created before version 9.2 (including those that use PowerShell) will continue to use this application (as long as it is still registered in Entra ID). Starting with version 9.2, all jobs using OAuth Authentication will use the Content Matrix SharePoint Client application.
Required Permissions
At a minimum, the following permissions are required to register and provide consent for the Content Matrix SharePoint Client application.
·For a site-level connection, the account must have a minimum of Site Administrator and Application Administrator permission roles.
·For a tenant-level connection, the account must have a minimum of Application Administrator permission role.
Providing Consent to Grant the Application Requested Permissions
The first time a Content Matrix user attempts to connect to SharePoint Online using Microsoft 365 OAuth Authentication, a dialog displays requesting that you grant the permissions that the application needs to perform migrations.
A Global Administrator can check the Consent on behalf of your organization box, which will prevent this dialog from displaying for other users. If the account is not a Global Administrator, the Consent on behalf of your organization option will be hidden.
IMPORTANT: If a Global Administrator does not consent on behalf of the organization, each Content Matrix user who attempts to connect using Microsoft 365 OAuth Authentication for the first time must sign in with an account that has the Application Administrator and SharePoint Administrator permission role.
After [Accept] is clicked, the connection is created (and the application will be registered if it does not already exist in Entra ID). In addition, the token cache file ConnectionsTokenCache.dat is created in the AppData/Roaming/Metalogix folder. (Note, if you have used OAuth Authentication in an earlier version of Content Matrix, this file will already exist.)