SharePoint Online Connector Configuration (6.1.1)

This article describes the steps needed for configuring the SharePoint Online Connector (SPOC) after the installation has succeeded.

1. Configure Primary Account for SPOC (Web Interface Access)

The Administrator account must first be created before the SharePoint Online Connector can be configured.

1. Navigate to https://[your-server]:[port number]

   1. Verify the interface loads correctly

2. Set up the Administrator user for SPOC

   1. The Administrator password is set on the first login

   2. Click on the Login drop-down button

   3. Choose Login Locally

   4. Enter Administrator for the Email field

   5. Enter a password of your choosing. (Note: The password must be at least 12 characters)

   6. Click Login

The Administrator account can be used to provision new Users as well as manage any aspect of the connector. This account information should be kept secure.

2. Configure Connection to Gimmal Records

This section configures the communication between the SharePoint Online Connector and Gimmal Records.

1. Access Web Interface: Navigate to https://your-server:8083 (Note: the port will depend on what was chosen during installation)

2. Connection Management: Go to Connection Configuration > Gimmal Records

3. Enter Configuration:

   • URL: URL for the Gimmal Records application

   • Username: Gimmal Records connector service account username

   • Password: Gimmal Records connector service account password

3. Configure Microsoft Graph API Connection in the SharePoint Online Connector

This section configures the connection to the Microsoft Graph API used to authenticate to SharePoint.

1. Click on ‘Microsoft Graph API’ in the left panel

2. Enter the Tenant ID and Client ID from the App Registration step:

   • Tenant ID: Your Azure AD Directory (tenant) ID (A)

   • Client ID: Your Azure AD Application (client) ID (B)
     

     

3. Click the ‘Save’ button (C)

4. An Upload Certificate button will appear. Click it to upload the .PFX version of the certificate file used during App Registration.

   1. Upload the .PFX certificate file created during App Registration using the ‘Select File’ button (A)

   2. Enter the certificate password (B)

      

   3. Click the ‘Upload’ button to complete the certificate upload (C). If you receive an error stating the password is invalid, refer to the troubleshooting section at the bottom of this document.

   4. Verify the certificate thumbprint and expiration dates match the original (D)

5. Test Connection: Click “Test Connection” to validate authentication (E)

6. Save Configuration: Click ‘Update’ to save the settings (F)

Enabling Label-based Record Locking

SPOC v6.1.1 includes support for Label-based record locking using a Purview retention label.  However, fully enabling this functionality requires additional configurations. 

Enable Label-based Record Locking

1. Stop all Gimmal Records-related Windows services when updating this configuration

2. Use SQL Server Management Studio (SSMS) to connect to the SPOC Database

3. Log in to the database and open a new query window

4. Execute the following query against the SPOC Database:

 -- Enable retention labels for record locking (set flag to true)
MERGE INTO KeyValues AS target
USING (SELECT '{0A0B7A21-97C9-4BEF-B0F0-AB226E3E9536}' AS [Key]) AS source
ON target.[Key] = source.[Key]
WHEN MATCHED THEN
    UPDATE SET [Value] = 'true'
WHEN NOT MATCHED THEN
    INSERT ([Key], [Value]) VALUES ('{0A0B7A21-97C9-4BEF-B0F0-AB226E3E9536}', 'true'); 

5. Exit SSMS

Configure the Purview Label in SPOC

1. Log in to the SPOC Administrative Web

2. Go to Manage > Job Configuration

3. Edit the Job Details - Retention, if needed

4. On the Job Details page, enter the name of the Purview Label to use, then click Save
   

   

Troubleshooting

Common Installation Issues

SSL Certificate Errors:

1. Ensure the certificate is properly bound to the IIS site

2. Verify that the certificate is not expired and includes the server name

3. Check certificate chain and root CA trust

Service Account Permissions

1. Verify the service account has the ‘Log on as a Service’ right

2. Ensure the service account has database permissions

3. Check the IIS application pool identity permissions

Database Connection Issues

1. Test SQL Server connectivity from the server

2. Verify connection string format and credentials

3. Check SQL Server authentication mode (Windows/Mixed)

4. Ensure the database exists and is properly configured

5. Ensure the service account has database permissions

Azure AD Authentication Failures

1. Verify Tenant ID and Client ID are correct

2. Check that the certificate is properly uploaded and has not expired

3. Ensure Azure AD app has required Microsoft Graph permissions

Invalid Password Error When Uploading Certificate

An "incorrect password" error when importing an RSA or PFX (.pfx/.p12) certificate is often caused by encryption algorithm incompatibility with Windows, special characters in the password, or incorrect cipher suites used during file generation. [1, 2, 3]
Common Causes & Fixes

· Windows Encryption Mismatch: Older versions of Windows or legacy Java truststores sometimes cannot read PFX files encrypted with modern algorithms (like AES-256).

· Fix: Re-export the PFX file using a legacy cipher like 3DES. If using OpenSSL, run the following command:
openssl pkcs12 -export -in cert.crt -inkey cert.key -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -out new.pfx [1, 2, 3]

· Special Characters in Password: PowerShell and OpenSSL allow password characters (like !, $, &, or backticks) that can break the string when parsed by certain Web GUIs or Windows certificate stores.

·         Fix: Generate a new PFX file using an alphanumeric-only password. [1, 2, 3]

 It looks like MS's crypto on Server 2016 has issues with special characters in the password - it may be better to try a password without them.

2. More importantly, if the certs were created on a newer system, it may have used a newer algorithm that is not supported by Server 2016 https://learn.microsoft.com/en-us/answers/questions/1054881/windows-server-2016-2012r2-how-to-add-support-for - They may was to try running the creation script on the Server 2016 server and not copy it for importation from a newer system (Windows 11 or Server 2022+).

Log File Locations

• Application Logs: C:\Program Files\Gimmal Records\Logs

• Service Logs: Windows Event Log > Application

• IIS Logs: C:\inetpub\logs\LogFiles

• Installation Logs: MSI log files created during installation