LDAP 集成
企业版

Neo4j 支持 LDAP，这允许与 Active Directory (AD)、OpenLDAP 或其他兼容 LDAP 的身份验证服务进行集成。这意味着您可以使用 LDAP 服务来管理联合用户，而原生的 Neo4j 用户和角色管理功能将完全关闭。

在配置 LDAP 时，需要考虑以下配置设置。有关 LDAP 配置选项的更详细概述，请参阅 Configuration settings。

LDAP 动态配置设置

以下配置设置可以在数据库运行时进行更新，请参阅 Update dynamic settings。更改这些设置中的任何一项都会清除身份验证和授权缓存。

参数名称 默认值 描述

dbms.security.ldap.authentication.user_dn_template

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

将用户名转换为登录所需的 LDAP 特定全限定名。

dbms.security.ldap.authorization.user_search_base

ou=users,dc=example,dc=com

设置搜索用户对象的基础对象或命名上下文。

dbms.security.ldap.authorization.user_search_filter

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

为用户主体设置 LDAP 搜索过滤器。

dbms.security.ldap.authorization.group_membership_attributes

memberOf

列出用户对象中包含用于映射到角色的组的属性名称。常见值：memberOf 和 gidNumber。

dbms.security.ldap.authorization.nested_groups_enabled

false

此设置决定是否处理多个 LDAP 搜索结果。为了解析嵌套组成员身份，必须将其设置为 true。

dbms.security.ldap.authorization.group_to_role_mapping

列出从组到预定义内置角色（admin, architect, publisher, editor, reader）或任何其他自定义角色的授权映射。

dbms.security.ldap.authentication.attribute

samaccountname

设置使用系统账户搜索用户的属性。

dbms.security.ldap.authorization.access_permitted_group

设置具有访问权限的 LDAP 用户组。通过身份验证的用户除了被 组到角色映射 分配的任何角色外，至少会被映射到 PUBLIC 角色，并获得这些角色所提供的数据库访问权限。如果设置了此属性，即使凭据正确，不属于此 LDAP 组的用户也将无法通过身份验证。

dbms.security.logs.ldap.groups_at_debug_level_enabled

false

当设置为 true 时，它会将组查找结果记录到安全日志中（前提是安全日志级别也设置为 DEBUG）。

所有设置均在服务器启动时在默认配置文件 neo4j.conf 中定义，或者可以使用 dbms.setConfigValue() 在运行时进行修改。

设置 Neo4j 使用 LDAP

首先，您需要配置 Neo4j 使用 LDAP 作为身份验证和授权提供程序。

  1. 取消注释设置 dbms.security.auth_enabled=false 并将其值更改为 true 以开启安全功能。

  2. 取消注释设置 dbms.security.authentication_providers 和 dbms.security.authorization_providers 并将其值更改为 ldap。这样，LDAP 连接器将同时用作身份验证和授权的安全提供程序。

    如果需要，您仍然可以使用 native 提供程序进行混合模式身份验证和授权。这些值以逗号分隔，并按声明的顺序进行查询。

    示例 1. 配置 Neo4j 使用 LDAP 和原生身份验证与授权提供程序
    dbms.security.authentication_providers=ldap,native
dbms.security.authorization_providers=ldap,native

将 LDAP 组映射到 Neo4j 角色

要根据用户的 LDAP 组分配权限，必须将 LDAP 组映射到 Neo4j 内置 和自定义角色。为此，您需要了解 Neo4j 角色拥有的权限，并基于这些权限创建与 LDAP 服务器中定义的组的映射。映射必须格式化为以分号分隔的键值对列表，其中键是 LDAP 组名，值是对应角色名的逗号分隔列表。

例如：group1=role1;group2=role2;group3=role3,role4,role5;group4=role6;group5=role6。

示例 2. LDAP 组到 Neo4j 角色映射示例
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 将 LDAP 组映射到 Neo4j 内置角色。
2 将 LDAP 组映射到两个 Neo4j 内置角色。
3 将两个 LDAP 组映射到一个 Neo4j 内置角色。
4 将 LDAP 组映射到自定义定义的角色。自定义角色（例如 rolename）必须先使用 CREATE ROLE rolename 命令明确创建，然后才能用于授予权限。请参阅 Manage roles。

配置 Neo4j 使用 Active Directory

您可以配置 Neo4j 使用 LDAP 安全提供程序来访问和管理您的 Active Directory。根据您的具体用例，有三种替代方法。

配置 Neo4j 支持 LDAP 用户 ID 身份验证

此选项允许用户使用其 LDAP 用户 ID 登录。

在 neo4j.conf 文件中，取消注释并配置以下设置：

  1. 配置 LDAP 以指向 AD 服务器

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

  2. 提供 LDAP 目录的用户结构详情

    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. 将 LDAP 系统中的组映射到 Neo4j 内置和自定义角色。请参阅 将 LDAP 组映射到 Neo4j 角色。

配置 Neo4j 支持属性身份验证

这是 Active Directory 的一种替代配置，允许用户通过提供要搜索的属性（默认为 sAMAccountName）来登录。该属性必须是唯一的才能用作查找依据。您需要创建一个对 LDAP 目录中所需部分具有只读访问权限的系统账户。但是，它不需要拥有 Neo4j 或任何其他系统的访问权限。

在 neo4j.conf 文件中，取消注释并配置以下设置：

  1. 配置 LDAP 以指向 AD 服务器

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

  2. 提供 LDAP 目录的用户结构详情（将 myattribute 替换为实际属性名称）

    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

  3. 将 LDAP 系统中的组映射到 Neo4j 内置和自定义角色。请参阅 将 LDAP 组映射到 Neo4j 角色。

  4. 配置 Neo4j 使用对 LDAP 服务器中所有用户和组具有读取权限的系统账户。

    1. 将 dbms.security.ldap.authorization.use_system_account 的值设置为 true。

    2. 将 dbms.security.ldap.authorization.system_username 的值设置为完整的专有名 (DN)，因为 dbms.security.ldap.authentication.user_dn_template 不会应用于此用户名。例如：

      dbms.security.ldap.authorization.system_username=cn=search-account,cn=Users,dc=example,dc=com

    3. 配置 LDAP 系统账户密码。

      dbms.security.ldap.authorization.system_password=your_password

    4. 通过在 neo4j.conf 文件中添加以下行来配置要搜索的属性（将 myattribute 替换为实际属性名称）

      dbms.security.ldap.authentication.search_for_attribute=true
dbms.security.ldap.authentication.attribute=myattribute

    5. （可选）创建一个 LDAP 组，将数据库的身份验证限制为 LDAP 用户的子集

      dbms.security.ldap.authorization.access_permitted_group=cn=Neo4j Access,cn=users,dc=example,dc=com

通过设置 user_dn_template 配置 Neo4j 支持 sAMAccountName 身份验证

这是 Active Directory 的另一种配置，允许来自指定域的所有用户使用 sAMAccountName 登录。使用此选项，您无需创建系统账户并在配置文件中存储系统用户名/密码。相反，您将 {0}@example.com 设置为 user_dn_template 的值，以启用从根域开始的身份验证。通过这种方式，系统会检查整个树以查找用户，无论其位于 LDAP 目录树中的何处。

在 neo4j.conf 文件中，取消注释并配置以下设置：

  1. 配置 LDAP 以指向 AD 服务器

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

  2. 提供 LDAP 目录的用户结构详情

    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. 将 LDAP 系统中的组映射到 Neo4j 内置和自定义角色。有关更多信息，请参阅 将 LDAP 组映射到 Neo4j 角色。

设置 dbms.security.ldap.authentication.search_for_attribute 应设置为默认值 false。

配置 Neo4j 执行嵌套组查找

当用户属于一个组（例如 engineers）且该组又是另一个组（例如 employees）的成员时，可以配置 Active Directory 执行嵌套搜索，使得 engineers 组中的用户同时也成为 employees 组的成员。这意味着可以为 employees 配置 组到角色映射，这将传递性地应用于 engineers。

Active Directory 通过可扩展匹配运算符 LDAP_MATCHING_RULE_IN_CHAIN（其对象标识符为 1.2.840.113556.1.4.1941）实现嵌套搜索。此运算符将对象中的祖先链一直遍历到根节点。

要在 neo4j.conf 文件中设置嵌套搜索，请配置以下设置：

  1. 启用嵌套组。

    dbms.security.ldap.authorization.nested_groups_enabled=true

  2. 提供 LDAP 目录的用户结构详情

    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}))

  3. 提供嵌套组搜索过滤器。
    这是将用于执行用户组嵌套查找的过滤器。它应包含占位符标记 {0}，该标记将替换为用户的专有名（使用 dbms.security.ldap.authorization.user_search_filter 为指定用户主体找到该名称）。
    此示例展示了 Active Directory 的 LDAP_MATCHING_RULE_IN_CHAIN (又名 1.2.840.113556.1.4.1941) 实现

    dbms.security.ldap.authorization.nested_groups_search_filter=(&(objectclass=group)(member:1.2.840.113556.1.4.1941:={0}))

  4. 提供组到角色的映射，如果需要，包括祖先组

    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
与非嵌套 LDAP 查找不同，嵌套组查找不会对用户对象执行基于属性的查找。相反，dbms.security.ldap.authorization.group_membership_attributes 设置会被忽略，而 dbms.security.ldap.authorization.user_search_filter 仅用于确定用户的专有名。随后将其替换到 dbms.security.ldap.authorization.nested_groups_search_filter 中，以对用户的组执行单独的嵌套查找。

配置 Neo4j 使用 OpenLDAP

您可以配置 LDAP 安全提供程序来访问和管理您的 OpenLDAP 目录服务。

在 neo4j.conf 文件中，取消注释并配置以下设置：

  1. 配置 LDAP 以指向 OpenLDAP 服务器

    dbms.security.ldap.host=myopenldap.example.com

  2. 提供 LDAP 目录的用户结构详情

    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. （可选）创建一个 LDAP 组，将数据库的身份验证限制为 LDAP 用户的子集

    dbms.security.ldap.authorization.access_permitted_group=501

  4. 将 LDAP 系统中的组映射到 Neo4j 内置和自定义角色。有关更多信息，请参阅 将 LDAP 组映射到 Neo4j 角色。

使用身份验证提供程序在用户级别配置身份验证/授权

User auth providers 可用于确定哪些用户可以使用包括 LDAP 在内的配置提供程序进行身份验证和授权。

您必须将 dbms.security.require_local_user 配置设置更改为 true 以使用身份验证提供程序。这意味着必须存在一个具有匹配身份验证提供程序的用户，才能进行身份验证和授权。这适用于所有提供程序。

相反，当 dbms.security.require_local_user 设置为 false 时，用户的身份验证提供程序对其身份验证和授权方式没有影响，此时身份验证和授权由数据库配置集中控制（针对所有用户）。

以下示例展示了如何使用 Cypher 配置具有 ldap 身份验证提供程序的用户。

示例 3. 创建一个可以使用 LDAP 进行身份验证和授权的身份验证提供程序用户
CREATE USER alice
SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }

该命令创建了用户 alice，如果她的 LDAP dn 为 cn=alice,ou=engineering,dc=example,dc=com，她就可以使用 LDAP 进行身份验证和授权。

示例 4. 创建一个具有两个身份验证提供程序的用户，允许该用户使用 LDAP 或 mysso 提供程序进行身份验证和授权
CREATE 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'}

该命令创建了用户 alice，她可以使用 ldap 或 mysso 进行身份验证和授权。有关设置 OIDC 提供程序的更多信息，请参阅 Configure SSO at the user level using auth providers。该示例还说明了即使仅使用外部身份验证提供程序，用户也可以设置其主数据库。

示例 5. 修改用户以移除其身份验证提供程序之一
ALTER USER alice
REMOVE AUTH 'ldap'

该命令禁止用户 alice 使用 ldap 进行身份验证和授权。

示例 6. 修改用户以允许他们使用用户名和密码进行身份验证和授权
ALTER USER alice
SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED}

该命令允许用户 alice 使用指定的用户名和密码进行身份验证和授权（除了他们已配置使用的内容之外）。

示例 7. 配置数据库以允许通过 ldap 进行身份验证，通过 native 提供程序进行授权

  1. 设置以下数据库配置

    dbms.security.authentication_providers=ldap
dbms.security.authorization_providers=native

  2. 创建一个具有 ldap 身份验证提供程序的用户

    CREATE USER alice
SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }

  3. 在本地授予该用户 READER 角色

    GRANT ROLE READER TO alice

    该命令允许用户 alice 使用 ldap 进行身份验证，并从 native 提供程序接收 READER 角色。

  4. 您还可以通过将 ldap 也设置为授权提供程序，将来自 ldap 和 native 角色的并集授予该用户。

    dbms.security.authentication_providers=ldap
dbms.security.authorization_providers=native,ldap
示例 8. 挂起用户
ALTER USER alice
SET STATUS SUSPENDED

该命令完全禁止该用户以任何方式进行身份验证/授权。

示例 9. 消除不同 LDAP 树中同名用户的歧义

假设有两个用户名均为 alice 的用户，一个属于 engineering 树 (cn=alice,ou=engineering,dc=example,dc=com)，另一个属于 sales 树 (cn=alice,ou=sales,dc=example,dc=com)。

为了消除这些用户的歧义，您可以在数据库中创建两个用户，每个用户具有与 LDAP 树中用户 dn 对应的不同 ID。

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' }

您可以使用 LDAP 命令行工具 ldapsearch 来验证您的 LDAP 配置是否正确，以及 LDAP 服务器是否响应。

ldapsearch 命令接受 LDAP 配置设置值作为输入，并验证用户的身份验证（使用 simple 机制）和授权。有关更高级的用法以及如何使用 SASL 身份验证机制，请参阅 ldapsearch 官方文档。

  1. 验证用户的身份验证和授权。例如：john。

    • 当 dbms.security.ldap.authorization.use_system_account=false (默认值) 时

      # 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

    • 当 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 your_password -b cn=Users,dc=example,dc=com "(&(objectClass=*)(cn=john))" memberOf

  2. 验证返回的成员资格属性的值是否为映射到 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

身份验证缓存

身份验证缓存是 Neo4j 用于缓存 LDAP 服务器身份验证结果以提升性能的机制。它通过参数 dbms.security.ldap.authentication.cache_enabled 和 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
表 1. 身份验证缓存参数
参数名称 默认值 描述

dbms.security.ldap.authentication.cache_enabled

true

决定是否缓存 LDAP 服务器的身份验证结果。

是否启用身份验证缓存必须根据贵公司的安全准则来考虑。

dbms.security.auth_cache_ttl

600 秒

是缓存身份验证和授权信息的生存时间 (TTL)。

将 TTL 设置为 0 将禁用所有身份验证缓存。

较短的 TTL 需要更频繁地重新进行身份验证和授权，这可能会影响性能。

非常长的 TTL 意味着 LDAP 服务器上的用户设置更改可能无法及时反映在 Neo4j 的授权行为中。

有效单位为 ms、s、m；默认单位为 s。

管理员可以清除身份验证缓存，强制从联合身份验证提供程序系统中重新查询身份验证和授权信息。使用 Neo4j Browser 或 Neo4j Cypher Shell 执行此语句：

CALL dbms.security.clearAuthCache()

可用的加密方法

指定 dbms.security.ldap.host 参数将配置为使用不加密的 LDAP。不指定协议或端口将导致在默认端口 389 上使用 ldap。

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

通过 StartTLS 使用加密的 LDAP

要配置带有 StartTLS 加密的 Active Directory，请设置以下参数：

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

使用加密的 LDAPS

要配置带有加密 LDAPS 的 Active Directory，请将 dbms.security.ldap.host 设置为以下值之一。如果不指定端口，则使用默认端口 636。

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

在测试环境中使用自签名证书 (SSL)

生产环境应始终使用由证书颁发机构颁发的 SSL 证书，以安全地访问 LDAP 服务器。然而，在某些场景（例如测试环境）中，您可能需要在 LDAP 服务器上使用自签名 SSL 证书。

要配置 LDAP 服务器上的 SSL 证书，请使用 neo4j.conf 中的 server.jvm.additional 输入证书详情。证书文件 MyCert.jks 的路径应为 Neo4j 服务器的绝对路径。

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

组结果的调试日志记录

在设置 LDAP 集成时，有时需要进行故障排除。在这些情况下，查看 LDAP 服务器返回的组结果非常有用。要启用安全日志中 DEBUG 级别的声明记录，请将 dbms.security.logs.ldap.groups_at_debug_level_enabled 设置为 true，并将安全日志级别设置为 DEBUG。

确保在生产环境中将 dbms.security.logs.ldap.groups_at_debug_level_enabled 改回 false，以避免不必要地记录可能敏感的信息。此外，请记住 LDAP 服务器提供的组结果可能会随时间发生变化。