Authentication

ArpeMSSQL supports the same SQL Server connection modes as FastBCP:

Mode	How to request it
SQL login	username + password (structured options or User ID=/Password= in a connection string)
Trusted / integrated (Windows only)	adbc.arpemssql.trusted=true (or =sspi), or Integrated Security=SSPI / Trusted_Connection=yes in a connection string
Full connection string	adbc.arpemssql.connection_string=... — the escape hatch

ArpeMSSQL is the driver (native TDS, no client library underneath), so the "full connection string" is parsed by ArpeMSSQL, not passed through to another driver. It can only honor modes ArpeMSSQL implements; anything else fails fast (see below).

For Microsoft Entra ID (Azure SQL, Microsoft Fabric), see Connection → Azure SQL, Microsoft Fabric & Entra ID.

Option / keyword reference

Structured ADBC options:

• adbc.arpemssql.trusted — true/sspi/yes/1 → integrated; false/no/0 → SQL.
• adbc.arpemssql.auth_type — sql/SqlPassword | integrated/sspi/trusted | ActiveDirectoryDefault/default (Entra ID default credential chain, see Connection). The other Entra ID / certificate families are recognized and rejected with NOT_IMPLEMENTED.
• adbc.arpemssql.krb5.spn — optional service principal name (SPN) override for integrated auth on Windows. Connection-string keyword: Service Principal Name (also ServicePrincipalName, service_principal_name). See SPN.

Authenticator=sspi/winsspi (also krb5) is a pyodbc-style alias for integrated auth; Authenticator=sql forces SQL login.

Connection-string auth-mode keywords (case-insensitive; aliases of the same auth-mode field, so specifying two is a duplicate-key error):

• Integrated Security — SSPI/true/yes/1 → integrated; false/no/0 → SQL.
• Trusted_Connection (also Trusted Connection) — SSPI/yes/true/1 → integrated; no/false/0 → SQL.
• Authentication — SqlPassword (or Sql Password) → SQL. Any ActiveDirectory* value is recognized and rejected with a clear NOT_IMPLEMENTED error (use Integrated Security=SSPI for Kerberos on Windows).

Mutual exclusion: integrated/trusted auth cannot be combined with a SQL username/password. Doing so fails with INVALID_ARGUMENT before any socket is opened.

Platform support

Trusted / integrated authentication is available on Windows only:

• Windows (x64) — SSPI with Kerberos. The driver authenticates as the logged-in Windows user; no username, password or ticket setup is needed. The server's identity is always verified (mutual authentication), so the SQL Server SPN must be registered and the server reached by its fully qualified name.
• Linux (x64) — not available. Requesting integrated auth fails immediately with a "Trusted/integrated authentication is unavailable" error. Use a SQL login or Microsoft Entra ID instead.

Large Kerberos tokens (users in many AD groups) are handled: the login succeeds regardless of token size.

Service principal name (SPN)

With Kerberos, the SPN the driver requests must match the one registered in Active Directory for the SQL Server service account. By default the driver derives it as MSSQLSvc/<host>:<port>:

• The host is used verbatim (no DNS rewrite): connect by the FQDN the SPN is registered for, not a short name, alias or IP address.
• For a named instance (host\INSTANCE, see Named instances) the port is the one resolved from the SQL Server Browser — the dynamic port SQL Server registers at startup, not 1433. The instance name never appears in the SPN.

If the registered SPN differs (for example a load-balancer or alias name), set adbc.arpemssql.krb5.spn (or Service Principal Name= in a connection string) to the exact SPN. The raw SSPI error is surfaced to help diagnose MSSQLSvc/... mismatches.

Checking the result

On a domain-joined Windows host, connect with Server=<FQDN>;Database=<db>;Integrated Security=SSPI; (no User ID/Password), then:

• SELECT SUSER_SNAME() returns your Windows domain account.
• SELECT auth_scheme FROM sys.dm_exec_connections WHERE session_id=@@SPID reports KERBEROS.

TLS

ArpeMSSQL negotiates encryption in the TDS PRELOGIN exchange (TDS 7.4), then runs the TLS handshake inside TDS packets. TDS 8 "strict" encryption, where TLS starts before any TDS traffic, is not supported. The options are in Connection → Encryption / TLS.

What gets encrypted

Setting	Server encryption setting	Result
encrypt=false (default)	off	Login-only TLS: the login packet (with the password) is encrypted, then the session continues in clear. The certificate is not checked.
encrypt=false	forced (Force Encryption)	Full TLS, and the certificate is checked (unless trust_server_cert=true).
encrypt=true	off or forced	Full TLS with certificate and host name checks (unless trust_server_cert=true). If the server refuses encryption, the connection fails.
Entra ID (federated) login	any	Always full TLS.

If the server supports no encryption at all, a SQL login is refused rather than sent in clear, unless allow_cleartext_login=true. A server that forces encryption with a self-signed certificate therefore needs TrustServerCertificate=true even when you did not ask for encrypt.

Protocol versions

TLS 1.2 is the minimum and TLS 1.3 is used when the server offers it. The minimum is fixed: there is no option to allow TLS 1.0 / 1.1, so SQL Server versions that cannot do TLS 1.2 cannot be reached with encryption.

Independent of the host's TLS stack

Because the driver brings its own OpenSSL, the TLS versions it can use do not depend on the host. A server that only accepts TLS 1.3 works even where the host's own TLS stack has no TLS 1.3: for example Windows Server 2019 and older (Schannel), or a Linux host whose system OpenSSL is 1.0.x. The limit on Linux is the C library: the released binary needs glibc 2.28 or later (RHEL 8, Debian 10, Ubuntu 20.04 or newer), so RHEL 7 is not supported.

Where trusted certificates come from

ArpeMSSQL carries its own copy of OpenSSL 3, linked into the library (the Linux release is built with OpenSSL 3.6.4). It never uses the operating system's TLS stack or certificate store. There is no option to give a CA file: the server certificate is checked against OpenSSL's default locations, in this order:

1. the SSL_CERT_FILE (a PEM bundle) and SSL_CERT_DIR (a hashed directory) environment variables;
2. on Linux, /etc/ssl/cert.pem and /etc/ssl/certs/.

Client OS	Without SSL_CERT_FILE
Debian, Ubuntu	Works: /etc/ssl/certs holds the system CAs.
RHEL, Rocky, AlmaLinux 8 and newer	Fails with "unable to get local issuer certificate": the CA bundle lives under /etc/pki. Set SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt.
Windows	Fails: the Windows certificate store is not read. Set SSL_CERT_FILE to a PEM file holding the CA that signed the server certificate.

trust_server_cert=true skips the check entirely; keep it for development servers.

Host name check and SNI

With the certificate check on, the host name from Server (without the port or instance name) must match the certificate: a DNS name against its DNS SANs (or its CN when it has none), an IP address against its IP SANs. A wildcard must be the whole first label (*.example.com). There is no HostNameInCertificate option. SNI is sent for DNS names, not for IP addresses.

Client certificates

Not supported: the driver presents no client certificate.

OpenSSL configuration

Like any OpenSSL 3 program, the driver reads an OpenSSL configuration file at the first TLS connection: the file named by OPENSSL_CONF, else /etc/ssl/openssl.cnf on Linux. Settings there, such as cipher lists or the security level, apply. The driver's TLS 1.2 minimum always wins. RHEL's system crypto-policies live under /etc/pki/tls/openssl.cnf, so they apply only if that file is the one loaded (for example with OPENSSL_CONF=/etc/pki/tls/openssl.cnf).

TLS errors are listed under Troubleshooting → TLS / certificates.