AuthToken rotation and session auth support

[injectives]

The support for AuthToken rotation allows replacing the current token with a new token during the driver's lifetime. This might also be referred to as re-auth.

The main objective of this feature is to allow token rotation for the same identity. As such, it is not intended for a change of identity.

A new type called AuthTokenManager has the following 2 primary responsibilities:

• supplying a valid token, which may be one of the following:
  • the current token
  • a new token, which instructs the driver to use the new token
• handling a token expiration failure that originates from the server if it determines the current token to be expired (a timely rotation should generally reduce the likelihood of this happening)

The driver does not make judgements on whether the current AuthToken should be updated. Instead, it calls the AuthTokenManager to check if the provided token is the same as the currently used token and takes action if not. The driver reserves the right to call the manager as often as it deems necessary. The manager implementations must be thread-safe and non-blocking for caller threads. For instance, IO operations must not be done on the calling thread.

The GraphDatabase class has been updated to include a set of new methods that accept the AuthTokenManager.

An example of the driver instantiation:

var manager = // the manager implementation
var driver = GraphDatabase.driver(uri, manager);

The token rotation benefits from the new Bolt 5.1 version, but works on previous Bolt versions at the expence of replacing existing connections with new connections.

An expiration based AuthTokenManager implementation is available via a new AuthTokenManagers factory. It manages AuthToken instances that come with a UTC expiration timestamp and calls a new token supplier, which is provided by the user, when a new token is required.

An example of the expiration based manager instantiation:

var manager = AuthTokenManagers.expirationBased(() -> {
  var token = // get new token logic
  return token.expiringAt(timestamp); // a new method on AuthToken introduced for the supplied expiration based AuthTokenManager implementation
});

The new LOGOFF and LOGON Bolt protocol messages allow for auth management on active Bolt connections and are used by the features in this update.

In addition to the token rotation support, this update also includes support for setting a static AuthToken instance on the driver session level.

Unlike the rotation feature, this feature may be used for an identity change. As such, it might be referred to as user switching.

It requires a minimum Bolt 5.1 version.

The Driver interface has 2 new session methods that accept an AuthToken instance.

A basic example:

var token = AuthTokens.bearer("token");
var session = driver.session(Session.class, token);

The Driver includes a new method that checks whether the session auth is supported.

The implementation assumes all servers to be at the same version.

Sample usage:

var supports = driver.supportsSessionAuth();

The Driver includes a new method that verifies a given AuthToken instance by communicating with the server.

It requires a minimum Bolt 5.1 version.

Sample usage:

var token = AuthTokens.bearer("token");
var successful = driver.verifyAuthentication(token);

There are 2 new exceptions:

• AuthTokenManagerExecutionException - Indicates that the AuthTokenManager execution has lead to an unexpected result. This includes invalid results and errors.
• TokenExpiredRetryableException - Indicates that the token supplied by the AuthTokenManager has been deemed as expired by the server. This is a retryable variant of the TokenExpiredException used when the driver has an explicit AuthTokenManager that might supply a new token following this failure. If driver is instantiated with the static AuthToken, the TokenExpiredException will be used instead.