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
androle
for policy enforcement via OPA (Open Policy Agent).Ranger supports permission checks based on
name
,group
, androle
.
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:
jwksUri: The URI for retrieving JSON Web Key Set (JWKS) certificates for token validation.
For remote JWKS endpoints: Use
https://<jwks_uri>
orhttp://<jwks_uri>
Example:
oidc: jwksUri: https://your-oidc-provider.com/.well-known/jwks.json
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
aud (Audience): Expected audience claim in JWT tokens for validation. If not set, will not validate.
tid (Tenant ID): Expected tenant claim in JWT tokens for multi-tenant environments. If not set, will not validate.
nbfCheck: Whether to validate the "not before" (
nbf
) timestamp in tokens (default:false
).userFieldName: The field in the JWT token to extract the username..
roleFieldName: The field in the JWT token to extract the role.
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
, andnbf.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 setaud
,tid
, andnbf.check
, the corresponding validations will not be performed. If you use a local file to provide JWKS, prefix the file path withfile://
.
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