Content Matrix 9.7 - eRoom Edition User Guide

Registering the Metalogix Content Matrix SharePoint Client Application for OAuth Authentication

The very first time OAuth Authentication is selected, the application Metalogix 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 Azure Active Directory).  Starting with version 9.2, all jobs using OAuth Authentication will use the Metalogix Content Matrix SharePoint Client application.

Required Permissions

At a minimum, the following permissions are required to register and provide consent for the Metalogix 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 Office 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 Office 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 Azure Active Directory).  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.)

Completing a Connection to SharePoint Online Using Office 365 OAuth Authentication

When you select one of the Office 365 OAuth authentication types, before making a connection to SharePoint Online, a pop-up specific to the authentication type will display, as described in the following table.

NOTE:  If you click the Do not show the message again. box, Content Matrix will continue to use the selected option and no longer display the pop-up.  You can resume having the pop-up display by clicking Reset Configuration Options on the ribbon toolbar Settings tab.

Signing into your O365 Account to Use Office 365 OAuth Authentication

When prompted to sign into your O365 account, for Auto Detect or Office365 OAuth/Standard/ADFS Authentication, you must use the account you specified as the Connect As account in Content Matrix.  The connection will fail if you try to sign in with another account. (This is not an issue with Office 365 OAuth with MFA Authentication, which does not use a Connect As account.)

IMPORTANT:  If you are using OAuth Authentication for the first time, a dialog  may display requesting that you consent to granting permissions that the application needs to perform migrations.  To  provide this consent, the account must be an Application Administrator.  (This dialog will not display if a Global Administrator has granted consent on behalf of the organization.)

Connecting with Certificates

Metalogix Content Matrix  can use client certificates to authenticate connections to eRoom servers secured with X.509 Certificates. This type of authentication can be used for RSA authentication implementations that support X.509 Certificates.

When connecting to SharePoint, there are two options that can be used to add certificates to the list of included certificates: Add Installed Certificate and Add Certificate From File.

SharePoint connections do not actually save the certificate information directly, but instead they save the data on how to locate the certificates that are in use. This means that if the certificates are deleted or moved from the referenced location, they will no longer be used with the SharePoint connection and will have to be manually re-added.

SharePoint Certificates are also supported when generating a PowerShell script. It is still recommended that the initial SharePoint connection is first configured in the Metalogix Content Matrix Console. The recommended process when working with certificates and PowerShell is to first add the connection (with certificates) in Metalogix Content Matrix, then set up a migration action in the UI and generate a PowerShell script. This will allow you to get the connection format that is required to create a connection in PowerShell, and it can then be written out manually (if desired).

It should also be noted that the Web Browser Authentication type does not automatically detect certificates. In order for certificates to be included with this method, they must first be installed in the appropriate locations in order for a web browser itself to access them.

NOTE:   In some cases, including certificates can potentially result in receiving "maximum request length" messages when migrating smaller files because the certificate information is included when the data is being migrated.  

To Add Installed Certificates:

Only "Personal" certificates can be added in this manner because it is the only store that web browsers use to find certificates when accessing a website.

1.In the SharePoint Logon dialog, select the Include Certificates tab.

2.Click [Add Installed Certificate].

The Add Installed Certificates dialog displays all of the certificates that are installed in the logged in user account's "Personal" certificate store.

3.Select any certificates that should be included, and click [OK].

When you return to the SharePoint Logon dialog the selected certificates be displayed in the Included Certificates list, and they will be included whenever Metalogix Content Matrix is running an action to or from the SharePoint connection.

To Add a Certificate from a file:

1.In the SharePoint Logon dialog, select the Include Certificates tab.

2.Click [Add Certificate From File].

3.Either:

§enter a filename and location into the Certificate File text box

OR

§select the Browse button to open a file explorer dialog and navigate to, and select, the desired certificate.

4.If a password is required to use with the certificate, enter it in the Password (optional) text box.

NOTE: When a connection to SharePoint is made, Metalogix Content Matrix will save the password field for any certificates so it can re-establish a connection to that SharePoint instance at a later date. If you are not comfortable with entering the password in the Password (optional) field, you can move the certificate into the user account's "Personal" folder, and use the Add Installed Certificate option instead, provided the user account/password is the same.

When you return to the SharePoint Logon dialog, the selected certificate will display in the Included Certificates list, and it will be included whenever Metalogix Content Matrix is running an action to or from the SharePoint connection.

Important Note About Self-Signed Certificates

For security purposes, Content Matrix always attempts to validate a certificate when connecting to a TLS/SSL site.  Content Matrix cannot validate a self-signed certificate for an on-premises connection however, and if it attempts to do so you will be unable to complete the connection.  To avoid this issue, you must change the value of the key BypassCertificateValidation in the EnvironmentSettings.xml file to True.

Removing Certificates

Any certificates that have previously been added through the two Add Certificates options can also be removed from the list of Included Certificates.

To remove a certificate:

1.In the SharePoint Logon dialog, select the Include Certificates tab.

2.Select the certificate(s) that you want to remove.

3.Click [Remove].