This document describes the following security related features in Alluxio.
- User Authentication:
Alluxio filesystem will differentiate users accessing the service
when the authentication mode is
alluxio.security.authentication.type=SIMPLE). Alluxio also supports other authentication modes like
NOSASLwhich ignores the difference among users. Having authentication mode to be
SIMPLEis required for authorization.
- User Authorization:
Alluxio filesystem will grant or deny user access based on the requesting user and
the POSIX permissions model of the files or directories to access,
alluxio.security.authorization.permission.enabled=true. Note that, authentication cannot be
NOSASLas authorization requires user information.
- Impersonation: Alluxio supports user impersonation so one user can access Alluxio on the behalf of another user. This can be useful if an Alluxio client is part of a service which provides access to Alluxio for many different users.
- Auditing: If
alluxio.master.audit.logging.enabled=true, Alluxio file system maintains an audit log for user accesses to file metadata.
See Security specific configuration for different security properties.
The authentication protocol is determined by the configuration property
with a default value of
Authentication is enabled when the authentication type is
A client must identify itself with a username to the Alluxio service.
If the property
alluxio.security.login.username is set on the client, its value will be used as
the login user, otherwise, the login user is inferred from the operating system.
The provided user information is attached to the corresponding metadata when the client creates
directories or files.
Authentication is disabled when the authentication type is
Alluxio service will ignore the user of the client and no user information will be attached to the corresponding metadata when the client creates directories or files.
Authentication is enabled when the authentication type is
Alluxio clients retrieves user information via the class provided by the
The specified class must implement
This mode is currently experimental and should only be used in tests.
The Alluxio file system implements a permissions model similar to the POSIX permissions model.
Each file and directory is associated with:
- An owner, which is the user of the client process to create the file or directory.
- A group, which is the group fetched from user-groups-mapping service. See User group mapping.
- Permissions, which consist of three parts:
- Owner permission defines the access privileges of the file owner
- Group permission defines the access privileges of the owning group
- Other permission defines the access privileges of all users that are not in any of above two classes
Each permission has three actions:
- read (r)
- write (w)
- execute (x)
- Read permissions are required to read files
- Write permission are required to write files
- Read permissions are required to list its contents
- Write permissions are required to create, rename, or delete files or directories under it
- Execute permissions are required to access a child of the directory
The output of the
ls shell command when authorization is enabled is:
./bin/alluxio fs ls / drwxr-xr-x jack staff 24 PERSISTED 11-20-2017 13:24:15:649 DIR /default_tests_files -rw-r--r-- jack staff 80 NOT_PERSISTED 11-20-2017 13:24:15:649 100% /default_tests_files/BASIC_CACHE_PROMOTE_MUST_CACHE
User group mapping
For a given user, the list of groups is determined by a group mapping service, configured by
alluxio.security.group.mapping.class property, with a default implementation of
This implementation executes the
groups shell command to fetch the group memberships of the given user.
The user group mapping is cached, with an expiration period configured by the
alluxio.security.group.mapping.cache.timeout property, with a default value of
If set to a value of
0, caching is disabled.
Alluxio has super user, a user with special privileges typically needed to administer and maintain the system.
alluxio.security.authorization.permission.supergroup property defines a super group.
Any users belong to this group are also super users.
Initialized directory and file permissions
When a file is created, it is initially assigned fully opened permissions of
666 by default.
Similarly, a directory is initially assigned with
A umask is applied on the initial permissions; this is configured by the
alluxio.security.authorization.permission.umask property, with a default of
Without any property modifications, files and directories are created with
755 permissions respectively.
Update directory and file permission model
The owner, group, and permissions can be changed by two ways:
- User application invokes the
- CLI command in shell. See chown, chgrp, chmod.
The owner attribute can only be changed by a super user. The group and permission attributes can be changed by a super user or the owner.
Alluxio supports user impersonation in order for a user to access Alluxio on the behalf of another user. This can be useful if an Alluxio client is part of a service which provides access to Alluxio for different users. In this scenario, the Alluxio client is configured to connect to Alluxio servers as a connection user, but act on behalf of, or impersonate, other users. In order to configure Alluxio for impersonation, both client and master configurations are required.
To enable a particular user to impersonate other users, set the
alluxio.master.security.impersonation.<USERNAME>.users property, where
<USERNAME> is the name
of the connection user.
The property value is a comma-separated list of users that
<USERNAME> is allowed to impersonate.
The wildcard value
* can be used to indicate the user can impersonate any other user.
alluxio.master.security.impersonation.alluxio_user.users=user1,user2means the connection user
alluxio_useris allowed to impersonate
alluxio.master.security.impersonation.client.users=*means the connection user
clientis allowed to impersonate any user.
To enable a particular user to impersonate other groups, set the
alluxio.master.security.impersonation.<USERNAME>.groups property, where again
the name of the connection user.
Similar to the above, the value is a comma-separated list of groups and the wildcard value
can be used to indicate all groups.
alluxio.master.security.impersonation.alluxio_user.groups=group1,group2means the connection user
alluxio_useris allowed to impersonate any users from groups
alluxio.master.security.impersonation.client.groups=*means the connection user
clientis allowed to impersonate users from any group.
In summary, impersonation of a given user is only enabled if at least one of the two impersonation properties are be set; setting both are allowed for the same user.
After enabling impersonation on the master for a given user,
the client must indicate which user it wants to impersonate.
This is configured by the
If the property is set to an empty string or
_NONE_, impersonation is disabled.
If the property is set to
_HDFS_USER_, the Alluxio client will impersonate as the same user as
the HDFS client when using the Hadoop compatible client.
This property can also be set to a particular string to indicate a user name.
Alluxio supports audit logging to allow system administrators to track users’ access to file metadata.
The audit log file at
master_audit.log contains entries corresponding to file metadata access operations.
The format of Alluxio audit log entry is shown in the table below:
|succeeded||True if the command has succeeded. To succeed, it must also have been allowed.|
|allowed||True if the command has been allowed. Note that a command can still fail even if it has been allowed.|
|ugi||User group information, including username, primary group, and authentication type.|
|ip||Client IP address.|
|cmd||Command issued by the user.|
|src||Path of the source file or directory.|
|dst||Path of the destination file or directory. If not applicable, the value is null.|
|perm||User:group:mask or null if not applicable.|
This is similar to the format of HDFS audit log wiki.
To enable Alluxio audit logging, set the JVM property
See Configuration settings.
Service level encryption is not supported yet. Users can encrypt sensitive data at the application level or enable encryption features in the respective under file system, such as HDFS transparent encryption or Linux disk encryption.
It is recommended to start Alluxio master and workers under the same user. In the case where there is a user mismatch, file operations may fail because of permission checks.