Authentication

Overview

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

  • user: 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 user, 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

authentication:
  enabled: false
  type: oidc # Supported types: "oidc"
  oidc:
    jwksUri:
    jwksConfigMapName: ""
    jwksFilename:
    aud: ""
    tid: ""
    nbfCheck: false
    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>

  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.

  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.

  6. roleFieldName: JWT token field containing user roles (default: roleFieldName).

  7. groupFieldName: JWT token field containing user groups (default: groupFieldName for scope).

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

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=scp
#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

alluxio.security.client.authentication.type=OIDC
alluxio.security.authentication.token.external.jwksaddr=
alluxio.security.authentication.token.assume.user.field=sub
alluxio.security.authentication.token.assume.group.field=scp
#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. If you do not set aud, tid, and nbf.check, the corresponding validations will not be performed.

Example:

export ALLUXIO_TOKEN=<Your_OIDC_TOKEN>
# or set ALLUXIO_TOKEN when using spark-submit
spark-submit --conf spark.executorEnv.ALLUXIO_TOKEN=<Your_OIDC_TOKEN> ...

Last updated