# 用户角色和访问控制

管理控制台实施基于角色的访问控制（RBAC），以确保用户只能访问其分配的角色或组允许的资源并执行相应的操作。

## 先决条件

要启用基于角色的访问控制，您需要配置以下设置：

在配置中：

* 将 `global.authorization.enabled` 设置为 `true`
* 将 `global.authentication.enabled` 设置为 `true`
* 在 `global.authentication` 部分配置 OIDC 设置以进行令牌验证
* 在 `global.authorization` 部分配置 OPA 授权策略和相关参数
* 确保您的 Okta 实例已设置好适当的角色/组配置
* [配置 Okta 身份验证](/ee-ai-cn/ai-3.7/administration/overview/deployment.md)

### 配置示例

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  global:
    authentication:
      enabled: true
      type: oidc
      oidc:
        jwksUri:
        jwksConfigMapName:
        jwksFilename:
        aud:
        tid:
        nbfCheck: false
        roleFieldName: roleFieldName
        groupFieldName: groupFieldName

    authorization:
      enabled: true
      type: opa
      opa:
        superAdmin:
        groupAdmin:
        allowApis:
        denyApis:
        components:
          gateway:
            configMapName:
            filenames:
              - opa_auth_policy.rego
              - opa_data.yaml
            query: data.opa_auth_policy.allow
            groups:
              # 网关的组配置
          console:
            configMapName:
            filenames:
              - opa_auth_policy.rego
              - opa_data.yaml
            query: data.opa_auth_policy.allow
            groups:  
              # 控制台的组配置
```

**重要提示：** 确保您的 Okta 实例已正确配置了必要的组和角色。每个用户都应分配到与其在系统中的访问级别相对应的适当组。

## 配置参数

### 身份验证

在 `global.authentication` 部分，提供以下关键参数：

* **`enabled`**：是否启用身份验证。
* **`type`**：身份验证类型，当前支持 `oidc`。
* **`oidc`**：OIDC 配置参数：
  * **`jwksUri`**：用于获取公钥以验证 JWT 令牌的 JWKS 端点 URI。
  * **`jwksConfigMapName`**：包含 JWKS 密钥的 ConfigMap 名称（可选，选择此项或 jwksUri）。
  * **`jwksFilename`**：JWKS 文件名。
  * **`aud`**：JWT 令牌中的受众字段，用于验证令牌的目标受众。
  * **`tid`**：用于在多租户环境中进行令牌验证的租户 ID。
  * **`nbfCheck`**：是否验证 JWT 令牌中的 "nbf"（not before）声明。当设置为 `true` 时，系统将拒绝尚未生效的令牌（当前时间在 "nbf" 时间之前）。当设置为 `false` 时，将跳过 "nbf" 声明验证。默认为 `false`。
  * **`roleFieldName`**：JWT 令牌中包含用户角色信息的字段名称。
  * **`groupFieldName`**：JWT 令牌中包含用户组信息的字段名称。

### 授权

在 `global.authorization` 部分，提供以下关键参数：

* **`enabled`**：是否启用授权控制。
* **`type`**：授权类型，当前支持 `opa`（Open Policy Agent）。
* **`opa`**：OPA 配置参数：
  * **`superAdmin`**：具有所有权限的超级管理员角色列表。
  * **`groupAdmin`**：具有组级别管理权限的组管理员角色列表。
  * **`allowApis`**：绕过授权检查的 API 端点列表。
  * **`denyApis`**：明确拒绝访问的 API 端点列表。
  * **`components`**：组件级配置：
    * **`gateway`**：网关组件的授权配置：
      * **`configMapName`**：包含 OPA 策略文件的 ConfigMap 名称。
      * **`filenames`**：OPA 策略文件列表（如 `opa_auth_policy.rego`、`opa_data.yaml`）。
      * **`query`**：用于策略评估的 OPA 查询字符串（如 `data.opa_auth_policy.allow`）。
      * **`groups`**：网关的组权限配置。
    * **`console`**：控制台组件的授权配置：
      * **`configMapName`**：包含 OPA 策略文件的 ConfigMap 名称。
      * **`filenames`**：OPA 策略文件列表。
      * **`query`**：用于策略评估的 OPA 查询字符串。
      * **`groups`**：控制台的组权限配置。

### 控制台组权限配置

```yaml
groups:
- group: some-group
  role:
  - some-role
  pages:
  - /some-page
  components:
  - some-component
```

`groups` 字段是一个列表，其中每个条目定义了组内特定角色可以访问哪些页面和组件。如果x[下述](#mo-ren-quan-xian-mo-xing)默认权限模型满足您的要求，则无需额外配置。但是，如果您希望对组内特定角色隐藏某些 UI 元素，可以添加此配置。有关可配置选项，请参阅[可用的 disallowPages 选项](#ke-yong-de-disallowpages-xuan-xiang)和[可用的 disallowComponents 选项](#ke-yong-de-disallowcomponents-xuan-xiang)。

### 网关组权限配置

```yaml
groups:
- group: some-group
  allow:
    pathPrefixes:
      - prefix: /some-path
        apis:
          - /some-api
  deny:
    pathPrefixes:
      - prefix: /some-path
        apis:
          - /some-api
```

`groups` 字段是一个列表，其中每个条目定义了组可以或不可以访问哪些资源路径。在 `allow` 部分，您定义了 API 可以访问的资源前缀。在 `deny` 部分，您定义了特定 API 不可访问的资源前缀。

## 默认权限模型

系统提供三种预定义的用户类型，具有不同的访问级别：

* **超级用户**：拥有对系统内所有页面和操作的无限制访问权限。
* **管理员用户**：作为组级别管理员，对所有数据具有只读访问权限，但只能修改其分配组内的资源。
* **普通用户**：默认情况下，这些用户没有访问权限，登录后将被重定向到 403 禁止访问页面。

要实现更灵活的访问控制，您可以使用 OPA 文件实施自定义授权规则。有关详细信息，请参阅“通过 OPA 进行自定义授权”部分。

## 配置示例

以下示例演示了如何实施一个基于角色的访问控制系统，满足以下要求：

* 用户角色由用户令牌中的 `role` 字段确定（已在 Okta 中预配置）
* 用户组由用户令牌中的 `group` 字段确定（已在 Okta 中预配置）
* 超级用户拥有对所有页面和操作的完全访问权限
* 搜索管理员可以查看所有页面，但仅限于挂载和加载以 `/search` 和 `/related-to-search` 为前缀的路径
* 推荐管理员可以查看所有页面，但仅限于操作以 `/recommend` 为前缀的资源
* 所有其他角色将被拒绝访问，并在登录后重定向到 403 禁止访问页面

### 配置

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  global:
    authentication:
      enabled: true
      type: oidc
      oidc:
        jwksUri: https://my-okta.okta.com/oauth2/default/v1/keys
        roleFieldName: role
        groupFieldName: group

    authorization:
      enabled: true
      type: opa
      opa:
        superAdmin: ['Super', 'SuperUser']
        groupAdmin: ['Admin', 'Team-Admin']
        allowApis: ['/api/allow/all']
        denyApis: ['/api/deny/all']
        components:
          gateway:
            groups:  
            - group: Search
              allow:
                pathPrefixes:
                  - prefix: /search
                  # 如果未定义，则默认为允许所有带有 /search 路径的 API
                  - prefix: /related-to-search
                    apis:
                      - /mount
                      - /load
            - group: Recommend
              allow:
                pathPrefixes:
                  - prefix: /recommend
          console:
            groups:
      #      如果默认权限模型足够，您可以将此部分留空。
      #      如果取消注释，搜索管理员将无法查看挂载页面
      #      - group: Search
      #        role:
      #          - Admin
      #        pages:
      #          - /mount
```

## 通过 OPA 进行自定义授权

您可以通过提供自己的 [OPA (Open Policy Agent)](https://www.openpolicyagent.org/docs/latest/) 策略文件（`.rego`）来实施自定义授权规则。要使用自定义策略：

1. 使用 `ConfigMap` 挂载文件
2. 在 `filenames` 中列出它
3. 设置适当的 `query`

您可以根据需要检查和修改仪表板和网关的 ConfigMap 中的默认 OPA 文件。

注意：仪表板 OPA 策略必须返回以下格式的对象：

```json
{
  "disallowPages": [],
  "disallowComponents": []
}
```

仪表板使用此响应根据用户权限动态隐藏页面和 UI 元素。

### 可用的 `disallowPages` 选项：

```
/monitoring/overview
/monitoring/components
/storage
/operations/preload
/operations/free
/settings/resource-management
/settings/cache-eviction
/support/snapshot
/license
/documentation
* (所有页面)
```

### 可用的 `disallowComponents` 选项：

* `createMount` – 挂载页面上的“创建”按钮
* `createQuota` – 配额页面上的“创建”按钮
* `createTTL` – TTL 页面上的“创建”按钮
* `createPriority` – 优先级页面上的“创建”按钮
* `createJob` – 预加载和释放页面上的“创建”按钮
* `*` - 所有组件

### 响应示例

如果 OPA 评估返回：

```json
{
  "disallowPages": ["/license"],
  "disallowComponents": ["createMount"]
}
```

用户将无法访问许可证页面，并且挂载页面上的“创建”按钮将被隐藏。

如果 OPA 评估返回：

```json
{
  "disallowPages": ["*"],
  "disallowComponents": ["*"]
}
```

用户登录后将被重定向到 403 禁止访问页面。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ai-3.7/administration/overview/user-roles-access-control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.