> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/administration/security/enabling-authentication.md).

# 身份验证

Alluxio 提供了灵活的机制来验证用户和服务，确保只有授权的客户端才能访问您的数据。本指南涵盖了 Alluxio 中身份验证的核心概念，并提供了详细的配置说明。

支持以下接口的身份验证：

* S3 API
* Hadoop 文件系统 API
* 管理 REST API（通过网关）

## 核心概念：用户身份

无论使用何种身份验证方法，Alluxio 都通过三个核心属性来识别每个用户。这些属性从用户的凭据（如令牌）中提取，并由授权引擎（例如 OPA、Ranger）用于强制执行访问策略。

* **名称**：用户的唯一标识符。
* **组**：用户所属的一个或多个组。
* **角色**：分配给用户的一个或多个角色。

## 使用 OIDC 进行身份验证

OpenID Connect (OIDC) 是保护集群的推荐方法。它允许 Alluxio 与外部身份提供商 (IdP) 集成，以验证客户端提供的 JSON Web 令牌 (JWT)。

### OIDC 令牌验证

当 Alluxio 服务收到 OIDC 令牌时，它会执行多项验证检查：

1. **令牌签名**：根据您的 IdP 提供的 JSON Web 密钥集 (JWKS) 验证令牌的签名。
2. **令牌时间戳**：检查 `iat`（颁发于）和 `exp`（过期）时间戳，以确保令牌当前有效。还可以选择性地检查 `nbf`（不早于）时间戳。
3. **租户 ID**：如果已配置，则验证 `tid`（租户 ID）声明，以确保令牌属于正确的租户。
4. **受众**：如果已配置，则验证 `aud`（受众）声明，以确保令牌是为 Alluxio 颁发的。

### OIDC 配置

需要为每个需要身份验证的 Alluxio 组件单独配置。

**1. 网关身份验证**

在您的 `alluxio-cluster.yaml` 中配置网关以保护管理 REST API。

```yaml
global:
  authentication:
    enabled: true
    type: oidc # 目前仅支持 "oidc"
    oidc:
      # 选项 1：使用远程 JWKS 端点
      jwksUri: https://your-oidc-provider.com/.well-known/jwks.json

      # 选项 2：使用来自 ConfigMap 的本地 JWKS 文件
      # jwksConfigMapName: "jwks-configmap"
      # jwksFilename: "jwks.json"

      # --- 令牌验证声明 ---
      aud: "your-audience"
      tid: "your-tenant-id"
      nbfCheck: false

      # --- 用户属性映射 ---
      userFieldName: "sub"
      roleFieldName: "role"
      groupFieldName: "scp"
```

**2. S3 API 身份验证**

要保护 worker 上的 S3 API，请将以下内容添加到 `alluxio-cluster.yaml` 的 `properties` 部分。

```yaml
properties:
  # --- 启用 S3 API 身份验证 ---
  alluxio.worker.s3.api.enabled: "true"
  alluxio.worker.s3.authentication.enabled: "true"
  alluxio.worker.s3.authenticator.classname: "alluxio.s3.auth.TokenAuthenticator"

  # --- OIDC 配置 ---
  # 选项 1：使用远程 JWKS 端点
  alluxio.security.authentication.token.external.jwksaddr: "https://your-oidc-provider.com/.well-known/jwks.json"

  # 选项 2：使用挂载文件中的本地 JWKS 文件
  #alluxio.security.authentication.token.external.jwksaddr=file:///path/to/jwks.json

  # --- 用户属性映射 ---
  alluxio.security.authentication.token.assume.user.field: "sub"
  alluxio.security.authentication.token.assume.group.field: "scp"
  alluxio.security.authentication.token.assume.role.field: "role"

  # --- 可选的令牌验证声明 ---
  # alluxio.security.authentication.token.aud: "your-audience"
  # alluxio.security.authentication.token.tid: "your-tenant-id"
  # alluxio.security.authentication.token.nbf.check: "true"
```

**3. Hadoop 文件系统客户端身份验证**

要配置使用 Hadoop 文件系统 API 的客户端（例如 Spark、Presto），请将以下内容添加到客户端的 `alluxio-site.properties` 文件中。

```properties
# --- 为客户端启用 OIDC 身份验证 ---
alluxio.security.client.authentication.type=OIDC

# --- OIDC 配置 ---
# 选项 1：使用远程 JWKS 端点
alluxio.security.authentication.token.external.jwksaddr=https://your-oidc-provider.com/.well-known/jwks.json

# 选项 2：使用本地 JWKS 文件
#alluxio.security.authentication.token.external.jwksaddr=file:///path/to/jwks.json

# --- 用户属性映射 ---
alluxio.security.authentication.token.assume.user.field=sub
alluxio.security.authentication.token.assume.group.field=scp
alluxio.security.authentication.token.assume.role.field=role

# --- 可选的令牌验证声明 ---
# alluxio.security.authentication.token.aud=your-audience
# alluxio.security.authentication.token.tid=your-tenant-id
# alluxio.security.authentication.token.nbf.check=true
```

**向客户端提供令牌**

客户端应用程序必须提供 OIDC 令牌。这可以通过设置 `ALLUXIO_TOKEN` 环境变量来完成：

```shell
export ALLUXIO_TOKEN=<Your_OIDC_TOKEN>
```

或者，像 Spark 这样的框架可以通过其配置传递令牌：

```scala
SparkSession.builder.config("spark.hadoop.ALLUXIO_TOKEN", "<YOUR_OIDC_TOKEN>")
```