Introduce auth rotation and session auth support

docs/source/api.rst

@@ -107,10 +107,17 @@ Auth
 
 To authenticate with Neo4j the authentication details are supplied at driver creation.
 
-The auth token is an object of the class :class:`neo4j.Auth` containing the details.
+The auth token is an object of the class :class:`neo4j.Auth` containing static details or :class:`neo4j.auth_management.AuthManager` object.
 
 .. autoclass:: neo4j.Auth
 
+.. autoclass:: neo4j.auth_management.AuthManager
+    :members:
+
+.. autoclass:: neo4j.auth_management.AuthManagers
+    :members:
+
+.. autoclass:: neo4j.auth_management.ExpiringAuth
 
 
 Example:
@@ -154,7 +161,8 @@ Closing a driver will immediately shut down all connections in the pool.
 
 .. autoclass:: neo4j.Driver()
     :members: session, query_bookmark_manager, encrypted, close,
-              verify_connectivity, get_server_info
+              verify_connectivity, get_server_info, verify_authentication,
+              supports_session_auth, supports_multi_db
 
     .. method:: execute_query(query, parameters_=None,routing_=neo4j.RoutingControl.WRITERS, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=Result.to_eager_result, **kwargs)
 
@@ -174,7 +182,7 @@ Closing a driver will immediately shut down all connections in the pool.
 
             def execute_query(
                 query_, parameters_, routing_, database_, impersonated_user_,
-                bookmark_manager_, result_transformer_, **kwargs
+                bookmark_manager_, auth_, result_transformer_, **kwargs
             ):
                 def work(tx):
                     result = tx.run(query_, parameters_, **kwargs)
@@ -184,6 +192,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     database=database_,
                     impersonated_user=impersonated_user_,
                     bookmark_manager=bookmark_manager_,
+                    auth=auth_,
                 ) as session:
                     if routing_ == RoutingControl.WRITERS:
                         return session.execute_write(work)
@@ -263,6 +272,20 @@ Closing a driver will immediately shut down all connections in the pool.
 
             See also the Session config :ref:`impersonated-user-ref`.
         :type impersonated_user_: typing.Optional[str]
+        :param auth_:
+            Authentication information to use for this query.
+
+            By default, the driver configuration is used.
+
+            **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
+
+            See also the Session config :ref:`session-auth-ref`.
+        :type auth_: typing.Union[
+            typing.Tuple[typing.Any, typing.Any], neo4j.Auth, None
+        ]
         :param result_transformer_:
             A function that gets passed the :class:`neo4j.Result` object
             resulting from the query and converts it to a different type. The
@@ -273,7 +296,6 @@ Closing a driver will immediately shut down all connections in the pool.
                 The transformer function must **not** return the
                 :class:`neo4j.Result` itself.
 
-
             .. warning::
 
                 N.B. the driver might retry the underlying transaction so the
@@ -334,7 +356,7 @@ Closing a driver will immediately shut down all connections in the pool.
 
             Defaults to the driver's :attr:`.query_bookmark_manager`.
 
-            Pass :const:`None` to disable causal consistency.
+            Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
             typing.Union[neo4j.BookmarkManager, neo4j.BookmarkManager,
                          None]
@@ -348,7 +370,7 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer``
         :rtype: T
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
+        **This is experimental** (see :ref:`filter-warnings-ref`).
         It might be changed or removed any time even without prior notice.
 
         We are looking for feedback on this feature. Please let us know what
@@ -357,6 +379,9 @@ Closing a driver will immediately shut down all connections in the pool.
 
         .. versionadded:: 5.5
 
+        .. versionchanged:: 5.8
+            Added the ``auth_`` parameter.
+
 
 .. _driver-configuration-ref:
 
@@ -433,7 +458,7 @@ Specify whether TCP keep-alive should be enabled.
 :Type: ``bool``
 :Default: ``True``
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
+**This is experimental** (see :ref:`filter-warnings-ref`).
 It might be changed or removed any time even without prior notice.
 
 
@@ -784,6 +809,7 @@ Session
     .. automethod:: execute_write
 
 
+
 Query
 =====
 
@@ -804,6 +830,7 @@ To construct a :class:`neo4j.Session` use the :meth:`neo4j.Driver.session` metho
 + :ref:`default-access-mode-ref`
 + :ref:`fetch-size-ref`
 + :ref:`bookmark-manager-ref`
++ :ref:`session-auth-ref`
 + :ref:`session-notifications-min-severity-ref`
 + :ref:`session-notifications-disabled-categories-ref`
 
@@ -816,7 +843,7 @@ Optional :class:`neo4j.Bookmarks`. Use this to causally chain sessions.
 See :meth:`Session.last_bookmarks` or :meth:`AsyncSession.last_bookmarks` for
 more information.
 
-:Default: ``None``
+:Default: :data:`None`
 
 .. deprecated:: 5.0
     Alternatively, an iterable of strings can be passed. This usage is
@@ -995,10 +1022,33 @@ See :class:`.BookmarkManager` for more information.
 
 .. versionadded:: 5.0
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
+**This is experimental** (see :ref:`filter-warnings-ref`).
 It might be changed or removed any time even without prior notice.
 
 
+.. _session-auth-ref:
+
+``auth``
+--------
+Optional :class:`neo4j.Auth` or ``(user, password)``-tuple. Use this overwrite the
+authentication information for the session.
+This requires the server to support re-authentication on the protocol level. You can
+check this by calling :meth:`.Driver.supports_session_auth` / :meth:`.AsyncDriver.supports_session_auth`.
+
+It is not possible to overwrite the authentication information for the session with no authentication,
+i.e., downgrade the authentication at session level.
+Instead, you should create a driver with no authentication and upgrade the authentication at session level as needed.
+
+**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: :data:`None`, :class:`.Auth` or ``(user, password)``-tuple
+:Default: :data:`None` - use the authentication information provided during driver creation.
+
+.. versionadded:: 5.x
+
+
 .. _session-notifications-min-severity-ref:
 
 ``notifications_min_severity``
@@ -1293,7 +1343,7 @@ Graph
 
     .. automethod:: relationship_type
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
+**This is experimental** (see :ref:`filter-warnings-ref`).
 It might be changed or removed any time even without prior notice.
 
 
@@ -1751,6 +1801,8 @@ Server-side errors
 
       * :class:`neo4j.exceptions.TokenExpired`
 
+        * :class:`neo4j.exceptions.TokenExpiredRetryable`
+
     * :class:`neo4j.exceptions.Forbidden`
 
   * :class:`neo4j.exceptions.DatabaseError`
@@ -1786,6 +1838,9 @@ Server-side errors
 .. autoexception:: neo4j.exceptions.TokenExpired()
     :show-inheritance:
 
+.. autoexception:: neo4j.exceptions.TokenExpiredRetryable()
+    :show-inheritance:
+
 .. autoexception:: neo4j.exceptions.Forbidden()
     :show-inheritance:
 

docs/source/async_api.rst

@@ -40,7 +40,7 @@ The :class:`neo4j.AsyncDriver` construction is done via a ``classmethod`` on the
 
                 await driver.close()  # close the driver object
 
-             asyncio.run(main())
+            asyncio.run(main())
 
 
         For basic authentication, ``auth`` can be a simple tuple, for example:
@@ -67,7 +67,7 @@ The :class:`neo4j.AsyncDriver` construction is done via a ``classmethod`` on the
                 async with AsyncGraphDatabase.driver(uri, auth=auth) as driver:
                     ...  # use the driver
 
-             asyncio.run(main())
+            asyncio.run(main())
 
 
 
@@ -118,6 +118,20 @@ Each supported scheme maps to a particular :class:`neo4j.AsyncDriver` subclass t
     See https://neo4j.com/docs/operations-manual/current/configuration/ports/ for Neo4j ports.
 
 
+.. _async-auth-ref:
+
+Async Auth
+==========
+
+Authentication works the same as in the synchronous driver.
+With the exception that when using AuthManagers, their asynchronous equivalents have to be used.
+
+.. autoclass:: neo4j.auth_management.AsyncAuthManager
+    :members:
+
+.. autoclass:: neo4j.auth_management.AsyncAuthManagers
+    :members:
+
 
 ***********
 AsyncDriver
@@ -136,7 +150,8 @@ Closing a driver will immediately shut down all connections in the pool.
 
 .. autoclass:: neo4j.AsyncDriver()
     :members: session, query_bookmark_manager, encrypted, close,
-              verify_connectivity, get_server_info
+              verify_connectivity, get_server_info, verify_authentication,
+              supports_session_auth, supports_multi_db
 
     .. method:: execute_query(query, parameters_=None, routing_=neo4j.RoutingControl.WRITERS, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=AsyncResult.to_eager_result, **kwargs)
         :async:
@@ -157,7 +172,7 @@ Closing a driver will immediately shut down all connections in the pool.
 
             async def execute_query(
                 query_, parameters_, routing_, database_, impersonated_user_,
-                bookmark_manager_, result_transformer_, **kwargs
+                bookmark_manager_, auth_, result_transformer_, **kwargs
             ):
                 async def work(tx):
                     result = await tx.run(query_, parameters_, **kwargs)
@@ -167,6 +182,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     database=database_,
                     impersonated_user=impersonated_user_,
                     bookmark_manager=bookmark_manager_,
+                    auth=auth_,
                 ) as session:
                     if routing_ == RoutingControl.WRITERS:
                         return await session.execute_write(work)
@@ -202,13 +218,14 @@ Closing a driver will immediately shut down all connections in the pool.
             async def example(driver: neo4j.AsyncDriver) -> int:
                 """Call all young people "My dear" and get their count."""
                 record = await driver.execute_query(
-                    "MATCH (p:Person) WHERE p.age <= 15 "
+                    "MATCH (p:Person) WHERE p.age <= $age "
                     "SET p.nickname = 'My dear' "
                     "RETURN count(*)",
                     # optional routing parameter, as write is default
                     # routing_=neo4j.RoutingControl.WRITERS,  # or just "w",
                     database_="neo4j",
                     result_transformer_=neo4j.AsyncResult.single,
+                    age=15,
                 )
                 assert record is not None  # for typechecking and illustration
                 count = record[0]
@@ -245,6 +262,20 @@ Closing a driver will immediately shut down all connections in the pool.
 
             See also the Session config :ref:`impersonated-user-ref`.
         :type impersonated_user_: typing.Optional[str]
+        :param auth_:
+            Authentication information to use for this query.
+
+            By default, the driver configuration is used.
+
+            **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
+
+            See also the Session config :ref:`session-auth-ref`.
+        :type auth_: typing.Union[
+            typing.Tuple[typing.Any, typing.Any], neo4j.Auth, None
+        ]
         :param result_transformer_:
             A function that gets passed the :class:`neo4j.AsyncResult` object
             resulting from the query and converts it to a different type. The
@@ -315,7 +346,7 @@ Closing a driver will immediately shut down all connections in the pool.
 
             Defaults to the driver's :attr:`.query_bookmark_manager`.
 
-            Pass :const:`None` to disable causal consistency.
+            Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
             typing.Union[neo4j.AsyncBookmarkManager, neo4j.BookmarkManager,
                          None]
@@ -329,7 +360,7 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer``
         :rtype: T
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
+        **This is experimental** (see :ref:`filter-warnings-ref`).
         It might be changed or removed any time even without prior notice.
 
         We are looking for feedback on this feature. Please let us know what
@@ -338,15 +369,21 @@ Closing a driver will immediately shut down all connections in the pool.
 
         .. versionadded:: 5.5
 
+        .. versionchanged:: 5.8
+            Added the ``auth_`` parameter.
+
 
 .. _async-driver-configuration-ref:
 
 Async Driver Configuration
 ==========================
 
 :class:`neo4j.AsyncDriver` is configured exactly like :class:`neo4j.Driver`
-(see :ref:`driver-configuration-ref`). The only difference is that the async
-driver accepts an async custom resolver function:
+(see :ref:`driver-configuration-ref`). The only differences are that the async
+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:`neo4j.AsyncAuthManager`).
 
 
 .. _async-resolver-ref:
@@ -622,7 +659,7 @@ See :class:`BookmarkManager` for more information.
 :Type: :data:`None`, :class:`BookmarkManager`, or :class:`AsyncBookmarkManager`
 :Default: :data:`None`
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
+**This is experimental** (see :ref:`filter-warnings-ref`).
 It might be changed or removed any time even without prior notice.
 
 

requirements-dev.txt

@@ -17,6 +17,7 @@ tomlkit~=0.11.6
 
 # needed for running tests
 coverage[toml]>=5.5
+freezegun >= 1.2.2
 mock>=4.0.3
 pyarrow>=1.0.0
 pytest>=6.2.5

src/neo4j/__init__.py

@@ -52,6 +52,7 @@
     deprecation_warn as _deprecation_warn,
     ExperimentalWarning,
     get_user_agent,
+    PreviewWarning,
     version as __version__,
 )
 from ._sync.driver import (
@@ -140,11 +141,13 @@
     "NotificationFilter",
     "NotificationSeverity",
     "PoolConfig",
+    "PreviewWarning",
     "Query",
     "READ_ACCESS",
     "Record",
     "Result",
     "ResultSummary",
+    "RenewableAuth",
     "RoutingControl",
     "ServerInfo",
     "Session",