Support `ClientCertificate` keyword in Connection String

[Aniruddh25]

Is your feature request related to a problem? Please describe.

SqlClient does not currently support the ClientCertificate keyword in a connection string. This prevents applications from specifying a client certificate directly in the connection configuration for scenarios that require certificate-based authentication or mutual TLS.

Because this setting cannot be expressed in a standard connection string, developers are forced to use custom configuration workarounds outside the SqlClient connection model, which is less portable, less discoverable, and harder to maintain.

Describe the solution you'd like

Add support for the ClientCertificate keyword in the SqlClient connection string so that a client certificate can be configured directly as part of the connection string.

The expected behavior should include:

• accepting ClientCertificate in the connection string
• validating and parsing the value consistently with other SqlClient connection-string keywords
• passing the configured certificate through the connection flow to the underlying authentication logic
• documenting the option in the SqlClient connection-string reference and examples

This would make certificate-based authentication easier to configure and align SqlClient with standard connection-string-based configuration patterns.

Describe alternatives you've considered

• Relying on System.Data.Odbc instead of SqlClient.

Additional context

Support for ClientCertificate would be valuable in secure deployment scenarios that rely on certificate-based authentication, mutual TLS, or centralized certificate management. Enabling this option in the connection string would improve usability, consistency, and portability for developers using SqlClient in real-world secure environments.

[github-actions]

🔍 Triage Summary

Check	Result
Issue type	Feature
Environment	N/A — feature request, no environment details required
Area	Area\Managed SNI
Duplicates	None found
Regression	Not indicated

Analysis

This is a feature request to add a ClientCertificate connection string keyword to SqlClient, enabling certificate-based client authentication (mutual TLS) directly via the connection string. Currently, there is no way to specify a client certificate through the standard SqlClient connection model, forcing developers to use out-of-band workarounds. The feature would affect SqlConnectionStringBuilder, the connection string parser, and the underlying SNI/TLS handshake layer. Severity: P2 — meaningful usability gap for secure deployment scenarios, but workarounds exist.

Next Steps

• Assess feasibility of accepting a ClientCertificate keyword in SqlConnectionStringBuilder and the connection string parser (SqlConnectionString.cs).
• Determine the expected value format (e.g., certificate thumbprint, subject name, PEM path, or store path) and document clearly in the connection string reference.
• Wire the parsed certificate value through the connection flow to the managed SNI TLS layer (ManagedSni/) and the native SNI path on Windows.
• Add unit tests for parsing and validation, plus integration tests for an mTLS handshake.
• Update doc/ with a new connection string keyword entry and a usage sample under doc/samples/.
• Assign to Copilot coding agent to investigate the implementation path, starting with SqlConnectionStringBuilder, SqlConnectionString.cs, and ManagedSni/SniTcpHandle.cs (or equivalent TLS configuration point).

Note: This triage summary is auto-generated by an AI agent. The analysis and suggestions above have not been verified by a human maintainer. Please treat as preliminary guidance only.

Generated by SqlClient Issue Auto-Triage for issue #4551 · 30.3 AIC · ⌖ 6.42 AIC · ⊞ 8.6K · ◷

[cheenamalhotra]

Discussed internally, this feature is supported by ODBC and JDBC drivers, would be a good addition to the SqlClient driver as well.

[JustinMDotNet]

Status update on this request, plus some findings that may be useful to anyone else looking at it.

PR #4556 implements this (still draft). It adds three connection-string keywords — Client Certificate / ClientCertificate, Client Key / ClientKey, and Client Key Password / ClientKeyPassword — deliberately mirroring the JDBC driver's property names rather than the single Certificate keyword prototyped in CTAIP, so the .NET and Java surfaces stay aligned. Authentication completes during the TLS handshake, so no new SqlAuthenticationMethod value is introduced. Both managed and native SNI are supported, on all target frameworks.

Two findings worth recording here:

1. Native SNI needed real work. The first implementation passed the certificate via SNIAuthProviderInfo.pCertContext. In the SNI sources corresponding to the package version restored in my build (6.0.2), that field is never read as an input — Ssl::AcquireCredentialsForClient gates only on pwszCertId, and pCertContext is an output parameter. The certificate is instead resolved by identifier (searching LocalMachine\MY, then CurrentUser\MY), falling back to pfnCertificateCallback when both miss. Separately, the driver always requested the shared Schannel credential cache, which makes SNI skip credential acquisition entirely. Both are fixed in the PR, and the simulated-server test matrix now runs over native SNI as well — it was the absence of that coverage that let the defect hide.

2. How far this can be validated outside sp_execute_external_script. I stood up SQL Server 2022 on Ubuntu 22.04 and ran a client built from the branch on that host. The driver loads the real launchpad-minted satellite credentials (/var/opt/mssql-extensibility/data/<guid>/sqlsatellitecert.pem and sqlsatellitekey.pem), presents the certificate, and the server responds Login failed for user 'Microsoft Corporation' — the O of that certificate's subject. Since LOGIN7 carries an empty user name, the server cannot be echoing anything the client supplied, so SQL Server is extracting a candidate identity from the certificate.

The login is still refused, and that appears to be by design rather than a driver gap. An ordinary certificate-mapped login (CREATE LOGIN ... FROM CERTIFICATE) is reported by name and then rejected with 18456 ... Reason: Infrastructure error occurred, which matches the CREATE LOGIN documentation stating such logins cannot be used to connect. Installing the extensibility framework and enabling external scripts did not change that result. The supported trust anchor appears to be the mapping the launchpad registers per external-script session, so a genuinely authenticated end-to-end session still needs a live satellite process — which I have not yet produced, because launchpad on my 2022 install could not load a Python launcher. That is a setup issue on my side, not a demonstrated product limitation.

So: driver-side certificate presentation is verified both against a simulated TLS server that asserts the observed thumbprint and against a real SQL Server that parses the certificate. The part still outstanding is the server's authorization decision inside a live SPEES session.

If anyone on the SQL Server or SNI side has a working loopback environment, validating against it would close the last gap. Details, evidence, and an open question about accepting the ODBC-style file: path prefix are in the PR.