Authentication

Overview

Alluxio requires each user to have three core properties: name, group, and role. These attributes are essential for enforcing security policies and access controls throughout the system:

  • name: Unique identifier for the user (mapped from token field, e.g. sub).

  • group: User group(s), can be a list (e.g. from the scp claim).

  • role: User role(s), used for policy enforcement.

Policy enforcement:

  • The gateway uses group and role for policy enforcement via OPA (Open Policy Agent).

  • Ranger supports permission checks based on name, group, and role.

The group field can be a list, such as the scp (scope) claim in OIDC tokens.

Note: Only the S3 API, Hadoop FileSystem API and Management Restful API support authentication.

Authentication Mechanisms

Alluxio supports OIDC (OpenID Connect) integration for modern identity management.

Token Validation

When applications receive tokens after authentication, they validate the following aspects:

  • Token Signature: Validate the ID Token's signature using the JWKS certificates.

  • Token Timestamps:

    • iat: Issued at (epoch time)

    • nbf: Not valid before (epoch time) (if need check)

    • exp: Expiration (epoch time)

  • Tenant Validation: The tid claim (tenant ID) must match the expected tenant.

  • Audience Validation: The aud claim must match the expected audience.

Tokens should be rejected if any validation fails.

Configuration

Gateway Configuration

Add the following configuration to in alluxio-cluster.yaml:

global:
  authentication:
    enabled: false
    type: oidc # Supported types: "oidc"
    oidc:
      jwksUri:
      jwksConfigMapName: ""
      jwksFilename:
      aud: ""
      tid: ""
      nbfCheck: false
      userFieldName:
      roleFieldName:
      groupFieldName:

Configuration Parameters Explained:

  1. jwksUri: The URI for retrieving JSON Web Key Set (JWKS) certificates for token validation.

    • For remote JWKS endpoints: Use https://<jwks_uri> or http://<jwks_uri>

    Example:

    oidc:
        jwksUri: https://your-oidc-provider.com/.well-known/jwks.json
    
  2. jwksConfigMapName and jwksFileName: Required only when using local JWKS files.

    • Create a Kubernetes ConfigMap containing the JWKS file

    • Mount it to the gateway pod for token validation

    • Don't need to set jwksUri when using local files.

    Example:

     oidc:
       jwksConfigMapName: jwks-configmap
       jwksFilename: jwks.json
  3. aud (Audience): Expected audience claim in JWT tokens for validation. If not set, will not validate.

  4. tid (Tenant ID): Expected tenant claim in JWT tokens for multi-tenant environments. If not set, will not validate.

  5. nbfCheck: Whether to validate the "not before" (nbf) timestamp in tokens (default: false).

  6. userFieldName: The field in the JWT token to extract the username..

  7. roleFieldName: The field in the JWT token to extract the role.

  8. groupFieldName: The field in the JWT token to extract the group.

JWKS Configuration Examples:

Option 1: Remote JWKS Endpoint

authentication:
  enabled: true
  type: oidc
  oidc:
    jwksUri: https://your-oidc-provider.com/.well-known/jwks.json
    aud: "your-application-id"
    tid: "your-tenant-id"
    roleFieldName: role
    groupFieldName: scp

Option 2: Local JWKS File via ConfigMap

authentication:
  enabled: true
  type: oidc
  oidc:
    jwksConfigMapName: jwks-configmap
    jwksFilename: jwks.json

S3 API Configuration

Add the following configuration to the alluxio-cluster.yaml file:

properties:
  alluxio.worker.s3.api.enabled: "true"
  alluxio.worker.s3.authentication.enabled: "true"
  alluxio.worker.s3.authenticator.classname: "alluxio.s3.auth.TokenAuthenticator"
  alluxio.security.authentication.token.external.jwksaddr:
  alluxio.security.authentication.token.assume.user.field: "sub"
  alluxio.security.authentication.token.assume.group.field:
  alluxio.security.authentication.token.assume.role.field:
  #alluxio.security.authentication.token.aud:
  #alluxio.security.authentication.token.tid:
  #alluxio.security.authentication.token.nbf.check: "true"

Note: If you do not set aud, tid, and nbf.check, the corresponding validations will not be performed.

Hadoop FS Configuration

In your alluxio-site.properties file, add or modify the following properties:

alluxio.security.client.authentication.type=OIDC
alluxio.security.authentication.token.external.jwksaddr=
alluxio.security.authentication.token.assume.user.field=
alluxio.security.authentication.token.assume.group.field=
alluxio.security.authentication.token.assume.role.field=
#alluxio.security.authentication.token.aud=
#alluxio.security.authentication.token.tid=
#alluxio.security.authentication.token.nbf.check=true

Note: The ALLUXIO_TOKEN should be obtained from the environment or hadoop configuration. If you do not set aud, tid, and nbf.check, the corresponding validations will not be performed. If you use a local file to provide JWKS, prefix the file path with file://.

Example:

export ALLUXIO_TOKEN=<Your_OIDC_TOKEN>
# or set ALLUXIO_TOKEN when using sparksession
SparkSession.builder.config("spark.hadoop.ALLUXIO_TOKEN", <YOUR_OIDC_TOKEN>)

Last updated