LDAP 集成

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

配置 LDAP 时，以下配置设置非常重要。有关 LDAP 配置选项的更详细概述，请参阅 配置设置。

LDAP 动态配置设置

数据库运行时可以更新以下配置设置，请参阅 更新动态设置。更改其中任何设置都会清除身份验证和授权缓存。

参数名称 默认值 描述

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 命令授予权限之前显式创建。请参阅 管理角色。

配置 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 的值设置为完整的 Distinguished Name (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}，该令牌将替换为用户的 Distinguished Name（使用 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 仅用于确定用户的 Distinguished Name。然后将其替换到 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 角色。

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

用户身份验证提供程序可用于确定哪些用户可以使用配置的提供程序（包括 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 进行身份验证和授权，前提是其 LDAP dn 为 cn=alice,ou=engineering,dc=example,dc=com。

示例 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 提供程序的更多信息，请参阅 使用身份验证提供程序在用户级别配置 SSO。该示例还说明，即使仅使用外部身份验证提供程序，用户也可以设置其主数据库。

示例 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 seconds

是缓存身份验证和授权信息的生存时间 (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 服务器提供的组结果可能会随时间变化。