Home

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.

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.

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.

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

export ALLUXIO_TOKEN=<Your_OIDC_TOKEN>

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

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

Last updated