Source: https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/schema-access-control/
Documentation version: v5.3.2

# Schema 访问控制

访问非默认 Schema 中的资源，普通用户需要两类权限：Schema 的`USAGE`，以及操作目标资源所需的权限。

## 前提条件

- 示例用户`alice`已创建、已加入服务组且具有`CONNECT`。
- `/finance/orders`已存在；使用其他资源时，替换示例路径。
- 使用具有`ADMIN`角色的账号连接 Graph 服务执行授权。用户创建和邀请步骤见[为用户配置访问权限](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/configure-user-access/)。

## 授权示例

例如，要允许`alice`查询图`/finance/orders`，需要同时授予以下权限：

````
'''
GRANT USAGE ON SCHEMA /finance TO USER alice
'''

'''
GRANT MATCH ON GRAPH /finance/orders TO USER alice
'''

````

- `USAGE`允许`alice`查看和使用 Schema `/finance`。
- `MATCH`允许`alice`查询图`/finance/orders`。

只有`USAGE`时，`alice`不能查询图；只有`MATCH`时，`alice`也不能进入 Schema `/finance`。

## 权限检查规则

对 Schema 中的对象执行操作，用户必须同时具备：

- 对该对象所属 Schema 的访问权限，即系统自动提供或通过授权获得的`USAGE`。
- 目标操作所需的权限。

目标操作所需的权限可以直接授予在目标对象上，也可以来自上级资源。例如，Schema 上的`MATCH ANY GRAPH`允许查询该 Schema 中的所有图。完整的适用范围请参见[权限参考](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/privilege-reference/)。

同级对象类型之间没有权限依赖。例如，用户具有`/finance`的`USAGE`和图`/finance/orders`的`MATCH`后即可查询该图，无需再获得该图所使用图类型的权限。

Note

Schema 访问控制适用于 Schema 及其中的对象，不适用于临时图、内置 Procedure 和内置 Function。

## 获取 Schema 访问权限

用户可以通过系统规则自动获得 Schema 访问权限，也可以通过`USAGE`授权获得访问权限：

 | 用户或条件 | Schema 访问权限的来源
 | 拥有`ADMIN`角色的用户 | 自动拥有所有 Schema 的访问权限。
 | 当前 Schema Owner（所有者） | 自动拥有该 Schema 的访问权限。
 | 访问`/default_schema`的任意用户 | 自动拥有`/default_schema`的访问权限。
 | 直接或通过角色获得`USAGE`的用户 | 拥有指定 Schema 的访问权限。

以下设置不会自动授予父级 Schema 的访问权限：

- 将 Schema 或其中的图设置为用户的主 Schema、主图。
- 成为 Schema 中某个图、图类型、UDP 或 UDF 的 Owner。
- 仅获得服务组的`CONNECT`。

## 授予 Schema 访问权限

可以将`USAGE`直接授予用户：

````
GRANT USAGE ON SCHEMA /finance TO USER alice

````

为了简化权限管理，建议将`USAGE`和目标操作所需的权限授予角色，再将角色授予用户：

````
'''
CREATE ROLE IF NOT EXISTS finance_reader
'''

'''
GRANT USAGE ON SCHEMA /finance TO ROLE finance_reader
'''

'''
GRANT MATCH ON GRAPH /finance/orders TO ROLE finance_reader
'''

'''
GRANT ROLE finance_reader TO USER alice
'''

````

在本示例中，`alice`可以访问`/finance`并查询`/finance/orders`，无需拥有该图所使用图类型的权限。如果角色只有`USAGE`，`alice`可以选择`/finance`，但不能查询`orders`。

只有 Schema Owner 和拥有`ADMIN`角色的用户可以授予或撤销该 Schema 的`USAGE`。完整的用户授权流程请参见[为用户配置访问权限](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/configure-user-access/)，命令语法请参见 [GRANT](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/grant-privilege/) 和 [REVOKE](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/revoke-privilege/)。

## 撤销 Schema 访问权限

撤销直接授予用户的访问权限：

````
REVOKE USAGE ON SCHEMA /finance FROM USER alice

````

撤销通过角色提供的访问权限：

````
REVOKE USAGE ON SCHEMA /finance FROM ROLE finance_reader

````

如果用户无法通过其他方式获得 Schema 访问权限，权限变更生效后会发生以下变化：

- 受影响的用户不再看到该 Schema。
- 现有会话不能继续访问该 Schema 及其中的对象。
- `SHOW CURRENT_SCHEMA`和`SHOW CURRENT_GRAPH`不再显示会话中不可访问的 Schema 和图。
- Schema 中对象的权限和 Owner 信息保持不变。
- 重新授予`USAGE`即可恢复 Schema 访问权限，无需重新授予未发生变化的对象权限。

## 访问权限变更

### Schema Owner

Schema Owner 自动获得的访问权限不能被撤销。

执行`ALTER OWNER SCHEMA`后：

- 新 Owner 自动获得 Schema 访问权限。
- 原 Owner 失去由 Schema Owner 身份提供的访问权限。此前直接或通过角色获得的`USAGE`仍然有效；如果没有此类授权，则必须获得`USAGE`才能继续访问该 Schema。
- 下级对象的 Owner 和权限不受影响。

更多信息，请参见 [ALTER OWNER](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/alter-owner/)。

### 主 Schema 和主图

主 Schema 和主图是用户建立连接后默认使用的 Schema 和图。将某个 Schema 设置为用户的主 Schema，或将某个图设置为用户的主图，都不会授予该用户父级 Schema 的`USAGE`。

用户失去主 Schema 的全部访问权限后：

- 用户无法通过新会话或现有会话访问该主 Schema 或主图。
- `SESSION RESET SCHEMA`会清空当前 Schema，而不是将其重置为无权访问的主 Schema。
- 如果主图位于无权访问的 Schema 中，`SESSION RESET GRAPH`会清空当前图。
- 用户可以显式切换到`/default_schema`：

````
SESSION SET SCHEMA /default_schema

````

管理员也可以为用户设置其他可访问的主 Schema。更多信息，请参见 [ALTER USER](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/alter-user/)。

### `/default_schema`

所有用户都隐式拥有`/default_schema`的`USAGE`，不能显式授予或撤销该权限：

````
'''
GRANT USAGE ON SCHEMA /default_schema TO USER alice
'''

'''
REVOKE USAGE ON SCHEMA /default_schema FROM USER alice
'''

````

以上命令都会返回权限不足错误。