> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-en/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-en/administration/security/enabling-authentication.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-en/administration/security/enabling-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.