feat(mssql): use integrated auth when no user or password supplied (#…

…8668) Co-authored-by: Phillip Cloud <[email protected]> Co-authored-by: Jim Crist-Harif <[email protected]>
ibis-project · Mar 17, 2024 · 0a78414 · 0a78414
1 parent 6c00579
commit 0a78414
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 0 deletions.
diff --git a/docs/backends/mssql.qmd b/docs/backends/mssql.qmd
@@ -71,14 +71,32 @@ con = ibis.mssql.connect()  # <1>
 
 ### `ibis.mssql.connect`
 
+::: {.panel-tabset}
+
+## Windows
+
+```python
+con = ibis.mssql.connect(
+    user="username",
+    password="password",
+    host="hostname",
+    driver="SQL Server",
+)
+```
+
+## OSX / Linux
+
 ```python
 con = ibis.mssql.connect(
     user="username",
     password="password",
     host="hostname",
+    driver="FreeTDS",  # if you are using unixODBC
 )
 ```
 
+:::
+
 ::: {.callout-note}
 `ibis.mssql.connect` is a thin wrapper around [`ibis.backends.mssql.Backend.do_connect`](#ibis.backends.mssql.Backend.do_connect).
 :::
@@ -102,6 +120,19 @@ passing a properly-formatted MSSQL connection URL to `ibis.connect`:
 con = ibis.connect(f"mssql://{user}:{password}@{host}:{port}")
 ```
 
+### Using Integrated Authentication
+
+Integrated Authentication allows users to log in via NTLM or Kerberos.
+To make use of integrated authentication, use `ibis.mssql.connect` as documented
+above, but do not specify values for `user` or `password`. The PyODBC driver
+will then default to Integrated Authentication.
+
+Some environments may require you to set additional keywords to connect.
+Additional information is available at the following pages:
+
+- https://learn.microsoft.com/en-us/aspnet/web-api/overview/security/integrated-windows-authentication
+- https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/using-integrated-authentication
+
 ```{python}
 #| echo: false
 BACKEND = "MSSQL"

diff --git a/ibis/backends/mssql/__init__.py b/ibis/backends/mssql/__init__.py
@@ -76,6 +76,43 @@ def do_connect(
         driver: str | None = None,
         **kwargs: Any,
     ) -> None:
+        """Connect to MSSQL database.
+
+        Parameters
+        ----------
+        host
+            Address of MSSQL server to connect to.
+        user
+            Username.  Leave blank to use Integrated Authentication.
+        password
+            Password.  Leave blank to use Integrated Authentication.
+        port
+            Port of MSSQL server to connect to.
+        database
+            The MSSQL database to connect to.
+        driver
+            ODBC Driver to use.
+
+            On Mac and Linux this is usually 'FreeTDS'.
+
+            On Windows, it is usually one of:
+
+            - ODBC Driver 11 for SQL Server
+            - ODBC Driver 13 for SQL Server (for both 13 and 13.1)
+            - ODBC Driver 17 for SQL Server
+            - ODBC Driver 18 for SQL Server
+
+            See https://learn.microsoft.com/en-us/sql/connect/odbc/windows/system-requirements-installation-and-driver-files
+        kwargs
+            Additional keyword arguments to pass to PyODBC.
+        """
+
+        # If no user/password given, assume Windows Integrated Authentication
+        # and set "Trusted_Connection" accordingly
+        # see: https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/using-integrated-authentication
+        if user is None and password is None:
+            kwargs.setdefault("Trusted_Connection", "yes")
+
         con = pyodbc.connect(
             user=user,
             server=host,