v5.8.0 - Feedback wanted on re-authentication 📣

[robsdedude]

Re-Authentication

In version 5.8.0, we introduce a new preview APIs to the driver. Under the term re-authentication, we deliver actually two closely related features:

1. Auth rotation:
   replacing the authentication information in the driver without having to create a new driver object
2. Session auth/user switching:
   using specific auth information for the duration of a session

1. Auth Rotation

This is used for auth tokens that are expected to expire (e.g., SSO).

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

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:

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


def auth_provider():
    # some way to get 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.expiration_based(auth_provider)
) as driver:
    ... 

⚠️ Important to 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.
• AuthManagers (and consequentially provider functions passed to AuthManagers.expiration_based) must not interact with the driver in any way as this can cause deadlocks and undefined behavior.

2) Session Auth

For the purpose of switching users, Sessions 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+).

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

Feedback wanted

This new API is currently marked as preview. What it means is that we are eagerly waiting for your feedback. Does it work well in your scenario? Do you wish there was more?

Let us know so we can correct course in the next releases!

[robsdedude]

⚠️ In 5.9.0, a breaking change to neo4j.auth_management.ExpiringAuth used for auth rotation is applied: it now expects an absolute expiration time. A convenience method to create it with a relative expiration time is added (#928).
The attribute expires_in was replaced by expires_at, which now expects a unix timestamp.
You can use ExpiringAuth(some_auth).expires_in(123) instead if you rely on relative expiration.

[robsdedude]

⚠️ In 5.12.0, breaking changes were introduced to this preview feature:

• Removed TokenExpiredRetryable exception.
  Even though it wasn't marked preview, it was introduced with and only used for re-auth. It no longer serves any purpose.
• The AuthManager and AsyncAuthManager abstract classes were changed.
  The method on_auth_expired(self, auth: _TAuth) -> None was removed in favor of handle_security_exception(self, auth: _TAuth, error: Neo4jError) -> bool.
  See the API docs for more details.
• The factories in AsyncAuthManagers and AuthManagers were changed.
  • expiration_based was renamed to bearer.
  • basic was added to cater for password rotation.

[zprobst]

We have password rotation for our service accounts. This feature, as implemented in 5.12 definitely meets our needs.

[robsdedude]

Thank you for the feedback. We're delighted to hear this :)

[robsdedude]

With version 5.14.0, this feature is now stabilized.