Re-authentication

[bigmontz]

⚠️ This API is released as preview.

This changes introduce two ways of changing the connection credentials in a driver instance, each of them solving a different use case.

Token Expiration / Change Credentials for the whole driver instance

This use case is related to the issue #993 in the repository. For solving this, the driver is now able to receive a AuthTokenManager in the driver creation. This interface enables the user code provide new auth tokens to the driver and be notified by token expiration failures.

For simplifying the usage, the driver also provides a default implementation of AuthTokenManager which can be created with neo4j. expirationBasedAuthTokenManager and receives a function for renewing the auth token as parameters.

Example:

import neo4j, { AuthToken } from 'neo4j-driver'

/**
 * Method called whenever the driver needs to refresh the token.
 *
 * The refresh will happen if the driver is notified by the server
 * about a token expiration or if the `Date.now() > tokenData.expiry`
 *
 * Important, the driver will block all the connections creation until
 * this function resolves the new auth token.
 */
async function fetchAuthTokenFromMyProvider () {
   const bearer: string = await myProvider.getBearerToken()
   const token: AuthToken = neo4j.auth.bearer(bearer)
   const expiration: Date = myProvider.getExpiryDate()  
   return {
      token,
      // if expiration is not provided, 
      // the driver will only fetch a new token when a failure happens
      expiration 
   }
}

const driver = neo4j.driver(
    'neo4j://localhost:7687', 
    neo4j.expirationBasedAuthTokenManager({ 
        tokenProvider: fetchAuthTokenFromMyProvider 
    })
)

User Switching

In this scenario, different credentials can be configured in a session providing a way for change the user context for the session. For using this feature, it needed to check if your server supports session auth by calling driver.supportsSessionAuth().

Example:

import neo4j from 'neo4j-driver'


const driver =  neo4j.driver(
    'neo4j://localhost:7687', 
    neo4j.auth.basic('neo4j', 'password')
)


const sessionWithUserB = driver.session({
  database: 'neo4j',
  auth: neo4j.auth.basic('userB', 'userBpassword')
})


try {
  // run some queries as userB
  const result = await sessionWithUserB.executeRead(tx => tx.run('RETURN 1'))
} finally {
  // close the session as usual
  await sessionWithUserB.close()
}

⚠️ This API is released as preview.

[tristanls]

Hi, apologies if this is the wrong place to ask. Thank you, been looking forward to this work. It looks like this missed the 5.7 release. Is it feasible to put out 5.8 release so we can test out this API preview?

[ConorNeo]

Hi, yes this is merged into dev and (unless something changes) will be in 5.8

[jhanggi]

I know this feature is in preview, so happy to wait. I wanted to try this out since we've had problems in the past with Neo4jError: LDAP authorization info expired. We've worked around it by catching that particular error and retrying, but this felt like it might be a cleaner solution.

I believe the typescript types may not all be updated. It seems the second argument to neo4j.driver still only accepts AuthToken.

Argument of type 'AuthTokenManager' is not assignable to parameter of type 'AuthToken'. Type 'AuthTokenManager' is missing the following properties from type 'AuthToken': scheme, credentials

const driver = neo4j.driver(
  'neo4j://localhost:7687',
  neo4j.expirationBasedAuthTokenManager({
    // tokenProvider rather than getAuthData
    tokenProvider: () => {
      return neo4j.basic('username', 'password')
    }),
  }),
);

[bigmontz]

@jhanggi, thanks for spotting the issue.

I've updated the type definitions in the PR: #1089

I've also updated description of this PR with the correct example.

[bigmontz]

Fix released in 5.9.0