v5.19.0 - Feedback wanted on mTLS for 2FA

[robsdedude]

mTLS

In version 5.19.0, we introduce mutual TLS (client-side certificates) as a second authentication factor (2FA).

Example Usage

import neo4j
from neo4j.auth_management import (
    ClientCertificateProviders, 
    ClientCertificate,
)


URL = "neo4j+s://localhost:7687"
AUTH = ("neo4j", "pass")


def main():
    cert_provider = ClientCertificateProviders.static(
        ClientCertificate(
            # path to public certificate to load
            "path/to/cert.pem",
            # path to private key to load
            "path/to/key.pem",
            # password to decrypt private key (can be a function or string)
            # see also Python's ssl.SSLContext.load_cert_chain()
            lambda: "password",
        )
    )
    # See the API docs for ClientCertificateProviders.rotating and more details
    # in general.
    
    with neo4j.GraphDatabase.driver(
        URL,
        auth=AUTH,
        client_certificate=cert_provider,
    ) as driver:
        with driver.session() as session:
            result = session.run("RETURN 'now with mTLS 🔒'")
            for record in result:
                print(record)
    

if __name__ == '__main__':
    main()

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!

[robsdedude]

In version 5.24.0, the neo4j.auth_management.RotatingClientCertificateProvider was made an abstract class. This means it can no longer be instantiated directly. Please use the factory method neo4j.auth_management.RotatingClientCertificateProvider.rotating instead.

Analogously for the async APIs.

[robsdedude]

With version 5.27.0, this feature is now stabilized.

[ChrisSamo632]

I realise this discussion is now closed, but hopefully you/somone can still help @robsdedude ...

I'm attempting to connect to a Neo4j instance secured with a custom CA. I can follow this example to set the client_certificate in the neo4j.GraphDatabase.driver but the connection fails because (I think) the driver isn't trusting the server's certificate.

There's a trusted_certificates parameter for the driver constructor, but that's only available for neo4j or bolt URIs, not neo4j+s (or +ssc) - how can one setup mTLS with client certs and custom CA trust?

[robsdedude]

When using either of the config options trusted_certificates (its deprecated counterpart trust), encrypted, and/or ssl_context, you can indeed only use the URI schemes bolt:// or neo4j://. That is because the suffixes ...+s[sc]:// are shorthand notation for configuring these TLS related options.

...+ssc:// =>

• encrypted=True,
• trusted_certificates=neo4j.TrustAll(),
• ssl_context=None (default)

...+s:// =>

• encrypted=True,
• trusted_certificates=neo4j.TrustSystemCAs(), (default)
• ssl_context=None (default)

From what I understand what you want is something along the lines of:

with neo4j.GraphDatabase(
    "neo4j://example.com:7687",  # without +s or +ssc
    auth=("user", "password"),
    encrypted=True,
    trusted_certificates=neo4j.TrustCustomCAs("/path/to/ca1.crt", ...),
)

[ChrisSamo632]

Ah OK, so your suggestion is effectively neo4j+s but with custom CA

And one should be able to set a client_certificate along with this too presumably, i.e. to enable mTLS between client and server?

So needing neo4j+s (or +ssc) is a misnomer/misunderstanding (on my part) if one uses straight-up neo4j:// but sets the extra fields too, is that right?

[robsdedude]

And one should be able to set a client_certificate along with this too presumably, i.e. to enable mTLS between client and server?

That's right.

So needing neo4j+s (or +ssc) is a misnomer/misunderstanding (on my part) if one uses straight-up neo4j:// but sets the extra fields too, is that right?

Yes. Not only do you not need to use neo4j+s (or +ssc) with other TLS settings, you cannot even.

N.B., the API docs should mention when certain options are incompatible with URL schemes.

For example:

encrypted

[...]
This setting is only available for URI schemes bolt:// and neo4j:// (URI).
[...]

-- https://neo4j.com/docs/api/python-driver/current/api.html#encrypted

[ChrisSamo632]

Yeah they do, thanks - I'd just not realised that the +s and +ssc are simply shorthand protocols for enabling the encrypted and trusted_certificates settings, nor the real difference between those two.

But thanks, this provides the clarity I needed, and hopefully I'll be able to get this working in the near future.