Security

This document describes the following security related features in Alluxio.

  1. Authentication: If alluxio.security.authentication.type=SIMPLE (by default), Alluxio file system recognizes the user accessing the service. Having SIMPLE authentication is required to use other security features such as authorization. Alluxio also supports other authentication modes like NOSASL and CUSTOM.
  2. Authorization: If alluxio.security.authorization.permission.enabled=true (by default), Alluxio file system will grant or deny user access based on the requesting user and the POSIX permission model of the files or directories to access. Note that, authentication cannot be NOSASL as authorization requires user information.
  3. 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.

Authentication

SIMPLE

When alluxio.security.authentication.type is set to SIMPLE, authentication is enabled. Before an Alluxio client accesses the service, this client retrieves the user information to report to Alluxio service in the following order:

  1. If property alluxio.security.login.username is set on the client, its value will be used as the login user of this client.
  2. Otherwise, the login user is inferred from the operating system.

After the client retrieves the user information, it will use this user information to connect to the service. After a client creates directories/files, the user information is added into metadata and can be retrieved in CLI and UI.

NOSASL

When alluxio.security.authentication.type is NOSASL, authentication is disabled. Alluxio service will ignore the user of the client and no information will be associated to the files or directories created by this user.

CUSTOM

When alluxio.security.authentication.type is CUSTOM, authentication is enabled. Alluxio clients checks alluxio.security.authentication.custom.provider.class which is name of a class implementing alluxio.security.authentication.AuthenticationProvider to retrieve the user.

This mode is currently experimental and should only be used in tests.

Authorization

Alluxio file system implements a permissions model for directories and files similar as the POSIX permission model.

Each file and directory is associated with:

  1. an owner, which is the user of the client process to create the file or directory.
  2. a group, which is the group fetched from user-groups-mapping service. See User group mapping.
  3. permissions

The permissions has three parts:

  1. owner permission defines the access privileges of the file owner
  2. group permission defines the access privileges of the owning group
  3. other permission defines the access privileges of all users that are not in any of above two classes

Each permission has three actions:

  1. read (r)
  2. write (w)
  3. execute (x)

For files, the r permission is required to read the file, and the w permission is required to write the file. For directories, the r permission is required to list the contents of the directory, the w permission is required to create, rename or delete files or directories under it, and the x permission is required to access a child of the directory.

For example, the output of the shell command ls 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

When user is determined, the list of groups is determined by a group mapping service, configured by alluxio.security.group.mapping.class. The default implementation is alluxio.security.group.provider.ShellBasedUnixGroupsMapping, which executes the groups shell command to fetch the group memberships of a given user. There is a caching mechanism for user group mapping, the mapping data will be cached for 60 seconds by default, this value can be configured by alluxio.security.group.mapping.cache.timeout, if the value is ‘0’, the cached will be disabled.

Property alluxio.security.authorization.permission.supergroup defines a super group. Any users belong to this group are also super users.

Initialized directory and file permissions

The initial creation permission is 777, and the difference between directory and file is 111. For default umask value 022, the created directory has permission 755 and file has permission 644. The umask can be set by property alluxio.security.authorization.permission.umask.

Update directory and file permission model

The owner, group, and permissions can be changed by two ways:

  1. User application invokes the setAttribute(…) method of FileSystem API or Hadoop API. See File System API.
  2. CLI command in shell. See chown, chgrp, chmod.

The owner can only be changed by super user. The group and permission can only be changed by super user and file owner.

Auditing

Alluxio supports audit logging to allow system administrators to track users’ access to file metadata.

The audit log file (master_audit.log) contains multiple audit log entries, each of which corresponds to an access to file metadata. The format of Alluxio audit log entry is shown in the table below.

keyvalue
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.

It is similar to the format of HDFS audit log wiki.

To enable Alluxio audit logging, you need to set the JVM property alluxio.master.audit.logging.enabled to true, see Configuration settings.

Encryption

Service level encryption is not supported yet, user could encrypt sensitive data at application level, or enable encryption feature at under file system, e.g. HDFS transparent encryption, Linux disk encryption.

Deployment

It is recommended to start Alluxio master and workers by one same user. Alluxio cluster service composes of master and workers. Every worker needs to RPC with master for some file operations. If the user of a worker is not the same as the master’s, the file operations may fail because of permission check.

Need help? Ask a Question