LDAP integration
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 Configuration settings.
LDAP dynamic configuration settings
The following configuration settings can be updated while the database is running, see Update dynamic settings. Altering any of these settings clears the authentication and authorization cache.
Parameter name | Default value | Description |
---|---|---|
|
Convert usernames into LDAP-specific fully qualified names required for logging in. |
|
|
Set the base object or named context to search for user objects. |
|
|
Set an LDAP search filter for a user principal. |
|
dbms.security.ldap.authorization.group_membership_attributes |
|
List attribute names of a user object that contains groups to be used for mapping to roles.
Common values: |
|
This setting determines whether multiple LDAP search results will be processed.
This must be set to |
|
List an authorization mapping from groups to the pre-defined built-in roles |
||
|
Set the attribute to search for users with a system account. |
|
Set an LDAP group of users with access rights.
Users passing authentication are mapped to at least the |
||
|
When set to |
All settings are defined at server startup time in the default configuration file neo4j.conf or can be modified at
runtime using dbms.setConfigValue()
.
Set Neo4j to use LDAP
First, you configure Neo4j to use LDAP as an authentication and authorization provider.
-
Uncomment the setting
dbms.security.auth_enabled=false
and change its value totrue
to turn on the security feature. -
Uncomment the settings
dbms.security.authentication_providers
anddbms.security.authorization_providers
and change their value toldap
. This way, the LDAP connector is used as a security provider for both authentication and authorization.If you want, you can still use the
native
provider for mixed-mode authentication and authorization. The values are comma-separated and queried in the declared order.Example 1. Configure Neo4j to use LDAP and the native authentication and authorization providerdbms.security.authentication_providers=ldap,native dbms.security.authorization_providers=ldap,native
Map the LDAP groups to the Neo4j roles
To assign privileges to users based on their LDAP groups, 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
.
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 Manage roles. |
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.
Configure Neo4j to support LDAP user ID authentication
This option allows users to log in with their LDAP user ID.
In the neo4j.conf file, uncomment and configure the following settings:
-
Configure LDAP to point to the AD server:
dbms.security.ldap.host=ldap://myactivedirectory.example.com
-
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
-
Map the groups in the LDAP system to the Neo4j built-in and custom roles. See Map the LDAP groups to the Neo4j roles.
Configure Neo4j to support attribute authentication
This is an alternative configuration for Active Directory that allows users to log in by providing an attribute to search for, by default sAMAccountName
.
The attribute has to be unique to be used as a lookup.
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:
-
Configure LDAP to point to the AD server:
dbms.security.ldap.host=ldap://myactivedirectory.example.com
-
Provide details on the user structure of the LDAP directory (replacing
myattribute
with the actual attribute name):dbms.security.ldap.authorization.user_search_base=cn=Users,dc=example,dc=com dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(myattribute={0})) dbms.security.ldap.authorization.group_membership_attributes=memberOf
-
Map the groups in the LDAP system to the Neo4j built-in and custom roles. See Map the LDAP groups to the Neo4j roles.
-
Configure Neo4j to use a system account with read access to all users and groups in the LDAP server.
-
Set
dbms.security.ldap.authorization.use_system_account
value totrue
. -
Set
dbms.security.ldap.authorization.system_username
value to the full Distinguished Name (DN) as thedbms.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
-
Configure the LDAP system account password.
dbms.security.ldap.authorization.system_password=mypassword
-
Configure which attribute to search for by adding the following lines to the neo4j.conf file (replacing
myattribute
with the actual attribute name):dbms.security.ldap.authentication.search_for_attribute=true dbms.security.ldap.authentication.attribute=myattribute
-
(Optional) Create an LDAP group to restrict authentication against the database to a subset of LDAP users:
dbms.security.ldap.authorization.access_permitted_group=cn=Neo4j Access,cn=users,dc=example,dc=com
-
Configure Neo4j to support sAMAccountName
authentication by setting user_dn_template
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:
-
Configure LDAP to point to the AD server:
dbms.security.ldap.host=ldap://myactivedirectory.example.com
-
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
-
Map the groups in the LDAP system to the Neo4j built-in and custom roles. For more information, see Map the LDAP groups to the Neo4j roles.
The setting dbms.security.ldap.authentication.search_for_attribute should be set to the default value of false.
|
Configure Neo4j to perform nested group lookup
When a user is a member of a group (e.g. engineers
) and that group is a member of another group (e.g. employees
), Active Directory can be configured to perform a nested search such that a user in the group engineers
would also be a member of the group employees
.
This in turn means that it is possible to configure a group to role mapping for employees
which will transitively apply to engineers
.
Active Directory facilitates nested search via the extensible match operator LDAP_MATCHING_RULE_IN_CHAIN
(whose Object Identifier is 1.2.840.113556.1.4.1941).
This operator walks the chain of ancestry in objects all the way to the root.
To set up nested search in the neo4j.conf file, configure the following settings:
-
Enable nested groups.
dbms.security.ldap.authorization.nested_groups_enabled=true
-
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=dc=example,dc=com dbms.security.ldap.authorization.user_search_filter=(&(objectClass=*)(uid={0}))
-
Provide the nested groups search filter.
This is the filter which will be used to perform the nested lookup of the user’s groups. It should contain the placeholder token{0}
, which will be substituted with the user’s Distinguished Name (which is found for the specified user principle usingdbms.security.ldap.authorization.user_search_filter
).
This example features Active Directory’sLDAP_MATCHING_RULE_IN_CHAIN
(aka1.2.840.113556.1.4.1941
) implementation:dbms.security.ldap.authorization.nested_groups_search_filter=(&(objectclass=group)(member:1.2.840.113556.1.4.1941:={0}))
-
Provide group to role mappings, including ancestor groups if required:
dbms.security.ldap.authorization.group_to_role_mapping=\ "cn=engineers,cn=users,dc=example,dc=com"=procedures;\ "cn=employees,cn=users,dc=example,dc=com"=reader
In contrast to a non-nested-LDAP lookup, a nested group lookup does not perform an attribute-based lookup on the user object.
Instead, the dbms.security.ldap.authorization.group_membership_attributes setting is ignored and the dbms.security.ldap.authorization.user_search_filter is only used to determine the Distinguished Name of the user.
This is then substituted into the dbms.security.ldap.authorization.nested_groups_search_filter to perform a separate, nested lookup of the user’s groups.
|
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:
-
Configure LDAP to point to the OpenLDAP server:
dbms.security.ldap.host=myopenldap.example.com
-
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
-
(Optional) Create an LDAP group to restrict authentication against the database to a subset of LDAP users:
dbms.security.ldap.authorization.access_permitted_group=501
-
Map the groups in the LDAP system to the Neo4j built-in and custom roles. For more information, see Map the LDAP groups to the Neo4j roles.
Configure authentication/authorization at the user level using auth providers
User auth providers can be used to determine which users can authenticate and authorize using the configured providers, including LDAP.
You must change the dbms.security.require_local_user
configuration setting to true
to use auth providers.
This means that a user with a matching auth provider must exist in order to be able to authenticate and authorize.
This applies to all providers.
Conversely, when dbms.security.require_local_user
is set to false
, users' auth providers have no bearing on the way that they are authenticated and authorized, instead authentication and authorization is controlled centrally (for all users) by the database configuration.
The following examples show how to configure users with auth provider ldap
using Cypher.
LDAP
CREATE USER alice
SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
The command creates the user alice
who can authenticate and authorize using LDAP provided their LDAP dn
is cn=alice,ou=engineering,dc=example,dc=com
.
mysso
providerCREATE USER alice
SET HOME DATABASE anotherDb
SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
SET AUTH 'oidc-mysso' {SET ID 'alicesUniqueMySsoId'}
The command creates the user alice
who can authenticate and authorize using ldap
or mysso
.
See Configure SSO at the user level using auth providers for more information on setting up an OIDC provider.
The example also illustrates that the user can have their home database set even when using only external auth providers.
ALTER USER alice
REMOVE AUTH 'ldap'
The command prevents the user alice
from being able to authenticate and authorize using ldap
.
ALTER USER alice
SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED}
The command allows the user alice
to authenticate and authorize using the specified username and password (in addition to what they are already configured to use).
ldap
and authorization via the native
provider-
Set the following database config:
dbms.security.authentication_providers=ldap dbms.security.authorization_providers=native
-
Create a user with an
ldap
auth provider:CREATE USER alice SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
-
Natively grant the
READER
role to the user:GRANT ROLE READER TO alice
The command allows the user
alice
to authenticate usingldap
and receive theREADER
role from thenative
provider. -
You can also give the user the union of roles from
ldap
andnative
roles by settingldap
as an authorization provider too:dbms.security.authentication_providers=ldap dbms.security.authorization_providers=native,ldap
ALTER USER alice
SET STATUS SUSPENDED
The command completely prevents the user from being able to authenticate/authorize by any means.
Suppose there are two users both with the name alice
, one is part of the engineering
tree (cn=alice,ou=engineering,dc=example,dc=com
) and the other is part of the sales
tree (cn=alice,ou=sales,dc=example,dc=com
).
To disambiguate these users, you can create two users in the database, each with a different ID
that corresponds to the dn
of the user in the LDAP tree.
CREATE USER aliceEngineering
SET AUTH 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
CREATE USER aliceSales
SET AUTH 'ldap' { SET ID 'cn=alice,ou=sales,dc=example,dc=com' }
Verify the LDAP configuration
You can verify that your LDAP configuration is correct, and that the LDAP server responds, by using the LDAP command-line tool ldapsearch
.
The ldapsearch
command accepts the LDAP configuration setting values as input and verifies both the authentication (using the simple
mechanism) and authorization of a user.
See the ldapsearch official documentation for more advanced usage and how to use SASL authentication mechanisms.
-
Verify the authentication and authorization of a user. For example,
john
.-
With
dbms.security.ldap.authorization.use_system_account=false
(default):# ldapsearch -v -H ldap://<dbms.security.ldap.host> -x -D <dbms.security.ldap.authentication.user_dn_template : replace {0}> -W -b <dbms.security.ldap.authorization.user_search_base> "<dbms.security.ldap.authorization.user_search_filter : replace {0}>" <dbms.security.ldap.authorization.group_membership_attributes> ldapsearch -v -H ldap://myactivedirectory.example.com:389 -x -D cn=john,cn=Users,dc=example,dc=com -W -b cn=Users,dc=example,dc=com "(&(objectClass=*)(cn=john))" memberOf
-
With
dbms.security.ldap.authorization.use_system_account=true
:# ldapsearch -v -H ldap://<dbms.security.ldap.host> -x -D <dbms.security.ldap.authorization.system_username> -w <dbms.security.ldap.authorization.system_password> -b <dbms.security.ldap.authorization.user_search_base> "<dbms.security.ldap.authorization.user_search_filter>" <dbms.security.ldap.authorization.group_membership_attributes> ldapsearch -v -H ldap://myactivedirectory.example.com:389 -x -D cn=search-account,cn=Users,dc=example,dc=com -w mypassword -b cn=Users,dc=example,dc=com "(&(objectClass=*)(cn=john))" memberOf
-
-
Verify that the value of the returned membership attribute is a group that is mapped to a role in
dbms.security.ldap.authorization.group_to_role_mapping
.# extended LDIF # # LDAPv3 # base <cn=Users,dc=example,dc=com> with scope subtree # filter: (cn=john) # requesting: memberOf # # john, Users, example.com dn: CN=john,CN=Users,DC=example,DC=com memberOf: CN=Neo4j Read Only,CN=Users,DC=example,DC=com # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1
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
Parameter name | Default value | Description |
---|---|---|
|
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. |
|
|
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 |
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()
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
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
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
is used.
dbms.security.ldap.host=ldaps://myactivedirectory.example.com
dbms.security.ldap.host=ldaps://myactivedirectory.example.com:636
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 server.jvm.additional
in neo4j.conf.
The path to the certificate file MyCert.jks
is an absolute path to the Neo4j server.
server.jvm.additional=-Djavax.net.ssl.keyStore=/path/to/MyCert.jks
server.jvm.additional=-Djavax.net.ssl.keyStorePassword=mypasword
server.jvm.additional=-Djavax.net.ssl.trustStore=/path/to/MyCert.jks
server.jvm.additional=-Djavax.net.ssl.trustStorePassword=mypasword
Debug logging of group result
While setting up an LDAP integration, it is sometimes necessary to perform troubleshooting.
In these cases, it can be useful to view the group result from the LDAP server.
To enable the logging of these claims at DEBUG
level in the security log, set dbms.security.logs.ldap.groups_at_debug_level_enabled to be true
and the security log level to DEBUG
.
Make sure to set dbms.security.logs.ldap.groups_at_debug_level_enabled back to |