Introduce auth rotation and session auth support (#890)

# ADR 012: re-authentication

This PR introduces two new auth mechanics for different use-cases
1) Auth Rotation
2) Session Auth (a.k.a. user switching)

**Note that all APIs introduced in this PR are previews**
See https://github.com/neo4j/neo4j-python-driver/wiki/preview-features


## 1) Auth Rotation
This is used for auth tokens that is expected to expire (e.g., SSO).

A `neo4j.auth_management.AuthManager` instance 
(or `neo4j.auth_management.AsyncAuthManager` for async driver) may be passed
to the driver instead of a static auth token.

```python
import neo4j
from neo4j.auth_management import AuthManager


class MyManager(AuthManager):
    ...  # see API dos for details


with neo4j.GraphDatabase.driver(
    "neo4j://example.com:7687", 
    auth=MyManager(),
) as driver:
    ...
```

The easiest way to get started is using the provided `AuthManager`
implementation. For example:

```python
import neo4j
from neo4j.auth_management import (
    AuthManagers,
    ExpiringAuth,
)


def auth_provider():
    # some way to getting a token
    sso_token = get_sso_token()
    # assume we know our tokens expire every 60 seconds
    expires_in = 60
    return ExpiringAuth(
        auth=neo4j.bearer_auth(sso_token),
        # Include a little buffer so that we fetch a new token
        # *before* the old one expires
        expires_in=expires_in - 10
    )


with neo4j.GraphDatabase.driver(
    "neo4j://example.com:7687",
    auth=AuthManagers.temporal(auth_provider)
) as driver:
    ... 
```

**Note**  
This API is explicitly *not* designed for switching users.
In fact, the token returned by each manager must always belong to the same
identity. Switching identities using the `AuthManager` is undefined behavior.


## 2) Session Auth
For the purpose of switching users, `Session`s can be configured with a static
auth token. This is very similar to impersonation in that all work in the
session will be executed in the security context of the user associated with
the auth token. The major difference is that impersonation does not require or
verify authentication information of the target user, however it requires
the impersonating user to have the permission to impersonate.

**Note**
This requires Bolt protocol version 5.3 or higher (Neo4j DBMS 5.8+).

```python
import neo4j


with neo4j.GraphDatabase.driver(
    "neo4j://example.com:7687",
    auth=("user1", "password1"),
) as driver:
    with driver.session(database="neo4j") as session:
        ...  # do some work as user1
    with driver.session(database="neo4j",
                        auth=("user2", "password2")) as session:
        ...  # do some work as user2
```


## References
Depends on:
 * neo4j-drivers/testkit#539

Related PRs:
 * #891

Issues:
 * closes #834

Author: robsdedude

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",