ADR 024: mTLS for 2FA (#1025)

* ADR 024: mTLS for 2FA

This PR enables using a client certificate (also known as mutual TLS) for
2-factor-authentication.

Signed-off-by: Rouven Bauer <[email protected]>
Co-authored-by: Steve Cathcart <[email protected]>

Author: robsdedude

docs/source/api.rst

@@ -403,6 +403,7 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`trust-ref`
 + :ref:`ssl-context-ref`
 + :ref:`trusted-certificates-ref`
++ :ref:`client-certificate-ref`
 + :ref:`user-agent-ref`
 + :ref:`driver-notifications-min-severity-ref`
 + :ref:`driver-notifications-disabled-categories-ref`
@@ -573,7 +574,8 @@ Specify how to determine the authenticity of encryption certificates provided by
 
 This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
 
-This setting does not have any effect if ``encrypted`` is set to ``False``.
+This setting does not have any effect if ``encrypted`` is set to ``False`` or a
+custom ``ssl_context`` is configured.
 
 :Type: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``, ``neo4j.TRUST_ALL_CERTIFICATES``
 
@@ -605,7 +607,7 @@ Specify a custom SSL context to use for wrapping connections.
 
 This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
 
-If given, ``encrypted`` and ``trusted_certificates`` have no effect.
+If given, ``encrypted``, ``trusted_certificates``, and ``client_certificate`` have no effect.
 
 .. warning::
     This option may compromise your application's security if used improperly.
@@ -632,13 +634,37 @@ custom ``ssl_context`` is configured.
 :Type: :class:`.TrustSystemCAs`, :class:`.TrustAll`, or :class:`.TrustCustomCAs`
 :Default: :const:`neo4j.TrustSystemCAs()`
 
+.. versionadded:: 5.0
+
 .. autoclass:: neo4j.TrustSystemCAs
 
 .. autoclass:: neo4j.TrustAll
 
 .. autoclass:: neo4j.TrustCustomCAs
 
-.. versionadded:: 5.0
+
+.. _client-certificate-ref:
+
+``client_certificate``
+----------------------
+Specify a client certificate or certificate provider for mutual TLS (mTLS) authentication.
+
+This setting does not have any effect if ``encrypted`` is set to ``False``
+(and the URI scheme is ``bolt://`` or ``neo4j://``) or a custom ``ssl_context`` is configured.
+
+**This is a preview** (see :ref:`filter-warnings-ref`).
+It might be changed without following the deprecation policy.
+See also
+https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+:Type: :class:`.ClientCertificate`, :class:`.ClientCertificateProvider` or :data:`None`.
+:Default: :data:`None`
+
+.. versionadded:: 5.19
+
+.. autoclass:: neo4j.auth_management.ClientCertificate
+
+.. autoclass:: neo4j.auth_management.ClientCertificateProvider
 
 
 .. _user-agent-ref:

docs/source/async_api.rst

@@ -381,7 +381,8 @@ Async Driver Configuration
 driver accepts
 
  * a sync as well as an async custom resolver function (see :ref:`async-resolver-ref`)
- * as sync as well as an async auth token manager (see :class:`.AsyncAuthManager`).
+ * a sync as well as an async auth token manager (see :class:`.AsyncAuthManager`).
+ * an async client certificate provider (see :ref:`async-client-certificate-ref`).
 
 
 .. _async-resolver-ref:
@@ -436,6 +437,28 @@ For example:
 :Default: :data:`None`
 
 
+.. _async-client-certificate-ref:
+
+``client_certificate``
+----------------------
+Specify a client certificate or certificate provider for mutual TLS (mTLS) authentication.
+
+This setting does not have any effect if ``encrypted`` is set to ``False``
+(and the URI scheme is ``bolt://`` or ``neo4j://``) or a custom ``ssl_context`` is configured.
+
+**This is a preview** (see :ref:`filter-warnings-ref`).
+It might be changed without following the deprecation policy.
+See also
+https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+:Type: :class:`.ClientCertificate`, :class:`.AsyncClientCertificateProvider` or :data:`None`.
+:Default: :data:`None`
+
+.. versionadded:: 5.19
+
+.. autoclass:: neo4j.auth_management.AsyncClientCertificateProvider
+
+
 
 Driver Object Lifetime
 ======================

src/neo4j/__init__.py

@@ -37,7 +37,6 @@
 )
 from ._conf import (
     Config as _Config,
-    PoolConfig as _PoolConfig,
     SessionConfig as _SessionConfig,
     TrustAll,
     TrustCustomCAs,
@@ -53,6 +52,7 @@
     PreviewWarning,
     version as __version__,
 )
+from ._sync.config import PoolConfig as _PoolConfig
 from ._sync.driver import (
     BoltDriver,
     Driver,

src/neo4j/_api.py

@@ -48,11 +48,11 @@ class NotificationMinimumSeverity(str, Enum):
         >>> NotificationMinimumSeverity.INFORMATION == "INFORMATION"
         True
 
-    .. versionadded:: 5.7
-
     .. seealso::
         driver config :ref:`driver-notifications-min-severity-ref`,
         session config :ref:`session-notifications-min-severity-ref`
+
+    .. versionadded:: 5.7
     """
 
     OFF = "OFF"
@@ -111,9 +111,9 @@ class NotificationSeverity(str, Enum):
                 # or severity_level == "UNKNOWN"
                 log.debug("%r", notification)
 
-    .. versionadded:: 5.7
-
     .. seealso:: :attr:`SummaryNotification.severity_level`
+
+    .. versionadded:: 5.7
     """
 
     WARNING = "WARNING"
@@ -137,14 +137,14 @@ class NotificationDisabledCategory(str, Enum):
         >>> NotificationDisabledCategory.DEPRECATION == "DEPRECATION"
         True
 
+    .. seealso::
+        driver config :ref:`driver-notifications-disabled-categories-ref`,
+        session config :ref:`session-notifications-disabled-categories-ref`
+
     .. versionadded:: 5.7
 
     .. versionchanged:: 5.14
         Added categories :attr:`.SECURITY` and :attr:`.TOPOLOGY`.
-
-    .. seealso::
-        driver config :ref:`driver-notifications-disabled-categories-ref`,
-        session config :ref:`session-notifications-disabled-categories-ref`
     """
 
     HINT = "HINT"
@@ -188,12 +188,12 @@ class NotificationCategory(str, Enum):
         >>> NotificationCategory.UNKNOWN == "UNKNOWN"
         True
 
+    .. seealso:: :attr:`SummaryNotification.category`
+
     .. versionadded:: 5.7
 
     .. versionchanged:: 5.14
         Added categories :attr:`.SECURITY` and :attr:`.TOPOLOGY`.
-
-    .. seealso:: :attr:`SummaryNotification.category`
     """
 
     HINT = "HINT"

src/neo4j/_async/auth_management.py

@@ -19,12 +19,18 @@
 import typing as t
 from logging import getLogger
 
-from .._async_compat.concurrency import AsyncLock
+from .._async_compat.concurrency import (
+    AsyncCooperativeLock,
+    AsyncLock,
+)
 from .._auth_management import (
     AsyncAuthManager,
+    AsyncClientCertificateProvider,
+    ClientCertificate,
     expiring_auth_has_expired,
     ExpiringAuth,
 )
+from .._meta import preview
 
 
 if t.TYPE_CHECKING:
@@ -285,3 +291,127 @@ async def auth_provider():
             "Neo.ClientError.Security.Unauthorized",
         ))
         return AsyncNeo4jAuthTokenManager(provider, handled_codes)
+
+
+class _AsyncStaticClientCertificateProvider(AsyncClientCertificateProvider):
+    _cert: t.Optional[ClientCertificate]
+
+    def __init__(self, cert: ClientCertificate) -> None:
+        self._cert = cert
+
+    async def get_certificate(self) -> t.Optional[ClientCertificate]:
+        cert, self._cert = self._cert, None
+        return cert
+
+
+@preview("Mutual TLS is a preview feature.")
+class AsyncRotatingClientCertificateProvider(AsyncClientCertificateProvider):
+    """
+    Implementation of a certificate provider that can rotate certificates.
+
+    The provider will make the driver use the initial certificate for all
+    connections until the certificate is updated using the
+    :meth:`update_certificate` method.
+    From that point on, the new certificate will be used for all new
+    connections until :meth:`update_certificate` is called again and so on.
+
+    **This is a preview** (see :ref:`filter-warnings-ref`).
+    It might be changed without following the deprecation policy.
+    See also
+    https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+    Example::
+
+        from neo4j import AsyncGraphDatabase
+        from neo4j.auth_management import (
+            ClientCertificate,
+            AsyncClientCertificateProviders,
+        )
+
+
+        provider = AsyncClientCertificateProviders.rotating(
+            ClientCertificate(
+                certfile="path/to/certfile.pem",
+                keyfile="path/to/keyfile.pem",
+                password=lambda: "super_secret_password"
+            )
+        )
+        driver = AsyncGraphDatabase.driver(
+           # secure driver must be configured for client certificate
+           # to be used: (...+s[sc] scheme or encrypted=True)
+           "neo4j+s://example.com:7687",
+           # auth still required as before, unless server is configured to not
+           # use authentication
+           auth=("neo4j", "password"),
+           client_certificate=provider
+        )
+
+        # do work with the driver, until the certificate needs to be rotated
+        ...
+
+        await provider.update_certificate(
+            ClientCertificate(
+                certfile="path/to/new/certfile.pem",
+                keyfile="path/to/new/keyfile.pem",
+                password=lambda: "new_super_secret_password"
+            )
+        )
+
+        # do more work with the driver, until the certificate needs to be
+        # rotated again
+        ...
+
+    :param initial_cert: The certificate to use initially.
+
+    .. versionadded:: 5.19
+
+    """
+    def __init__(self, initial_cert: ClientCertificate) -> None:
+        self._cert: t.Optional[ClientCertificate] = initial_cert
+        self._lock = AsyncCooperativeLock()
+
+    async def get_certificate(self) -> t.Optional[ClientCertificate]:
+        async with self._lock:
+            cert, self._cert = self._cert, None
+            return cert
+
+    async def update_certificate(self, cert: ClientCertificate) -> None:
+        """
+        Update the certificate to use for new connections.
+        """
+        async with self._lock:
+            self._cert = cert
+
+
+class AsyncClientCertificateProviders:
+    """A collection of :class:`.AsyncClientCertificateProvider` factories.
+
+    **This is a preview** (see :ref:`filter-warnings-ref`).
+    It might be changed without following the deprecation policy.
+    See also
+    https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+    .. versionadded:: 5.19
+    """
+    @staticmethod
+    @preview("Mutual TLS is a preview feature.")
+    def static(cert: ClientCertificate) -> AsyncClientCertificateProvider:
+        """
+        Create a static client certificate provider.
+
+        The provider simply makes the driver use the given certificate for all
+        connections.
+        """
+        return _AsyncStaticClientCertificateProvider(cert)
+
+    @staticmethod
+    @preview("Mutual TLS is a preview feature.")
+    def rotating(
+        initial_cert: ClientCertificate
+    ) -> AsyncRotatingClientCertificateProvider:
+        """
+        Create certificate provider that allows for rotating certificates.
+
+        .. seealso:: :class:`.AsyncRotatingClientCertificateProvider`
+        """
+        return AsyncRotatingClientCertificateProvider(initial_cert)