You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Introduce AuthToken rotation and session auth support (neo4j#1380)
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:
```java
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:
```java
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:
```java
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:
```java
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:
```java
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.
0 commit comments