neo4j-security-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use

适用场景

Creating, altering, suspending, or dropping users
Creating roles, granting/revoking role membership
Granting/denying/revoking graph, database, or DBMS privileges
Inspecting current privileges (
```
SHOW PRIVILEGES
```
)
Implementing property-level access control (read/write per property)
Setting up ABAC rules against OIDC claims
Referencing LDAP/SSO auth provider configuration

创建、修改、暂停或删除用户
创建角色、授予/撤销角色成员资格
授予/拒绝/撤销图、数据库或DBMS权限
检查当前权限（
```
SHOW PRIVILEGES
```
）
实现属性级访问控制（按属性设置读写权限）
基于OIDC声明配置ABAC规则
参考LDAP/SSO认证提供商配置

When NOT to Use

不适用场景

Writing Cypher queries against application data →
```
neo4j-cypher-skill
```
Cluster ops, backups, server config →
```
neo4j-cli-tools-skill
```
Driver connection setup →
```
neo4j-driver-*-skill
```

针对应用数据编写Cypher查询 → 使用
```
neo4j-cypher-skill
```
集群操作、备份、服务器配置 → 使用
```
neo4j-cli-tools-skill
```
驱动连接设置 → 使用
```
neo4j-driver-*-skill
```

MCP Write Gate — MANDATORY

MCP写入网关——强制要求

Before executing ANY of the following, show the planned command and wait for explicit confirmation:

```
CREATE USER
```
/
```
ALTER USER
```
/
```
DROP USER
```
```
CREATE ROLE
```
/
```
DROP ROLE
```
```
GRANT
```
/
```
DENY
```
/
```
REVOKE
```
(any privilege)
```
CREATE AUTH RULE
```
/
```
DROP AUTH RULE
```

Never auto-execute privilege changes. Show exact Cypher, annotate impact, get "yes".

在执行以下任何操作之前，必须展示计划执行的命令并等待明确确认：

```
CREATE USER
```
/
```
ALTER USER
```
/
```
DROP USER
```
```
CREATE ROLE
```
/
```
DROP ROLE
```
```
GRANT
```
/
```
DENY
```
/
```
REVOKE
```
（任何权限）
```
CREATE AUTH RULE
```
/
```
DROP AUTH RULE
```

切勿自动执行权限变更操作。需展示准确的Cypher语句，标注影响，等待用户回复"yes"后再执行。

Execution Context

执行上下文

All security Cypher runs against the system database:

cypher

// Neo4j auto-routes CREATE/ALTER/SHOW USER|ROLE|PRIVILEGE to system
// If using cypher-shell: cypher-shell -d system
// If using driver: use database="system"

所有安全相关的Cypher语句都需在system数据库上运行：

cypher

// Neo4j会自动将CREATE/ALTER/SHOW USER|ROLE|PRIVILEGE路由到system数据库
// 如果使用cypher-shell：cypher-shell -d system
// 如果使用驱动：指定use database="system"

1. User Management

1. 用户管理

Create user

创建用户

cypher

CREATE USER alice SET PASSWORD 'secret' CHANGE NOT REQUIRED;
// CHANGE REQUIRED (default): forces password change on first login
// CHANGE NOT REQUIRED: password valid immediately
// SET STATUS ACTIVE (default) | SUSPENDED

cypher

CREATE USER alice SET PASSWORD 'secret' CHANGE NOT REQUIRED;
// CHANGE REQUIRED（默认）：首次登录时强制修改密码
// CHANGE NOT REQUIRED：密码立即生效
// SET STATUS ACTIVE（默认）| SUSPENDED

Parameterised password (preferred in scripts)

参数化密码（脚本中推荐使用）

cypher

CREATE USER $username SET PASSWORD $password CHANGE NOT REQUIRED;

cypher

CREATE USER $username SET PASSWORD $password CHANGE NOT REQUIRED;

Alter user

修改用户

cypher

ALTER USER alice SET PASSWORD $newPw CHANGE NOT REQUIRED;
ALTER USER alice SET STATUS SUSPENDED;          // lock account
ALTER USER alice SET STATUS ACTIVE;             // unlock
ALTER USER alice SET HOME DATABASE mydb;        // default db on connect
ALTER USER alice IF EXISTS SET PASSWORD $pw;    // safe if missing

cypher

ALTER USER alice SET PASSWORD $newPw CHANGE NOT REQUIRED;
ALTER USER alice SET STATUS SUSPENDED;          // 锁定账户
ALTER USER alice SET STATUS ACTIVE;             // 解锁账户
ALTER USER alice SET HOME DATABASE mydb;        // 设置连接时的默认数据库
ALTER USER alice IF EXISTS SET PASSWORD $pw;    // 用户不存在时也能安全执行

Show users

查看用户

cypher

SHOW USERS YIELD username, roles, passwordChangeRequired, suspended, homeDatabase
WHERE suspended = false
RETURN username, roles ORDER BY username;

cypher

SHOW USERS YIELD username, roles, passwordChangeRequired, suspended, homeDatabase
WHERE suspended = false
RETURN username, roles ORDER BY username;

Drop user

删除用户

cypher

DROP USER alice IF EXISTS;

cypher

DROP USER alice IF EXISTS;

2. Role Management

2. 角色管理

Create / drop role

创建/删除角色

cypher

CREATE ROLE analyst;
CREATE ROLE analyst IF NOT EXISTS;
DROP ROLE analyst IF EXISTS;

cypher

CREATE ROLE analyst;
CREATE ROLE analyst IF NOT EXISTS;
DROP ROLE analyst IF EXISTS;

Assign / remove roles

分配/移除角色

cypher

GRANT ROLE analyst TO alice;
GRANT ROLE analyst, writer TO alice, bob;   // bulk
REVOKE ROLE analyst FROM alice;

cypher

GRANT ROLE analyst TO alice;
GRANT ROLE analyst, writer TO alice, bob;   // 批量操作
REVOKE ROLE analyst FROM alice;

Inspect roles

查看角色

cypher

SHOW ROLES YIELD role, member ORDER BY role;
SHOW ROLE analyst PRIVILEGES AS COMMANDS;   // returns runnable GRANT commands
SHOW POPULATED ROLES YIELD role;            // only roles with members

cypher

SHOW ROLES YIELD role, member ORDER BY role;
SHOW ROLE analyst PRIVILEGES AS COMMANDS;   // 返回可执行的GRANT命令
SHOW POPULATED ROLES YIELD role;            // 仅显示有成员的角色

3. Privilege Decision Table

3. 权限决策表

Goal	Command
Allow db connection	`GRANT ACCESS ON DATABASE mydb TO analyst`
Read all graph data	`GRANT MATCH {} ON GRAPH mydb ELEMENTS TO analyst`
Read specific label	`GRANT MATCH {*} ON GRAPH mydb NODES Person TO analyst`
Read specific rel type	`GRANT MATCH {*} ON GRAPH mydb RELATIONSHIPS KNOWS TO analyst`
Read one property	`GRANT READ {email} ON GRAPH mydb NODES Person TO analyst`
Traverse but hide properties	`GRANT TRAVERSE ON GRAPH mydb NODES Person TO analyst`
Write (create/set)	`GRANT WRITE ON GRAPH mydb TO writer`
Create nodes only	`GRANT CREATE ON GRAPH mydb NODES Person TO writer`
Delete nodes only	`GRANT DELETE ON GRAPH mydb NODES Person TO writer`
Execute procedure	`GRANT EXECUTE PROCEDURE apoc.* TO analyst`
Execute function	`GRANT EXECUTE USER DEFINED FUNCTION apoc.* TO analyst`
All on one db	`GRANT ALL ON DATABASE mydb TO dba`
Full DBMS admin	`GRANT ALL ON DBMS TO dba`
Manage users	`GRANT USER MANAGEMENT ON DBMS TO secadmin`
Manage roles	`GRANT ROLE MANAGEMENT ON DBMS TO secadmin`
Schema changes	`GRANT CREATE ELEMENT TYPES ON DATABASE mydb TO schemaadmin`

目标	命令
允许数据库连接	`GRANT ACCESS ON DATABASE mydb TO analyst`
读取所有图数据	`GRANT MATCH {} ON GRAPH mydb ELEMENTS TO analyst`
读取特定标签	`GRANT MATCH {*} ON GRAPH mydb NODES Person TO analyst`
读取特定关系类型	`GRANT MATCH {*} ON GRAPH mydb RELATIONSHIPS KNOWS TO analyst`
读取单个属性	`GRANT READ {email} ON GRAPH mydb NODES Person TO analyst`
遍历但隐藏属性	`GRANT TRAVERSE ON GRAPH mydb NODES Person TO analyst`
写入（创建/设置）	`GRANT WRITE ON GRAPH mydb TO writer`
仅创建节点	`GRANT CREATE ON GRAPH mydb NODES Person TO writer`
仅删除节点	`GRANT DELETE ON GRAPH mydb NODES Person TO writer`
执行存储过程	`GRANT EXECUTE PROCEDURE apoc.* TO analyst`
执行函数	`GRANT EXECUTE USER DEFINED FUNCTION apoc.* TO analyst`
单个数据库的所有权限	`GRANT ALL ON DATABASE mydb TO dba`
完整DBMS管理员权限	`GRANT ALL ON DBMS TO dba`
管理用户	`GRANT USER MANAGEMENT ON DBMS TO secadmin`
管理角色	`GRANT ROLE MANAGEMENT ON DBMS TO secadmin`
模式变更	`GRANT CREATE ELEMENT TYPES ON DATABASE mydb TO schemaadmin`

DENY overrides GRANT

DENY优先级高于GRANT

cypher

// Analyst can read Person but NOT the ssn property
GRANT MATCH {*} ON GRAPH mydb NODES Person TO analyst;
DENY  READ {ssn} ON GRAPH mydb NODES Person TO analyst;

cypher

// 分析师可以读取Person节点，但无法读取ssn属性
GRANT MATCH {*} ON GRAPH mydb NODES Person TO analyst;
DENY  READ {ssn} ON GRAPH mydb NODES Person TO analyst;

REVOKE removes a specific grant or deny

REVOKE移除特定的授予或拒绝规则

cypher

REVOKE GRANT READ {email} ON GRAPH mydb NODES Person FROM analyst;
REVOKE DENY  READ {ssn}   ON GRAPH mydb NODES Person FROM analyst;
REVOKE MATCH {*} ON GRAPH mydb NODES Person FROM analyst;  // removes both grant+deny

cypher

REVOKE GRANT READ {email} ON GRAPH mydb NODES Person FROM analyst;
REVOKE DENY  READ {ssn}   ON GRAPH mydb NODES Person FROM analyst;
REVOKE MATCH {*} ON GRAPH mydb NODES Person FROM analyst;  // 同时移除授予和拒绝规则

4. Common Role Patterns

4. 常见角色模式

Read-only analyst

只读分析师角色

cypher

CREATE ROLE analyst IF NOT EXISTS;
GRANT ACCESS            ON DATABASE mydb TO analyst;
GRANT MATCH {*}         ON GRAPH mydb ELEMENTS * TO analyst;
GRANT EXECUTE PROCEDURE apoc.* TO analyst;

cypher

CREATE ROLE analyst IF NOT EXISTS;
GRANT ACCESS            ON DATABASE mydb TO analyst;
GRANT MATCH {*}         ON GRAPH mydb ELEMENTS * TO analyst;
GRANT EXECUTE PROCEDURE apoc.* TO analyst;

Write role (no admin)

写入角色（无管理员权限）

cypher

CREATE ROLE writer IF NOT EXISTS;
GRANT ACCESS  ON DATABASE mydb TO writer;
GRANT MATCH {*} ON GRAPH mydb ELEMENTS * TO writer;
GRANT WRITE   ON GRAPH mydb TO writer;

cypher

CREATE ROLE writer IF NOT EXISTS;
GRANT ACCESS  ON DATABASE mydb TO writer;
GRANT MATCH {*} ON GRAPH mydb ELEMENTS * TO writer;
GRANT WRITE   ON GRAPH mydb TO writer;

Read-only on specific labels only

仅特定标签的只读角色

cypher

CREATE ROLE limited_reader IF NOT EXISTS;
GRANT ACCESS    ON DATABASE mydb TO limited_reader;
GRANT TRAVERSE  ON GRAPH mydb ELEMENTS * TO limited_reader;      // can traverse
GRANT MATCH {*} ON GRAPH mydb NODES Person TO limited_reader;    // Person props visible
GRANT MATCH {*} ON GRAPH mydb NODES Company TO limited_reader;   // Company props visible
// Other labels: traversable but properties invisible

cypher

CREATE ROLE limited_reader IF NOT EXISTS;
GRANT ACCESS    ON DATABASE mydb TO limited_reader;
GRANT TRAVERSE  ON GRAPH mydb ELEMENTS * TO limited_reader;      // 可遍历
GRANT MATCH {*} ON GRAPH mydb NODES Person TO limited_reader;    // Person节点属性可见
GRANT MATCH {*} ON GRAPH mydb NODES Company TO limited_reader;   // Company节点属性可见
// 其他标签：可遍历但属性不可见

DBA role (full admin)

DBA角色（完整管理员权限）

cypher

CREATE ROLE dba IF NOT EXISTS;
GRANT ALL ON DBMS     TO dba;
GRANT ALL ON DATABASE * TO dba;

cypher

CREATE ROLE dba IF NOT EXISTS;
GRANT ALL ON DBMS     TO dba;
GRANT ALL ON DATABASE * TO dba;

5. Property-Level Access Control (Enterprise)

5. 属性级访问控制（企业版）

Restrict read access to individual properties:

cypher

// Grant read on all Person props, then deny sensitive ones
GRANT MATCH {*}   ON GRAPH mydb NODES Person TO analyst;
DENY  READ {ssn, dateOfBirth} ON GRAPH mydb NODES Person TO analyst;

Property-based pattern matching (sub-graph access):

cypher

// Only see Person nodes where classification = 'public'
GRANT MATCH {*} ON GRAPH mydb
  FOR (n:Person) WHERE n.classification = 'public'
  TO analyst;

// Block access to classified nodes
DENY MATCH {*} ON GRAPH mydb
  FOR (n) WHERE n.classification <> 'UNCLASSIFIED'
  TO regularUsers;

Constraints:

```
FOR
```
pattern applies to read privileges only — not write
Each property-based privilege restricted by a single property
Performance overhead scales with number of rules;
```
TRAVERSE
```
rules cost more than
```
READ
```
Ensure the property used for rules cannot be modified by the restricted role

限制对单个属性的读取权限：

cypher

// 授予读取Person节点所有属性的权限，然后拒绝敏感属性
GRANT MATCH {*}   ON GRAPH mydb NODES Person TO analyst;
DENY  READ {ssn, dateOfBirth} ON GRAPH mydb NODES Person TO analyst;

基于属性的模式匹配（子图访问）：

cypher

// 仅能查看classification = 'public'的Person节点
GRANT MATCH {*} ON GRAPH mydb
  FOR (n:Person) WHERE n.classification = 'public'
  TO analyst;

// 阻止访问已分类的节点
DENY MATCH {*} ON GRAPH mydb
  FOR (n) WHERE n.classification <> 'UNCLASSIFIED'
  TO regularUsers;

约束条件：

```
FOR
```
模式仅适用于读取权限——不适用于写入权限
每个基于属性的权限只能由单个属性限制
性能开销随规则数量增加而增大；
```
TRAVERSE
```
规则的成本高于
```
READ
```
规则
确保用于规则的属性无法被受限角色修改

6. ABAC — Attribute-Based Access Control (Enterprise + OIDC)

6. ABAC——基于属性的访问控制（企业版 + OIDC）

ABAC grants roles dynamically from JWT/OIDC claims rather than explicit

GRANT ROLE ... TO user

ABAC通过JWT/OIDC声明动态授予角色，而非使用显式的

GRANT ROLE ... TO user

语句。

Prerequisites

前提条件

undefined

undefined

neo4j.conf

dbms.security.abac.authorization_providers=<oidc-provider-alias>

undefined

dbms.security.abac.authorization_providers=<oidc-provider-alias>

undefined

Create auth rule

创建认证规则

cypher

CREATE AUTH RULE salesRule
  SET CONDITION abac.oidc.user_attribute('department') = 'sales';

GRANT ROLE analyst TO AUTH RULE salesRule;

cypher

CREATE AUTH RULE salesRule
  SET CONDITION abac.oidc.user_attribute('department') = 'sales';

GRANT ROLE analyst TO AUTH RULE salesRule;

Compound conditions

复合条件

cypher

CREATE OR REPLACE AUTH RULE seniorRule
  SET CONDITION abac.oidc.user_attribute('department') = 'engineering'
    AND abac.oidc.user_attribute('level') >= 5;

GRANT ROLE senior_engineer TO AUTH RULE seniorRule;

cypher

CREATE OR REPLACE AUTH RULE seniorRule
  SET CONDITION abac.oidc.user_attribute('department') = 'engineering'
    AND abac.oidc.user_attribute('level') >= 5;

GRANT ROLE senior_engineer TO AUTH RULE seniorRule;

Manage auth rules

管理认证规则

cypher

SHOW AUTH RULES YIELD ruleName, condition, roles;
ALTER AUTH RULE salesRule SET ENABLED false;     // disable without dropping
RENAME AUTH RULE salesRule TO salesDeptRule;
DROP AUTH RULE salesDeptRule;
REVOKE ROLE analyst FROM AUTH RULE salesRule;

Notes:

Missing claims evaluate to NULL → rule condition false → role not granted
Rules apply immediately to existing sessions when claims are already loaded
ABAC works only with OIDC providers (not native or LDAP)

cypher

SHOW AUTH RULES YIELD ruleName, condition, roles;
ALTER AUTH RULE salesRule SET ENABLED false;     // 禁用规则但不删除
RENAME AUTH RULE salesRule TO salesDeptRule;
DROP AUTH RULE salesDeptRule;
REVOKE ROLE analyst FROM AUTH RULE salesRule;

注意事项：

缺失的声明会被评估为NULL → 规则条件不成立 → 角色不会被授予
当声明已加载时，规则会立即应用于现有会话
ABAC仅适用于OIDC提供商（不适用于本地认证或LDAP）

7. SHOW PRIVILEGES Patterns

7. SHOW PRIVILEGES使用模式

cypher

// All privileges in the system
SHOW PRIVILEGES YIELD *;

// Privileges for a specific user (as runnable commands)
SHOW USER alice PRIVILEGES AS COMMANDS;

// Privileges for a specific role
SHOW ROLE analyst PRIVILEGES YIELD privilege, action, resource, graph, segment;

// Find who has access to a database
SHOW PRIVILEGES YIELD *
WHERE graph = 'mydb'
RETURN role, action, resource, segment ORDER BY role;

// Find all DENY rules
SHOW PRIVILEGES YIELD *
WHERE access = 'DENIED'
RETURN role, action, resource, segment;

cypher

// 系统中的所有权限
SHOW PRIVILEGES YIELD *;

// 特定用户的权限（以可执行命令形式展示）
SHOW USER alice PRIVILEGES AS COMMANDS;

// 特定角色的权限
SHOW ROLE analyst PRIVILEGES YIELD privilege, action, resource, graph, segment;

// 查找谁有权限访问某个数据库
SHOW PRIVILEGES YIELD *
WHERE graph = 'mydb'
RETURN role, action, resource, segment ORDER BY role;

// 查找所有DENY规则
SHOW PRIVILEGES YIELD *
WHERE access = 'DENIED'
RETURN role, action, resource, segment;

8. Built-in Roles (do not drop)

8. 内置角色（请勿删除）

Role	Scope
`admin`	Full DBMS + all databases
`architect`	Schema changes + write on all databases
`publisher`	Write on all databases
`editor`	Write excluding schema changes
`reader`	Read-only on all databases
`public`	All users implicitly; default home database access

Assign built-in roles:

GRANT ROLE reader TO alice;

角色	作用范围
`admin`	完整DBMS权限 + 所有数据库
`architect`	所有数据库的模式变更 + 写入权限
`publisher`	所有数据库的写入权限
`editor`	写入权限（不包含模式变更）
`reader`	所有数据库的只读权限
`public`	所有用户默认继承；默认主数据库访问权限

分配内置角色：

GRANT ROLE reader TO alice;

9. Auth Provider Config Reference (operational — not Cypher)

9. 认证提供商配置参考（运维操作——非Cypher）

Native (default)

本地认证（默认）

dbms.security.auth_enabled=true
dbms.security.auth_max_failed_attempts=3    # lockout threshold

dbms.security.auth_enabled=true
dbms.security.auth_max_failed_attempts=3    # 锁定阈值

LDAP

dbms.security.auth_provider=ldap
dbms.security.ldap.host=ldap://ldap.example.com
dbms.security.ldap.authentication.mechanism=simple
dbms.security.ldap.authentication.user_dn_template=uid={0},ou=users,dc=example,dc=com
dbms.security.ldap.authorization.group_membership_attributes=memberOf
dbms.security.ldap.authorization.group_to_role_mapping=\
  "cn=analysts,ou=groups,dc=example,dc=com" = analyst;\
  "cn=admins,ou=groups,dc=example,dc=com"   = admin

dbms.security.auth_provider=ldap
dbms.security.ldap.host=ldap://ldap.example.com
dbms.security.ldap.authentication.mechanism=simple
dbms.security.ldap.authentication.user_dn_template=uid={0},ou=users,dc=example,dc=com
dbms.security.ldap.authorization.group_membership_attributes=memberOf
dbms.security.ldap.authorization.group_to_role_mapping=\
  "cn=analysts,ou=groups,dc=example,dc=com" = analyst;\
  "cn=admins,ou=groups,dc=example,dc=com"   = admin

OIDC / SSO (Okta, Auth0, Entra ID)

OIDC / SSO（Okta、Auth0、Entra ID）

dbms.security.oidc.<alias>.display_name=Okta
dbms.security.oidc.<alias>.auth_flow=pkce
dbms.security.oidc.<alias>.well_known_discovery_uri=https://example.okta.com/.well-known/openid-configuration
dbms.security.oidc.<alias>.audience=neo4j
dbms.security.oidc.<alias>.claims.username=email
dbms.security.oidc.<alias>.claims.groups=groups
dbms.security.oidc.<alias>.authorization.group_to_role_mapping=\
  "neo4j-analysts" = analyst;\
  "neo4j-admins"   = admin

Config changes require server restart. Roles referenced in mappings must exist in Neo4j (native or created via Cypher).

dbms.security.oidc.<alias>.display_name=Okta
dbms.security.oidc.<alias>.auth_flow=pkce
dbms.security.oidc.<alias>.well_known_discovery_uri=https://example.okta.com/.well-known/openid-configuration
dbms.security.oidc.<alias>.audience=neo4j
dbms.security.oidc.<alias>.claims.username=email
dbms.security.oidc.<alias>.claims.groups=groups
dbms.security.oidc.<alias>.authorization.group_to_role_mapping=\
  "neo4j-analysts" = analyst;\
  "neo4j-admins"   = admin

配置变更需要重启服务器。映射中引用的角色必须在Neo4j中存在（本地角色或通过Cypher创建的角色）。

Checklist — New Role Setup

清单——新角色设置步骤

Determine required operations: read / write / admin
Identify target database(s) and graph scope (all labels vs specific)
Identify any properties that must be hidden (→ DENY READ)
Create role:
```
CREATE ROLE ... IF NOT EXISTS
```
Grant ACCESS on database
Grant MATCH / TRAVERSE / WRITE as needed
Apply DENY for restricted properties
Run
```
SHOW ROLE ... PRIVILEGES AS COMMANDS
```
to verify
Assign to users:
```
GRANT ROLE ... TO ...
```
Test with
```
SHOW USER ... PRIVILEGES AS COMMANDS
```

Full privilege syntax → references/privilege-reference.md

确定所需操作：读取 / 写入 / 管理
确定目标数据库和图范围（所有标签 vs 特定标签）
确定必须隐藏的属性（→ 使用DENY READ）
创建角色：
```
CREATE ROLE ... IF NOT EXISTS
```
授予数据库访问权限
根据需要授予MATCH / TRAVERSE / WRITE权限
对受限属性应用DENY规则
执行
```
SHOW ROLE ... PRIVILEGES AS COMMANDS
```
验证权限
分配给用户：
```
GRANT ROLE ... TO ...
```
使用
```
SHOW USER ... PRIVILEGES AS COMMANDS
```
测试权限

完整权限语法 → references/privilege-reference.md