Deployment

The official Neo4j Kerberos Add-on can be used to extend Neo4j with Kerberos authentication. The add-on provides authentication and should be used in conjunction with another provider such as LDAP for authorization. It is available for download at the Neo4j download site.

The Neo4j Kerberos Add-on v4.0.0 is compatible with all releases of Neo4j v4 and Neo4j v5.

We walk you through the deployment of Kerberos Add-on in the following section. It consists of several steps:

Configure Neo4j for Kerberos
Generate the Kerberos keytab file
Configure the Kerberos Add-on

For file locations, please refer to Operations Manual → File Locations. All relative paths in this document are resolved against the neo4j-home directory.

In the examples, we are using Kerberos on Windows. We assume that LDAP is used for authorization, and that the current realm (Windows domain) is WINDOMAIN.LOCAL.

Configure Neo4j for Kerberos

Place the kerberos-add-on.jar file in the plugins/ directory of your Neo4j installation. Edit neo4j.conf to enable the Kerberos Add-on as authentication provider.

Example 1. Configure neo4j.conf

#For authentication with kerberos-add-on
dbms.security.authentication_providers=plugin-Neo4j-Kerberos
dbms.security.authorization_providers=ldap

#For authorization with LDAP
dbms.security.ldap.host=ad.windomain.local
dbms.security.ldap.authorization.use_system_account=true
dbms.security.ldap.authorization.system_username=CN=neo4jservice,OU=IT-Services,DC=windomain,DC=local
dbms.security.ldap.authorization.system_password=PASSWORD
dbms.security.ldap.authorization.user_search_base=CN=Users,DC=windomain,DC=local
dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(SamAccountName={0}))
dbms.security.ldap.authorization.group_membership_attributes=memberOf
dbms.security.ldap.authorization.group_to_role_mapping= \
  "CN=Neo4j Read Only,CN=Users,DC=windomain,DC=local"      = reader; \
  "CN=Neo4j Read-Write,CN=Users,DC=windomain,DC=local"     = publisher; \
  "CN=Neo4j Schema Manager,CN=Users,DC=windomain,DC=local" = architect; \
  "CN=Neo4j Administrator,CN=Users,DC=windomain,DC=local"  = admin; \
  "CN=Neo4j Procedures,CN=Users,DC=windomain,DC=local"     = allowed_role

Generate the Kerberos keytab file

Create a service user for the Neo4j server in the KDC. Make sure to generate a keytab for the Neo4j service user and place it in the conf directory. In this example, we name it neo4j.ktab. The keytab will be used by Neo4j.

Configure the Kerberos Add-on

If you have already been using Kerberos through the Heimdal or MIT tool kinit, you have a krb5.conf file that contains information on how to reach the KDC. If you do not have such a file, or do not wish to use it, create a new krb5.conf file in the conf directory.

Example 2. Configure krb5.conf

In this example, we are using a realm of WINDOMAIN.LOCAL and an IP address for the KDC and admin server of 192.168.38.2.

Replace these with your actual realm and the actual IP or domain name of your KDC and admin server, respectively.

[libdefaults]
	default_realm = WINDOMAIN.LOCAL

	default_tgs_enctypes = rc4-hmac rc4-hmac-exp aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 des3-hmac-sha1
	default_tkt_enctypes = rc4-hmac rc4-hmac-exp aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 des3-hmac-sha1
	permitted_enctypes = rc4-hmac rc4-hmac-exp aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 des3-hmac-sha1

[realms]
	WINDOMAIN.LOCAL = {
		kdc = 192.168.38.2
		admin_server = 192.168.38.2
	}

[domain_realm]
	.windomain.local = WINDOMAIN.LOCAL
	windomain.local = WINDOMAIN.LOCAL

Some cryptographic algorithms are not natively supported by Java. When using the more advanced cryptographic algorithms (for example ASE-256) ensure that the Java that is running Neo4j have the Java Cryptography Extension extension enabled.

Now create a second file called kerberos.conf in the conf directory. The keytab setting refers to the keytab file created above. The service.principal setting is the principal in that keytab, and the krb5.conf setting refers to the krb5.conf file (already present from the existing Kerberos installation, or created in the step above).

Again, replace the values with the correct values according to your setup.

Example 3. Configure kerberos.conf

realm=WINDOMAIN.LOCAL
keytab=conf/neo4j.ktab
service.principal=neo4j/neo4j.windomain.local@WINDOMAIN.LOCAL
krb5.conf=conf/krb5.conf