Connecting QuerySurge to a Microsoft Fabric Mirrored Database Using Managed Identity – Customer Support

Overview

Microsoft Fabric Mirroring replicates transactional data into OneLake and exposes the replicated tables through a read-only SQL analytics endpoint.

QuerySurge can connect to this endpoint using the Microsoft JDBC Driver for SQL Server. Microsoft Entra Managed Identity authentication allows the QuerySurge Agent to authenticate without storing a username, password, client secret, or certificate in QuerySurge.

This article explains how to connect QuerySurge to a Microsoft Fabric Mirrored Database using either a system-assigned or user-assigned managed identity.

Managed Identity Options

Microsoft Entra supports two types of managed identities:

Identity type	Description
System-assigned	Created for and associated with a single Azure resource. QuerySurge automatically uses the identity assigned to the Azure resource hosting the Agent.
User-assigned	Created as a separate Azure resource and attached to one or more Azure compute resources. The identity’s Client ID must be included in the QuerySurge connection URL.

A system-assigned identity is tied to the lifecycle of its Azure resource. A user-assigned identity has an independent lifecycle and can be shared by multiple supported Azure resources.

For additional information, see Microsoft’s Managed identities for Azure resources overview.

Prerequisites

1. Host the QuerySurge Agent on a Supported Azure Resource

The QuerySurge Agent executing the Fabric connection must run on an Azure resource that supports Microsoft Entra Managed Identity, such as an Azure Virtual Machine.

Note: The examples in this article use an Azure Virtual Machine. Other supported managed-identity hosts may require different identity configuration steps. The QuerySurge Agent executing the Connection must be able to access the managed-identity token service provided by its host environment.

The QuerySurge Application Server does not need to run on the same Azure resource. However, every Agent assigned to this connection must have access to the appropriate managed identity and the required JDBC authentication libraries.

2. Configure the Managed Identity

For a system-assigned managed identity, open the Azure resource hosting the QuerySurge Agent and enable:

Identity
→ System assigned
→ Status: On

For a user-assigned managed identity:

Create the managed identity in Azure.
Attach the identity to the Azure resource hosting the QuerySurge Agent.
Record the identity’s Client ID.

The Client ID, rather than the Object or Principal ID, is used in the QuerySurge JDBC connection URL. Microsoft documents the Azure VM configuration procedures for both identity types.

For additional instructions, see Microsoft’s Configure managed identities on Azure virtual machines.

3. Enable Managed Identity Access in Fabric

A Fabric administrator must enable application identity access:

Sign in to Microsoft Fabric.
Select Settings → Admin portal.
Open Tenant settings → Developer settings.
Expand Service principals can use Fabric APIs.
Enable the setting.

Access can be restricted to a security group instead of being enabled for the entire organization.

Managed identities are represented in Microsoft Entra ID as service principals, and Fabric requires this tenant setting for service-principal access through SQL connection strings.

4. Grant the Managed Identity Access to Fabric

Open the Fabric workspace containing the mirrored database and select:

Manage access
→ Add people or groups

Search for the system-assigned or user-assigned managed identity and assign it the Viewer role.

For more restrictive access, grant the identity Read access only to the required SQL analytics endpoint and apply any necessary SQL permissions.

Any Fabric workspace role permits connection to the SQL analytics endpoint. The Viewer role is the recommended read-only workspace role for QuerySurge validation.

5. Install the Microsoft SQL Server JDBC Driver and Authentication Libraries

A Microsoft SQL Server JDBC driver is bundled with QuerySurge and can be installed using the QuerySurge Installer. Ensure the driver is installed on every QuerySurge Agent that will use this Connection.

Microsoft Entra Managed Identity authentication also requires the Microsoft Azure Identity library and its dependencies.

Note: The required Azure Identity version depends on the Microsoft SQL Server JDBC driver version installed on the QuerySurge Agent. Refer to Microsoft’s JDBC Driver feature dependencies documentation to identify the appropriate version.

Microsoft SQL Server JDBC Driver version 12.4.1.jre11, which was used to validate this configuration, requires Azure Identity version 1.9.0. The Azure Identity library and its dependencies can be downloaded using Maven or an online Maven dependency tool by entering the following dependency:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.9.0</version>
</dependency>

Ensure that the download includes all transitive dependencies. The downloaded package will include Azure Identity, MSAL4J, and the additional supporting libraries required for Managed Identity authentication. A separate MSAL4J dependency entry is not required.

Deploy all downloaded JAR files to every QuerySurge Agent that may execute this Connection, and then restart the Agents.

Note: If you are using the SQL Server JDBC driver bundled with QuerySurge, do not deploy an additional mssql-jdbc JAR from the dependency package. Multiple versions of the SQL Server JDBC driver should not be installed on the same QuerySurge Agent.

Setting Up the Connection in QuerySurge

Before creating the connection, gather the following information:

Fabric SQL analytics endpoint
Mirrored database name
Managed identity type
User-assigned managed identity Client ID, when applicable

Locate the Fabric SQL Analytics Endpoint

To locate the Fabric connection information, open the mirrored database and confirm that SQL analytics endpoint is selected in the upper-right dropdown. Click Copy SQL connection string in the lower-left corner and record the server endpoint.

The server endpoint will resemble:

xxxxxxxxxx.datawarehouse.fabric.microsoft.com

Record the exact database name displayed in the Fabric Explorer.

Launch the Connection Wizard

Log into QuerySurge as an Admin user.
In the Administration view, select Connections, and then click Add to launch the Connection Wizard. Click Next.
Provide a name for the connection and select All Other JDBC Connections (Connection Extensibility) as the Data Source. Click Next.
Enter the following Driver Class:

com.microsoft.sqlserver.jdbc.SQLServerDriver

Leave the Username and Password fields blank.
Enter the connection URL appropriate for the managed identity type.

System-Assigned Managed Identity

jdbc:sqlserver://<fabric_sql_endpoint>:1433;databaseName=<database_name>;authentication=ActiveDirectoryManagedIdentity;encrypt=true;trustServerCertificate=false;pdw=true;

When no managed identity Client ID is supplied, the Microsoft JDBC driver uses the system-assigned identity of the Azure resource hosting the QuerySurge Agent.

Replace <fabric_sql_endpoint> and <database_name> with the values collected from Microsoft Fabric.

Note: The QuerySurge-specific pdw=true; property enables compatibility handling for Fabric’s distributed SQL architecture.

If you have a Test Query, feel free to enter it to help verify that your Connection parameters are correct. It should be a standard query that returns a small amount of information - one row is enough.

User-Assigned Managed Identity

jdbc:sqlserver://<fabric_sql_endpoint>:1433;databaseName=<database_name>;authentication=ActiveDirectoryManagedIdentity;msiClientId=<managed_identity_client_id>;encrypt=true;trustServerCertificate=false;pdw=true;

Replace <fabric_sql_endpoint> and <database_name> with the values collected from Microsoft Fabric.

Note: The QuerySurge-specific pdw=true; property enables compatibility handling for Fabric’s distributed SQL architecture.

If you entered a Test Query, you can use the Test Connection button to test whether your Connection is set up properly:

A successful test confirms that the QuerySurge Agent can authenticate to the Fabric SQL analytics endpoint and retrieve database metadata.

Save the Connection.

The Microsoft Fabric Mirrored Database connection is now available for use in QueryPairs.

Mirroring Consideration

Fabric Mirroring continuously synchronizes source data with the mirrored tables in OneLake. When validating an active transactional source against its Fabric mirror, temporary differences may occur while recent source changes are being replicated.

For stable comparisons, consider using a common cutoff timestamp, filtering by a shared watermark, or running tests after the mirrored data has synchronized.

Troubleshooting

Managed Identity authentication is not available

This error normally indicates that:

The QuerySurge Agent is not running on a supported managed-identity host.
The managed identity is not enabled or attached to the Agent host.
Required Azure Identity libraries are missing.
The Agent cannot access the host’s managed-identity token service.

Identity not found

For a user-assigned identity, confirm that:

The identity is attached to the Azure resource hosting the Agent.
msiClientId contains the identity’s Client ID.
The Object ID or Principal ID was not used by mistake.

Login or authorization failure

If token acquisition succeeds but the SQL connection is denied, verify that the managed identity has been granted access to the Fabric workspace or SQL analytics endpoint.

The connection works on one Agent but not another

Every Agent that may execute the connection must:

Run on a supported managed-identity host.
Have access to the required identity.
Have the JDBC driver and Azure Identity dependencies installed.

Articles in this section