11.4. Integration with LDAP directory services

This section describes Neo4j support for integrating with LDAP systems.

11.4.1. Introduction

Neo4j supports LDAP, which allows for integration with Active Directory (AD), OpenLDAP, or other LDAP-compatible authentication services. This means that you use the LDAP service for managing federated users, while the native Neo4j user and role administration are completely turned off.

The following configuration settings are important to consider when configuring LDAP. For a more detailed overview of the LDAP configuration options, see Section A.1, “Configuration settings”.

11.4.2. LDAP configuration parameters

Parameter name Default value Description

dbms.security.ldap.authentication.user_dn_template

uid={0},ou=users,dc=example,dc=com

Converts usernames into LDAP-specific fully qualified names required for logging in.

dbms.security.ldap.authorization.user_search_base

ou=users,dc=example,dc=com

Sets the base object or named context to search for user objects.

dbms.security.ldap.authorization.user_search_filter

(&(objectClass=*)(uid={0}))

Sets up an LDAP search filter to search for a user principal.

dbms.security.ldap.authorization.group_membership_attributes

memberOf

Lists attribute names on a user object that contains groups to be used for mapping to roles. Common values: memberOf and gidNumber.

dbms.security.ldap.authorization.group_to_role_mapping

 

Lists an authorization mapping from groups to the pre-defined built-in roles admin, architect, publisher, editor, and reader, or to any other custom-defined roles.

All settings are defined at server startup time in the default configuration file neo4j.conf.

11.4.3. Set Neo4j to use LDAP

First, you configure Neo4j to use LDAP as an authentication and authorization provider.

  1. Uncomment the setting dbms.security.auth_enabled=false and change its value to true to turn on the security feature.
  2. Uncomment the settings dbms.security.authentication_providers and dbms.security.authorization_providers and change their value to ldap. This way, the LDAP connector will be used as a security provider for both authentication and authorization.

11.4.4. Map the LDAP groups to the Neo4j roles

To access the user and role management procedures, you have to map the LDAP groups to the Neo4j built-in and custom-defined roles. To do that, you need to know what privileges the Neo4j roles have, and based on these privileges, to create the mapping to the groups defined in the LDAP server. The map must be formatted as a semicolon separated list of key-value pairs, where the key is a comma-separated list of the LDAP group names and the value is a comma-separated list of the corresponding role names. For example, group1=role1;group2=role2;group3=role3,role4,role5;group4,group5=role6.

Example of LDAP groups to Neo4j roles mapping. 

dbms.security.ldap.authorization.group_to_role_mapping=\
    "cn=Neo4j Read Only,cn=users,dc=example,dc=com"      = reader;    \ (1)
    "cn=Neo4j Read-Write,cn=users,dc=example,dc=com"     = editor,publisher; \ (2)
    "cn=Neo4j Read-Write,cn=users,dc=example,dc=com","cn=Neo4j Create Data,cn=users,dc=example,dc=com"     = publisher; \ (3)
    "cn=Neo4j Create Data,cn=users,dc=example,dc=com","cn=Neo4j Schema Manager,cn=users,dc=example,dc=com" = architect; \
    "cn=Neo4j Administrator,cn=users,dc=example,dc=com"  = admin; \
    "cn=Neo4j Procedures,cn=users,dc=neo4j,dc=com"       = rolename (4)

1

Mapping of an LDAP group to a Neo4j built-in role.

2

Mapping of an LDAP group to two Neo4j built-in roles.

3

Mapping of two LDAP groups to a Neo4j built-in role.

4

Mapping of an LDAP group to a custom-defined role. Custom-defined roles, such as rolename, must be explicitly created using the CREATE ROLE rolename command before they can be used to grant privileges. See the Cypher Manual → Creating roles.

11.4.5. Configure Neo4j to use Active Directory

You configure Neo4j to use the LDAP security provider to access and manage your Active Directory. There are three alternative ways to do that depending on your specific use case.

11.4.5.1. Configure Neo4j to support LDAP user ID authentication (Option 1)

This option allows users to log in with their LDAP user ID.

In the neo4j.conf file, uncomment and configure the following settings:

  1. Configure LDAP to point to the AD server:

    dbms.security.ldap.host=ldap://myactivedirectory.example.com
  2. Provide details on the user structure of the LDAP directory:

    dbms.security.ldap.authentication.user_dn_template=cn={0},cn=Users,dc=example,dc=com
    dbms.security.ldap.authorization.user_search_base=cn=Users,dc=example,dc=com
    dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(cn={0}))
    dbms.security.ldap.authorization.group_membership_attributes=memberOf
  3. Map the groups in the LDAP system to the Neo4j built-in and custom roles. See Section 11.4.4, “Map the LDAP groups to the Neo4j roles”.

11.4.5.2. Configure Neo4j to support sAMAccountName authentication (Option 2)

This is an alternative configuration for Active Directory that allows users to log in using sAMAccountName. You create a system account that has read-only access to the parts of the LDAP directory that you want. However, it does not need to have access rights to Neo4j or any other systems.

In the neo4j.conf file, uncomment and configure the following settings:

  1. Configure LDAP to point to the AD server:

    dbms.security.ldap.host=ldap://myactivedirectory.example.com
  2. Provide details on the user structure of the LDAP directory:

    dbms.security.ldap.authorization.user_search_base=cn=Users,dc=example,dc=com
    dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(samaccountname={0}))
    dbms.security.ldap.authorization.group_membership_attributes=memberOf
  3. Map the groups in the LDAP system to the Neo4j built-in and custom roles. See Section 11.4.4, “Map the LDAP groups to the Neo4j roles”.
  4. Configure Neo4j to use a system account with read access to all users and groups in the LDAP server.

    1. Set dbms.security.ldap.authorization.use_system_account value to true.
    2. Set dbms.security.ldap.authorization.system_username value to the full Distinguished Name (DN) as the dbms.security.ldap.authentication.user_dn_template will not be applied to this username. For example,

      dbms.security.ldap.authorization.system_username=cn=search-account,cn=Users,dc=example,dc=com
    3. Configure the LDAP system account password.

      dbms.security.ldap.authorization.system_password=mypassword

      sAMAccountName requires dbms.security.ldap.authorization.system_username and dbms.security.ldap.authorization.system_password to be used, since there is no way to log in through LDAP directly with the sAMAccountName. Instead, the login name will be resolved to a DN that will be used to log in with.

    4. Add the following line to the neoj.conf file:

      dbms.security.ldap.authentication.use_samaccountname=true

11.4.5.3. Configure Neo4j to support sAMAccountName authentication (Option 3)

This is an alternative configuration for Active Directory that allows all users from the specified domain to log in using sAMAccountName. With this option, you do not have to create a system account and store a system username/password in the config file. Instead, you set {0}@example.com as a value of the user_dn_template to enable the authentication to start at the root domain. This way, the whole tree is checked to find the user, regardless of where it is located within the LDAP directory tree.

In the neo4j.conf file, uncomment and configure the following settings:

  1. Configure LDAP to point to the AD server:

    dbms.security.ldap.host=ldap://myactivedirectory.example.com
  2. Provide details on the user structure of the LDAP directory:

    dbms.security.ldap.authentication.user_dn_template={0}@example.com
    dbms.security.ldap.authorization.user_search_base=dc=example,dc=com
    dbms.security.ldap.authorization.user_search_filter=(&(objectClass=user)(sAMAccountName={0}))
    dbms.security.ldap.authorization.group_membership_attributes=memberOf
  3. Map the groups in the LDAP system to the Neo4j built-in and custom roles. For more information, see Section 11.4.4, “Map the LDAP groups to the Neo4j roles”.

The setting dbms.security.ldap.authentication.use_samaccountname is not configured.

11.4.6. Configure Neo4j to use OpenLDAP

You configure the LDAP security provider to access and manage your OpenLDAP directory service.

In the neo4j.conf file, uncomment and configure the following settings:

  1. Configure LDAP to point to the OpenLDAP server:

    dbms.security.ldap.host=myopenldap.example.com
  2. Provide details on the user structure of the LDAP directory:

    dbms.security.ldap.authentication.user_dn_template=cn={0},ou=users,dc=example,dc=com
    dbms.security.ldap.authorization.user_search_base=ou=users,dc=example,dc=com
    dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(uid={0}))
    dbms.security.ldap.authorization.group_membership_attributes=gidNumber
  3. Map the groups in the LDAP system to the Neo4j built-in and custom roles. For more information, see Section 11.4.4, “Map the LDAP groups to the Neo4j roles”.

11.4.8. The auth cache

The auth cache is the mechanism by which Neo4j caches the result of authentication via the LDAP server in order to aid performance. It is configured with the parameters dbms.security.ldap.authentication.cache_enabled, and dbms.security.auth_cache_ttl.

# Turn on authentication caching to ensure performance.

dbms.security.ldap.authentication.cache_enabled=true
dbms.security.auth_cache_ttl=10m
Table 11.2. Auth cache parameters
Parameter name Default value Description

dbms.security.ldap.authentication.cache_enabled

true

Determines whether or not to cache the result of authentication via the LDAP server.

Whether authentication caching should be enabled or not must be considered in view of your company’s security guidelines.

dbms.security.auth_cache_ttl

600 seconds

Is the time to live (TTL) for cached authentication and authorization info.

Setting the TTL to 0 disables all auth caching.

A short TTL requires more frequent re-authentication and re-authorization, which can impact performance.

A very long TTL means that changes to the users settings on an LDAP server may not be reflected in the Neo4j authorization behaviour in a timely manner.

Valid units are ms, s, m; default unit is s.

An administrator can clear the auth cache to force the re-querying of authentication and authorization information from the federated auth provider system. Use Neo4j Browser or Neo4j Cypher Shell to execute this statement:

CALL dbms.security.clearAuthCache()

11.4.9. Available methods of encryption

Specifying the dbms.security.ldap.host parameter configures using LDAP without encryption. Not specifying the protocol or port results in ldap being used over the default port 389.

dbms.security.ldap.host=myactivedirectory.example.com
dbms.security.ldap.host=myactivedirectory.example.com:389
dbms.security.ldap.host=ldap://myactivedirectory.example.com
dbms.security.ldap.host=ldap://myactivedirectory.example.com:389

11.4.9.1. Use LDAP with encryption via StartTLS

To configure Active Directory with encryption via StartTLS, set the following parameters:

dbms.security.ldap.use_starttls=true
dbms.security.ldap.host=ldap://myactivedirectory.example.com

11.4.9.2. Use LDAP with encrypted LDAPS

To configure Active Directory with encrypted LDAPS, set dbms.security.ldap.host to one of the following. If you do not specify the port, the default one 636 will be used.

dbms.security.ldap.host=ldaps://myactivedirectory.example.com
dbms.security.ldap.host=ldaps://myactivedirectory.example.com:636

11.4.10. Use a self-signed certificate (SSL) in a test environment

Production environments should always use an SSL certificate issued by a Certificate Authority for secure access to the LDAP server. However, there are scenarios, for example in test environments, where you may want to use an SSL certificate on the LDAP server.

To configure an SSL certificate on LDAP server, enter the details of the certificate using dbms.jvm.additional in neo4j.conf. The path to the certificate file MyCert.jks is an absolute path to the Neo4j server.

dbms.jvm.additional=-Djavax.net.ssl.keyStore=/path/to/MyCert.jks
dbms.jvm.additional=-Djavax.net.ssl.keyStorePassword=mypasword
dbms.jvm.additional=-Djavax.net.ssl.trustStore=/path/to/MyCert.jks
dbms.jvm.additional=-Djavax.net.ssl.trustStorePassword=mypasword