# Authentication

Alluxio provides flexible mechanisms to authenticate users and services, ensuring that only authorized clients can access your data. This guide covers the core concepts of authentication in Alluxio and provides detailed instructions for configuring it.

Authentication is supported for the following interfaces:

* S3 API
* Hadoop FileSystem API
* Management REST API (via the Gateway)

## Core Concepts: User Identity

Regardless of the authentication method, Alluxio identifies every user by three core attributes. These are extracted from the user's credentials (like a token) and used by authorization engines (e.g., OPA, Ranger) to enforce access policies.

* **Name**: A unique identifier for the user.
* **Group**: One or more groups the user belongs to.
* **Role**: One or more roles assigned to the user.

## Authentication with OIDC

OpenID Connect (OIDC) is the recommended method for securing your cluster. It allows Alluxio to integrate with an external Identity Provider (IdP) to validate JSON Web Tokens (JWTs) presented by clients.

### OIDC Token Validation

When an Alluxio service receives an OIDC token, it performs several validation checks:

1. **Token Signature**: The token's signature is verified against the JSON Web Key Set (JWKS) provided by your IdP.
2. **Token Timestamps**: The `iat` (issued at) and `exp` (expiration) timestamps are checked to ensure the token is currently valid. The `nbf` (not before) timestamp can also be checked optionally.
3. **Tenant ID**: If configured, the `tid` (tenant ID) claim is validated to ensure the token belongs to the correct tenant.
4. **Audience**: If configured, the `aud` (audience) claim is validated to ensure the token was issued for Alluxio.

### Configuration for OIDC

Authentication is configured separately for each Alluxio component that requires it.

**1. Gateway Authentication**

Configure the Gateway in your `alluxio-cluster.yaml` to secure the management REST API.

```yaml
global:
  authentication:
    enabled: true
    type: oidc # Currently, only "oidc" is supported
    oidc:
      # Option 1: Use a remote JWKS endpoint
      jwksUri: https://your-oidc-provider.com/.well-known/jwks.json

      # Option 2: Use a local JWKS file from a ConfigMap
      # jwksConfigMapName: "jwks-configmap"
      # jwksFilename: "jwks.json"

      # --- Token Validation Claims ---
      aud: "your-audience"
      tid: "your-tenant-id"
      nbfCheck: false

      # --- User Attribute Mapping ---
      userFieldName: "sub"
      roleFieldName: "role"
      groupFieldName: "scp"
```

**2. S3 API Authentication**

To secure the S3 API on the workers, add the following to the `properties` section of your `alluxio-cluster.yaml`.

```yaml
properties:
  # --- Enable S3 API Authentication ---
  alluxio.worker.s3.api.enabled: "true"
  alluxio.worker.s3.authentication.enabled: "true"
  alluxio.worker.s3.authenticator.classname: "alluxio.s3.auth.TokenAuthenticator"

  # --- OIDC Configuration ---
  # Option 1: Use a remote JWKS endpoint
  alluxio.security.authentication.token.external.jwksaddr: "https://your-oidc-provider.com/.well-known/jwks.json"

  # Option 2: Use a local JWKS file from a mounted file
  #alluxio.security.authentication.token.external.jwksaddr=file:///path/to/jwks.json

  # --- User Attribute Mapping ---
  alluxio.security.authentication.token.assume.user.field: "sub"
  alluxio.security.authentication.token.assume.group.field: "scp"
  alluxio.security.authentication.token.assume.role.field: "role"

  # --- Optional Token Validation Claims ---
  # alluxio.security.authentication.token.aud: "your-audience"
  # alluxio.security.authentication.token.tid: "your-tenant-id"
  # alluxio.security.authentication.token.nbf.check: "true"
```

**3. Hadoop FileSystem Client Authentication**

To configure clients using the Hadoop FileSystem API (e.g., Spark, Presto), add the following to the client-side `alluxio-site.properties` file.

```properties
# --- Enable OIDC Authentication for the Client ---
alluxio.security.client.authentication.type=OIDC

# --- OIDC Configuration ---
# Option 1: Use a remote JWKS endpoint
alluxio.security.authentication.token.external.jwksaddr=https://your-oidc-provider.com/.well-known/jwks.json

# Option 2: Use a local JWKS file
#alluxio.security.authentication.token.external.jwksaddr=file:///path/to/jwks.json

# --- User Attribute Mapping ---
alluxio.security.authentication.token.assume.user.field=sub
alluxio.security.authentication.token.assume.group.field=scp
alluxio.security.authentication.token.assume.role.field=role

# --- Optional Token Validation Claims ---
# alluxio.security.authentication.token.aud=your-audience
# alluxio.security.authentication.token.tid=your-tenant-id
# alluxio.security.authentication.token.nbf.check=true
```

**Providing the Token to Clients**

The client application must provide the OIDC token. This can be done by setting the `ALLUXIO_TOKEN` environment variable:

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

Alternatively, frameworks like Spark can pass the token through their configuration:

```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-en/ai-3.8-15.1.x/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.