# User Roles & Access Control

The Management Console implements role-based access control (RBAC) to ensure users can only access resources and perform actions permitted by their assigned roles or groups.

## Prerequisites

To enable role-based access control, you need to configure the following settings:

In the configuration:

* Set `global.authorization.enabled` to `true`
* Set `global.authentication.enabled` to `true`
* Configure OIDC settings for token validation in the `global.authentication` section
* Configure OPA authorization policies and related parameters in the `global.authorization` section
* Ensure your Okta instance has proper role/group configurations set up
* [Configure Okta Authentication](/ee-ai-en/ai-3.7/administration/overview/deployment.md)

### Example Configuration

```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:
              # groups config for gateway
          console:
            configMapName:
            filenames:
              - opa_auth_policy.rego
              - opa_data.yaml
            query: data.opa_auth_policy.allow
            groups:  
              # groups config for console
```

**Important Notes:** Ensure your Okta instance is properly configured with the necessary groups and roles. Each user should be assigned to appropriate groups that correspond to their access level in the system.

## Configuration Parameters

### Authentication

In the `global.authentication` section, the following key parameters are available:

* **`enabled`**: Whether to enable authentication.
* **`type`**: Authentication type, currently supports `oidc`.
* **`oidc`**: OIDC configuration parameters:
  * **`jwksUri`**: JWKS endpoint URI for obtaining public keys to verify JWT tokens.
  * **`jwksConfigMapName`**: ConfigMap name containing JWKS keys (optional, choose either this or jwksUri).
  * **`jwksFilename`**: JWKS filename.
  * **`aud`**: Audience field in JWT token for verifying the target audience of the token.
  * **`tid`**: Tenant ID for token validation in multi-tenant environments.
  * **`nbfCheck`**: Whether to validate the "nbf" (not before) claim in JWT tokens. When set to `true`, the system will reject tokens that are not yet valid (current time is before the "nbf" time). When set to `false`, the "nbf" claim validation is skipped. Default is `false`.
  * **`roleFieldName`**: Field name in JWT token containing user role information.
  * **`groupFieldName`**: Field name in JWT token containing user group information.

### Authorization

In the `global.authorization` section, the following key parameters are available:

* **`enabled`**: Whether to enable authorization control.
* **`type`**: Authorization type, currently supports `opa` (Open Policy Agent).
* **`opa`**: OPA configuration parameters:
  * **`superAdmin`**: List of super administrator roles with all permissions.
  * **`groupAdmin`**: List of group administrator roles with group-level management permissions.
  * **`allowApis`**: List of API endpoints that bypass authorization checks.
  * **`denyApis`**: List of API endpoints that are explicitly denied access.
  * **`components`**: Component-level configuration:
    * **`gateway`**: Authorization configuration for gateway component:
      * **`configMapName`**: ConfigMap name containing OPA policy files.
      * **`filenames`**: List of OPA policy files (such as `opa_auth_policy.rego`, `opa_data.yaml`).
      * **`query`**: OPA query string for policy evaluation (such as `data.opa_auth_policy.allow`).
      * **`groups`**: Group permission configuration for gateway.
    * **`console`**: Authorization configuration for console component:
      * **`configMapName`**: ConfigMap name containing OPA policy files.
      * **`filenames`**: List of OPA policy files.
      * **`query`**: OPA query string for policy evaluation.
      * **`groups`**: Group permission configuration for console.

### Console Group Permission Configuration

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

The `groups` field is a list where each entry defines which pages and components are accessible to specific roles within a group. If the default permission model [described below](#default-permission-model) meets your requirements, no additional configuration is needed. However, if you want to hide certain UI elements from specific roles within a group, you can add this configuration. See [Available disallowPages Options](#available-disallowpages-options) and [Available disallowComponents Options](#available-disallowcomponents-options) for configurable options.

### Gateway Group Permission Configuration

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

The `groups` field is a list where each entry defines which resource paths a group can or cannot access. Under the `allow` section, you define resource prefixes that can be accessed by APIs. Under the `deny` section, you define resource prefixes that cannot be accessed by specific APIs.

## Default Permission Model

The system provides three predefined user types with distinct access levels:

* **Super User**: Has unrestricted access to all pages and actions within the system.
* **Admin User**: Functions as a group-level administrator with read-only access to all data, but can only modify resources within their assigned group.
* **Regular Users**: By default, these users have no access and will be redirected to a 403 Forbidden page upon login.

For more flexible access control, you can implement custom authorization rules using OPA files. See the "Custom Authorization via OPA" section for details.

## Configuration Example

The following example demonstrates how to implement a role-based access control system with the following requirements:

* User roles are determined by the `role` field in the user's token (pre-configured in Okta)
* User groups are determined by the `group` field in the user's token (pre-configured in Okta)
* Super Users have full access to all pages and actions
* Search Admins can view all pages but are restricted to mounting and loading paths prefixed with `/search` and `/related-to-search`
* Recommend Admins can view all pages but are limited to operating on resources prefixed with `/recommend`
* All other roles are denied access and redirected to a 403 Forbidden page after login

### Configuration

```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
                  # If not defined, defaults to allowing all APIs with /search path
                  - prefix: /related-to-search
                    apis:
                      - /mount
                      - /load
            - group: Recommend
              allow:
                pathPrefixes:
                  - prefix: /recommend
          console:
            groups:
      #      You can leave this section empty if the default permission model is sufficient.
      #      If uncommented, Search Admin will not be able to view the mount page
      #      - group: Search
      #        role:
      #          - Admin
      #        pages:
      #          - /mount
```

## Custom Authorization via OPA

You can implement custom authorization rules by providing your own [OPA (Open Policy Agent)](https://www.openpolicyagent.org/docs/latest/) policy file (`.rego`). To use a custom policy:

1. Mount the file using a `ConfigMap`
2. List it in `filenames`
3. Set the appropriate `query`

You can examine and modify the default OPA files in the ConfigMap for both dashboard and gateway as needed.

Note: Dashboard OPA policies must return an object in the following format:

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

The dashboard uses this response to dynamically hide pages and UI elements based on user permissions.

### Available `disallowPages` Options:

```
/monitoring/overview
/monitoring/components
/storage
/operations/preload
/operations/free
/settings/resource-management
/settings/cache-eviction
/support/snapshot
/license
/documentation
* (all pages)
```

### Available `disallowComponents` Options:

* `createMount` – "Create" button on the Mount page
* `createQuota` – "Create" button on the Quota page
* `createTTL` – "Create" button on the TTL page
* `createPriority` – "Create" button on the Priority page
* `createJob` – "Create" button on Preload and Free pages
* `*` - All components

### Example Response

If the OPA evaluation returns:

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

The user will be unable to access the License page, and the "Create" button on the Mount page will be hidden.

If the OPA evaluation returns:

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

The user will be redirected to a 403 Forbidden page after login.


---

# 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-en/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.