# Enabling 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:

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