Introduce AuthToken rotation and session auth support

[injectives]

The main feature of this update is the support for AuthToken rotation, which might also be referred to as a refresh or re-auth. In practice, it allows replacing the current token with a new token during the driver's lifetime.

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.

[injectives]

What I don't like is the naming. Temporal can be anything. While it is better than Renewable, it doesn't capture the essence of wrt it expires. It is a mouthful, but ExpiringToken or TokenWIthExpirationDate would give a very clear indication of what this actually is.

@michael-simons, thanks a lot for the review and for the kind comment.

As you might be aware, there has been a team discussion and it has been decided to go with AuthTokenAndExpiration, which hopefully is a better name.

[injectives]

Also apreciate the detailed PR comment, especially with how much the ADR has grown in size.

Just some minor initial comments on the surface parts.

@gjmwoods many thanks for the review and for the kind comment.

The comments have been addressed.