Add support for re-authentication

[fbiville]

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-go-driver/#preview-features

1) Auth Rotation

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

An auth.TokenManager instance may be passed to the driver instead of a static auth token.

import (
    "context"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

type myTokenManager struct {}
func (m *myTokenManager) GetAuthToken(ctx context.Context) (neo4j.AuthToken, error) {
    // [...] see API documentation for details
}
func (m *myTokenManager) OnTokenExpired(ctx context.Context, token neo4j.AuthToken) error {
    // [...] see API documentation for details
}

driver, err := neo4j.NewDriverWithContext("neo4j://example.com:7687", &myTokenManager{})
// [...]

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

import (
    "context"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j/auth"
    "time"
)

myProvider := func(ctx context.Context) (neo4j.AuthToken, *time.Time, error) {
    // some way of getting a token
    token, err := getSsoToken(ctx)
    if err != nil {
        return neo4j.AuthToken{}, nil, err
    }
    // assume we know our tokens expire every 60 seconds
    expiresIn := time.Now().Add(60 * time.Second)
    // Include a little buffer so that we fetch a new token *before* the old one expires
    expiresIn = expiresIn.Add(-10 * time.Second)
    // note: we can return nil instead of `&expiresIn` if we don't expect the token to expire
    return token, &expiresIn, nil
}

driver, err = neo4j.NewDriverWithContext(getUrl(), auth.ExpirationBasedTokenManager(myProvider))
// [...]

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, 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 server 5.8+).

import (
    "context"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

// [...]
sessionAuth1 := neo4j.BasicAuth("jane", "doe", "")
session1 := driver.NewSession(ctx, neo4j.SessionConfig{Auth: &sessionAuth1})
// [...]
sessionAuth2 := neo4j.BasicAuth("john", "doe", "")
session2 := driver.NewSession(ctx, neo4j.SessionConfig{Auth: &sessionAuth2})