Neo4j作为主流的图数据库，在安全体系中最基础的一环就是用户认证。默认安装的Neo4j使用native authentication（本地原生认证）方式，也就是把用户和密码信息保存在数据库内部，由Neo4j自己完成身份校验。很多初次接触Neo4j的开发者在使用客户端驱动连接数据库时遇到Unauthorized错误，往往就是对这套认证机制不够了解造成的。本文将从原理、配置、用户管理和常见问题排查几个方面，系统讲解Neo4j的native authentication。
一、native authentication的工作原理
Neo4j的认证体系支持两种主要方式：native authentication（本地认证）和外部认证（如LDAP、Kerberos、SSO插件）。当没有配置任何外部认证插件时，Neo4j默认使用native authentication，这是最简单也最常用的方式。
native authentication的核心特点是：所有用户的账号信息，包括用户名、密码哈希、密码修改时间、是否 suspended（挂起）、是否需要修改密码等标记，全部存储在Neo4j内部的system数据库中。system数据库是Neo4j 4.0之后引入的一个特殊数据库，专门存放系统级元数据，普通用户无法直接用Cypher查询其中的认证数据，只有管理员权限才能操作。
当你用Bolt协议连接Neo4j并提交用户名密码时，服务端会在system数据库中查找该用户，校验密码哈希是否匹配。如果认证失败，客户端会收到一个Unauthorized的错误响应。整个校验过程完全在数据库实例内部完成，不依赖任何外部服务，这也是它被称为native（原生）的原因。相比之下，LDAP认证则是把密码校验委托给外部的目录服务，Neo4j本身只负责授权部分。
二、认证相关配置项详解
native authentication的开关由配置文件neo4j.conf中的dbms.security.auth_enabled参数控制。该参数默认值为true，即开启认证。只有在本地开发调试、或者前端已有网关做认证的场景下，才建议将其设为false来关闭认证。
# 开启认证（默认值，生产环境必须保持开启） dbms.security.auth_enabled=true # 关闭认证（仅限本地调试使用） dbms.security.auth_enabled=false
这个配置文件的位置取决于安装方式：tar包或zip包安装时位于conf目录下，例如Linux下通常是/usr/local/neo4j/conf/neo4j.conf，Windows下是D:\neo4j\conf\neo4j.conf；DEB或RPM包安装时则在/etc/neo4j/neo4j.conf。修改配置后必须重启Neo4j服务才能生效。
除了开关之外，native authentication还涉及一个重要的行为参数dbms.security.auth_lock_time。当某个用户连续多次（默认10次）认证失败后，账号会被临时锁定一段时间（默认5秒后自动解锁，可用dbms.security.auth_max_failed_attempts调整尝试次数）。这是为了防止暴力破解密码。如果你在测试中反复输错密码后发现突然连不上了，等几秒再试即可恢复。
三、用户管理常用操作
Neo4j 4.x和5.x使用Cypher的ADMIN命令来管理用户，这些命令需要在system数据库上执行。默认安装后会自带一个neo4j管理员账号，初始密码为neo4j，首次登录会被强制要求修改。
创建新用户使用CREATE USER语句，语法如下：
// 创建用户并设置密码，要求首次登录必须修改密码 CREATE USER app_user SET PASSWORD 'MySecret@123' CHANGE REQUIRED; // 创建用户但不强制修改密码 CREATE USER report_user SET PASSWORD 'Report@2024' CHANGE NOT REQUIRED;
密码在system数据库中是以哈希形式存储的，Neo4j默认使用SHA-256加盐哈希算法，不会保存明文。修改用户密码和状态可以使用ALTER USER：
// 修改用户密码 ALTER USER app_user SET PASSWORD 'NewPass@456'; // 挂起用户，禁止其登录，但不删除 ALTER USER app_user SET STATUS SUSPENDED; // 恢复用户 ALTER USER app_user SET STATUS ACTIVE;
查看当前所有用户可以用SHOW USERS命令，它会列出用户名、角色、状态和密码是否过期等标记。为用户分配权限则通过角色实现，例如GRANT ROLE reader TO app_user，Neo4j内置了reader、editor、publisher、architect、admin等常用角色，也可以使用CREATE ROLE自定义角色并精细控制到标签、关系类型和属性级别，这就是基于RBAC的权限模型。
四、常见问题与排查思路
最经典的报错是客户端连接时返回类似The client is unauthorized due to authentication failure的信息。遇到这类问题，首先确认dbms.security.auth_enabled的配置与客户端行为是否匹配：如果服务端关闭了认证而客户端传了密码，或者相反，都会导致连接异常。其次检查用户名密码拼写，注意密码是区分大小写的。
另一个高频问题是密码过期。当用户被设置为CHANGE REQUIRED或密码过期后，用旧密码可以连接成功，但执行任何查询前会收到提示要求先改密码。在驱动程序中处理这种情况，通常的做法是捕获该状态并用ALTER CURRENT USER SET PASSWORD ...完成修改，之后再继续正常业务。Cypher Shell命令行工具则会在交互模式下直接引导你输入新密码。
还有一个容易被忽略的场景是集群部署。Neo4j因果集群中，所有成员共享system数据库，因此在一个节点上创建的用户在整个集群范围内都有效，不需要在每个节点重复创建。但如果是从单机迁移到集群，务必确认旧实例的认证数据已经通过dump和load的方式迁移过来，否则之前创建的用户将全部丢失，只剩默认的neo4j账号。
最后提醒一点：关闭认证虽然能省去输入密码的麻烦，但会让数据库完全暴露。只要Neo4j端口（默认7474和7687）能被外部访问，任何人都可以读写甚至删除数据。生产环境中务必保持dbms.security.auth_enabled=true，修改默认密码，并遵循最小权限原则为不同应用分配独立的低权限账号。
Neo4j native authentication 用户认证修改时间：2026-09-05 06:38:29