# 身份验证

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>")
```


---

# 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/administration/security/enabling-authentication.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.