Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce Client Certificate configuration #1183

Merged
merged 23 commits into from
Mar 7, 2024
Merged

Conversation

bigmontz
Copy link
Contributor

@bigmontz bigmontz commented Feb 21, 2024

⚠️ This API is released as preview.
⚠️ This feature is NodeJS only. Browser should configure the client certificate in the system certificates.

The ClientCertificate is a mechanism to support mutual TLS as a second factor for authentication. The driver's certificate will not be used to authenticate a user on the DBMS, but only to authenticate the driver as a trusted client to the DBMS. Another authentication mechanism is still required to authenticate the user.

The configuration is done by using the driver configuration, the property name is clientCertificate and this a object with the following properties:

  • certfile: The path to client certificate file. This is can configured as list of paths.
  • keyfile: The path to key file. This can also be configured as a list of paths, an object contain path and password or a list of objects contain path and password.
  • password (optional): The client key password.

See node documentation for understanding how password, certs and keys work together.

Configuration example:

import neo4j from 'neo4j-driver'

const driver = neo4j.driver('neo4j+s://myhost:7687', MY_CREDENTIALS, {
   clientCertificate: {
      certfile: '/path/to/cert/file.cert',
      keyfile: '/path/to/cert/file.pem',
      password: 'the_key_password' // optional
   }
})

// then use your driver as usual. 

Client Certificate Provider and Certificate Rotation

In case of the certificate needs to be changed, the driver offers an api for change client certificates without creating a new driver instance. The change is done by inform an ClientCertificateProvider instead of a ClientCertificate in the driver configuration.

ClientCertificateProvider is a public interface which can be implemented by user. However, the driver offers an implementation of this interface for working with certificate rotation scenarios.

import neo4j from 'neo4j-driver'

const initialClientCertificate: {
  certfile: '/path/to/cert/file.cert',
  keyfile: '/path/to/cert/file.pem',
  password: 'the_key_password' // optional
}

const clientCertificateProvider = neo4j.clientCertificateProviders.rotating({
    initialCertificate: initialClientCertificate
})

const driver = neo4j.driver('neo4j+s://myhost:7687', MY_CREDENTIALS, {
   clientCertificate: clientCertificateProvider
})


// use the driver as usual

// then you have new certificate which will replace the old one
clientCertificateProvider.updateCertificate({
  certfile: '/path/to/cert/new_file.cert',
  keyfile: '/path/to/cert/new_file.pem',
  password: 'the_new_key_password' // optional
})

// New connections will be created using the new certificate.
// however, older connections will not be closed if they still working.

⚠️ This feature is NodeJS only. Browser should configure the client certificate in the system certificates.
⚠️ This API is released as preview.

@bigmontz bigmontz linked an issue Feb 21, 2024 that may be closed by this pull request
@bigmontz bigmontz marked this pull request as ready for review March 5, 2024 08:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Client-authenticated TLS connection
2 participants