v5.8.0 - Feedback wanted on re-authentication 📣

[fbiville]

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).

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})

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!

[StephenCathcart]

⚠️ In 5.12.0, breaking changes were introduced to this preview feature (see 523):

ExpirationBasedTokenManager was renamed to BearerTokenManager for handling potentially expiring auth information:

func ExampleBearerTokenManager() {
	fetchAuthTokenFromMyProvider := 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)
		// or return nil instead of `&expiresIn` if we don't expect it to expire
		return token, &expiresIn, nil
	}
	// create a new driver with a bearer token manager which uses provider to handle possibly expiring auth tokens.
	_, _ = neo4j.NewDriverWithContext(getUrl(), auth.BearerTokenManager(fetchAuthTokenFromMyProvider))
}

A BasicTokenManager token manager was added to handle password rotation:

func ExampleBasicTokenManager() {
	fetchBasicAuthToken := func(ctx context.Context) (neo4j.AuthToken, error) {
		// some way of getting basic authentication information
		username, password, realm, err := getBasicAuth()
		if err != nil {
			return neo4j.AuthToken{}, err
		}
		// create and return a basic authentication token with provided username, password and realm
		return neo4j.BasicAuth(username, password, realm), nil
	}
	// create a new driver with a basic token manager which uses provider to handle basic auth password rotation.
	_, _ = neo4j.NewDriverWithContext(getUrl(), auth.BasicTokenManager(fetchBasicAuthToken))
}

[StephenCathcart]

Closing the discussion as the re-auth feature is now out of preview as of v5.14.0 🎉