Implement SSPI authentication (#1128)

SSPI is a Windows technology for secure authentication. SSPI and GSSAPI interoperate as clients and servers. Postgres documentation recommends using SSPI on Windows clients and servers and GSSAPI on non-Windows platforms[1]. Changes in this PR: * Support AUTH_REQUIRED_SSPI server request. This is the same as AUTH_REQUIRED_GSS, except it allows negotiation with SSPI clients. * Allow using SSPI on the client. Which library to use can be specified using the `gsslib` connection parameter. * Use SSPI instead of GSSAPI on Windows by default. The latter requires installing Kerberos for Windows and is unlikely to work out of the box. Closes #142 [1] https://www.postgresql.org/docs/current/sspi-auth.html

Author: eltoder

README.rst

@@ -58,11 +58,18 @@ This enables asyncpg to have easy-to-use support for:
 Installation
 ------------
 
-asyncpg is available on PyPI and has no dependencies.
-Use pip to install::
+asyncpg is available on PyPI. When not using GSSAPI/SSPI authentication it
+has no dependencies. Use pip to install::
 
  $ pip install asyncpg
 
+If you need GSSAPI/SSPI authentication, use::
+
+ $ pip install 'asyncpg[gssauth]'
+
+For more details, please `see the documentation
+<https://magicstack.github.io/asyncpg/current/installation.html>`_.
+
 
 Basic Usage
 -----------

asyncpg/connect_utils.py

@@ -57,6 +57,7 @@ def parse(cls, sslmode):
  'server_settings',
  'target_session_attrs',
  'krbsrvname',
+ 'gsslib',
  ])
 
 
@@ -262,7 +263,7 @@ def _dot_postgresql_path(filename) -> typing.Optional[pathlib.Path]:
 def _parse_connect_dsn_and_args(*, dsn, host, port, user,
  password, passfile, database, ssl,
  direct_tls, server_settings,
- target_session_attrs, krbsrvname):
+ target_session_attrs, krbsrvname, gsslib):
  # `auth_hosts` is the version of host information for the purposes
  # of reading the pgpass file.
  auth_hosts = None
@@ -389,6 +390,11 @@ def _parse_connect_dsn_and_args(*, dsn, host, port, user,
  if krbsrvname is None:
  krbsrvname = val
 
+ if 'gsslib' in query:
+ val = query.pop('gsslib')
+ if gsslib is None:
+ gsslib = val
+
  if query:
  if server_settings is None:
  server_settings = query
@@ -659,12 +665,21 @@ def _parse_connect_dsn_and_args(*, dsn, host, port, user,
  if krbsrvname is None:
  krbsrvname = os.getenv('PGKRBSRVNAME')
 
+ if gsslib is None:
+ gsslib = os.getenv('PGGSSLIB')
+ if gsslib is None:
+ gsslib = 'sspi' if _system == 'Windows' else 'gssapi'
+ if gsslib not in {'gssapi', 'sspi'}:
+ raise exceptions.ClientConfigurationError(
+ "gsslib parameter must be either 'gssapi' or 'sspi'"
+ ", got {!r}".format(gsslib))
+
  params = _ConnectionParameters(
  user=user, password=password, database=database, ssl=ssl,
  sslmode=sslmode, direct_tls=direct_tls,
  server_settings=server_settings,
  target_session_attrs=target_session_attrs,
- krbsrvname=krbsrvname)
+ krbsrvname=krbsrvname, gsslib=gsslib)
 
  return addrs, params
 
@@ -675,7 +690,7 @@ def _parse_connect_arguments(*, dsn, host, port, user, password, passfile,
  max_cached_statement_lifetime,
  max_cacheable_statement_size,
  ssl, direct_tls, server_settings,
- target_session_attrs, krbsrvname):
+ target_session_attrs, krbsrvname, gsslib):
  local_vars = locals()
  for var_name in {'max_cacheable_statement_size',
  'max_cached_statement_lifetime',
@@ -705,7 +720,7 @@ def _parse_connect_arguments(*, dsn, host, port, user, password, passfile,
  direct_tls=direct_tls, database=database,
  server_settings=server_settings,
  target_session_attrs=target_session_attrs,
- krbsrvname=krbsrvname)
+ krbsrvname=krbsrvname, gsslib=gsslib)
 
  config = _ClientConfiguration(
  command_timeout=command_timeout,

asyncpg/connection.py

@@ -2008,7 +2008,8 @@ async def connect(dsn=None, *,
  record_class=protocol.Record,
  server_settings=None,
  target_session_attrs=None,
- krbsrvname=None):
+ krbsrvname=None,
+ gsslib=None):
  r"""A coroutine to establish a connection to a PostgreSQL server.
 
  The connection parameters may be specified either as a connection
@@ -2240,6 +2241,10 @@ async def connect(dsn=None, *,
  Kerberos service name to use when authenticating with GSSAPI. This
  must match the server configuration. Defaults to 'postgres'.
 
+ :param str gsslib:
+ GSS library to use for GSSAPI/SSPI authentication. Can be 'gssapi'
+ or 'sspi'. Defaults to 'sspi' on Windows and 'gssapi' otherwise.
+
  :return: A :class:`~asyncpg.connection.Connection` instance.
 
  Example:
@@ -2309,7 +2314,7 @@ async def connect(dsn=None, *,
  Added the *target_session_attrs* parameter.
 
  .. versionchanged:: 0.30.0
- Added the *krbsrvname* parameter.
+ Added the *krbsrvname* and *gsslib* parameters.
 
  .. _SSLContext: https://docs.python.org/3/library/ssl.html#ssl.SSLContext
  .. _create_default_context:
@@ -2354,6 +2359,7 @@ async def connect(dsn=None, *,
  max_cacheable_statement_size=max_cacheable_statement_size,
  target_session_attrs=target_session_attrs,
  krbsrvname=krbsrvname,
+ gsslib=gsslib,
  )
 
 

asyncpg/protocol/coreproto.pxd

@@ -91,7 +91,7 @@ cdef class CoreProtocol:
  object con_params
  # Instance of SCRAMAuthentication
  SCRAMAuthentication scram
- # Instance of gssapi.SecurityContext
+ # Instance of gssapi.SecurityContext or sspilib.SecurityContext
  object gss_ctx
 
  readonly int32_t backend_pid
@@ -138,7 +138,9 @@ cdef class CoreProtocol:
  cdef _auth_password_message_md5(self, bytes salt)
  cdef _auth_password_message_sasl_initial(self, list sasl_auth_methods)
  cdef _auth_password_message_sasl_continue(self, bytes server_response)
- cdef _auth_gss_init(self)
+ cdef _auth_gss_init_gssapi(self)
+ cdef _auth_gss_init_sspi(self, bint negotiate)
+ cdef _auth_gss_get_spn(self)
  cdef _auth_gss_step(self, bytes server_response)
 
  cdef _write(self, buf)

asyncpg/protocol/coreproto.pyx

@@ -38,7 +38,8 @@ cdef class CoreProtocol:
  self.encoding = 'utf-8'
  # type of `scram` is `SCRAMAuthentcation`
  self.scram = None
- # type of `gss_ctx` is `gssapi.SecurityContext`
+ # type of `gss_ctx` is `gssapi.SecurityContext` or
+ # `sspilib.SecurityContext`
  self.gss_ctx = None
 
  self._reset_result()
@@ -635,29 +636,33 @@ cdef class CoreProtocol:
  )
  self.scram = None
 
- elif status == AUTH_REQUIRED_GSS:
- self._auth_gss_init()
- self.auth_msg = self._auth_gss_step(None)
+ elif status in (AUTH_REQUIRED_GSS, AUTH_REQUIRED_SSPI):
+ # AUTH_REQUIRED_SSPI is the same as AUTH_REQUIRED_GSS, except that
+ # it uses protocol negotiation with SSPI clients. Both methods use
+ # AUTH_REQUIRED_GSS_CONTINUE for subsequent authentication steps.
+ if self.gss_ctx is not None:
+ self.result_type = RESULT_FAILED
+ self.result = apg_exc.InterfaceError(
+ 'duplicate GSSAPI/SSPI authentication request')
+ else:
+ if self.con_params.gsslib == 'gssapi':
+ self._auth_gss_init_gssapi()
+ else:
+ self._auth_gss_init_sspi(status == AUTH_REQUIRED_SSPI)
+ self.auth_msg = self._auth_gss_step(None)
 
  elif status == AUTH_REQUIRED_GSS_CONTINUE:
  server_response = self.buffer.consume_message()
  self.auth_msg = self._auth_gss_step(server_response)
 
- elif status in (AUTH_REQUIRED_KERBEROS, AUTH_REQUIRED_SCMCRED,
- AUTH_REQUIRED_SSPI):
- self.result_type = RESULT_FAILED
- self.result = apg_exc.InterfaceError(
- 'unsupported authentication method requested by the '
- 'server: {!r}'.format(AUTH_METHOD_NAME[status]))
-
  else:
  self.result_type = RESULT_FAILED
  self.result = apg_exc.InterfaceError(
  'unsupported authentication method requested by the '
- 'server: {}'.format(status))
+ 'server: {!r}'.format(AUTH_METHOD_NAME.get(status, status)))
 
- if status not in [AUTH_SASL_CONTINUE, AUTH_SASL_FINAL,
- AUTH_REQUIRED_GSS_CONTINUE]:
+ if status not in (AUTH_SASL_CONTINUE, AUTH_SASL_FINAL,
+ AUTH_REQUIRED_GSS_CONTINUE):
  self.buffer.discard_message()
 
  cdef _auth_password_message_cleartext(self):
@@ -714,25 +719,43 @@ cdef class CoreProtocol:
 
  return msg
 
- cdef _auth_gss_init(self):
+ cdef _auth_gss_init_gssapi(self):
  try:
  import gssapi
  except ModuleNotFoundError:
- raise RuntimeError(
- 'gssapi module not found; please install asyncpg[gssapi] to '
- 'use asyncpg with Kerberos or GSSAPI authentication'
+ raise apg_exc.InterfaceError(
+ 'gssapi module not found; please install asyncpg[gssauth] to '
+ 'use asyncpg with Kerberos/GSSAPI/SSPI authentication'
  ) from None
 
+ self.gss_ctx = gssapi.SecurityContext(
+ name=gssapi.Name(self._auth_gss_get_spn()), usage='initiate')
+
+ cdef _auth_gss_init_sspi(self, bint negotiate):
+ try:
+ import sspilib
+ except ModuleNotFoundError:
+ raise apg_exc.InterfaceError(
+ 'sspilib module not found; please install asyncpg[gssauth] to '
+ 'use asyncpg with Kerberos/GSSAPI/SSPI authentication'
+ ) from None
+
+ self.gss_ctx = sspilib.ClientSecurityContext(
+ target_name=self._auth_gss_get_spn(),
+ credential=sspilib.UserCredential(
+ protocol='Negotiate' if negotiate else 'Kerberos'))
+
+ cdef _auth_gss_get_spn(self):
  service_name = self.con_params.krbsrvname or 'postgres'
  # find the canonical name of the server host
  if isinstance(self.address, str):
- raise RuntimeError('GSSAPI authentication is only supported for '
- 'TCP/IP connections')
+ raise apg_exc.InternalClientError(
+ 'GSSAPI/SSPI authentication is only supported for TCP/IP '
+ 'connections')
 
  host = self.address[0]
  host_cname = socket.gethostbyname_ex(host)[0]
- gss_name = gssapi.Name(f'{service_name}/{host_cname}')
- self.gss_ctx = gssapi.SecurityContext(name=gss_name, usage='initiate')
+ return f'{service_name}/{host_cname}'
 
  cdef _auth_gss_step(self, bytes server_response):
  cdef:

docs/installation.rst

@@ -4,20 +4,35 @@
 Installation
 ============
 
-**asyncpg** has no external dependencies and the recommended way to
-install it is to use **pip**:
+**asyncpg** has no external dependencies when not using GSSAPI/SSPI
+authentication. The recommended way to install it is to use **pip**:
 
 .. code-block:: bash
 
  $ pip install asyncpg
 
+If you need GSSAPI/SSPI authentication, the recommended way is to use
 
-.. note::
+.. code-block:: bash
+
+ $ pip install 'asyncpg[gssauth]'
+
+This installs SSPI support on Windows and GSSAPI support on non-Windows
+platforms. SSPI and GSSAPI interoperate as clients and servers: an SSPI
+client can authenticate to a GSSAPI server and vice versa.
+
+On Linux installing GSSAPI requires a working C compiler and Kerberos 5
+development files. The latter can be obtained by installing **libkrb5-dev**
+package on Debian/Ubuntu or **krb5-devel** on RHEL/Fedora. (This is needed
+because PyPI does not have Linux wheels for **gssapi**. See `here for the
+details <https://github.com/pythongssapi/python-gssapi/issues/200#issuecomment-1032934269>`_.)
+
+It is also possible to use GSSAPI on Windows:
 
-  It is recommended to use **pip** version **8.1** or later to take
-  advantage of the precompiled wheel packages. Older versions of pip
-  will ignore the wheel packages and install asyncpg from the source
- package. In that case a working C compiler is required.
+ * `pip install gssapi`
+ * Install `Kerberos for Windows <https://web.mit.edu/kerberos/dist/>`_.
+ * Set the ``gsslib`` parameter or the ``PGGSSLIB`` environment variable to
+  `gssapi` when connecting.
 
 
 Building from source

pyproject.toml

@@ -35,15 +35,17 @@ dependencies = [
 github = "https://github.com/MagicStack/asyncpg"
 
 [project.optional-dependencies]
-gssapi = [
- 'gssapi',
+gssauth = [
+ 'gssapi; platform_system != "Windows"',
+ 'sspilib; platform_system == "Windows"',
 ]
 test = [
  'flake8~=6.1',
  'flake8-pyi~=24.1.0',
  'uvloop>=0.15.3; platform_system != "Windows" and python_version < "3.12.0"',
  'gssapi; platform_system == "Linux"',
  'k5test; platform_system == "Linux"',
+ 'sspilib; platform_system == "Windows"',
  'mypy~=1.8.0',
 ]
 docs = [