Hive SQL Syntax for Use with Sentry
Sentry permissions can be configured through GRANT and REVOKE statements issued either interactively or programmatically through the HiveServer2 SQL command line interface, Beeline (documentation available here). The syntax described below is very similar to the GRANT and REVOKE commands that are available in well-established relational database systems.
CREATE ROLE <admin role>; GRANT ALL ON SERVER <server1> TO ROLE <admin role> WITH GRANT OPTION; GRANT ROLE <admin role> TO GROUP <hive>;
Sentry supports column-level authorization with the SELECT privilege. Information about column-level authorization is in the Column-level Authorization section of this page.
See the sections below for details about the supported statements and privileges:
- Column-level Authorization
- CREATE ROLE Statement
- DROP ROLE Statement
- GRANT ROLE Statement
- REVOKE ROLE Statement
- GRANT <Privilege> Statement
- GRANT <Privilege> ON URIs (HDFS and S3A)
- REVOKE <Privilege> Statement
- GRANT <Privilege> ... WITH GRANT OPTION
- SET ROLE Statement
- SHOW Statement
- Example: Using Grant/Revoke Statements to Match an Existing Policy File
CREATE ROLE Statement
The CREATE ROLE statement creates a role to which privileges can be granted. Privileges can be granted to roles, which can then be assigned to users. A user that has been assigned a role will only be able to exercise the privileges of that role.
Only users that have administrative privileges can create or drop roles. By default, the hive, impala and hue users have admin privileges in Sentry.
CREATE ROLE <role name>;
Note that role names are case-insensitive.
DROP ROLE Statement
The DROP ROLE statement can be used to remove a role from the database. Once dropped, the role will be revoked for all users to whom it was previously assigned. Queries that are already executing will not be affected. However, since Hive checks user privileges before executing each query, active user sessions in which the role has already been enabled will be affected.
DROP ROLE <role name>;
GRANT ROLE Statement
The GRANT ROLE statement can be used to grant roles to groups. Only Sentry admin users can grant roles to a group.
GRANT ROLE <role name> [, <role name>] TO GROUP <group name> [,GROUP <group name>]
GRANT ROLE test TO GROUP test-group;To grant a role to this group, put the group name in backticks:
GRANT ROLE test TO GROUP `test-group`;The following command, which contains an underscore, is also acceptable:
GRANT ROLE test TO GROUP test_group;
Operating system group names must be in lowercase letters. Although group names are case-insensitive to Sentry, Sentry modifies capital letters within group names to be lowercase. For example, Sentry will change TestGroup to testgroup. It is not possible to disable this normalization. Therefore, group information within the environment must be in lowercase letters.
REVOKE ROLE Statement
The REVOKE ROLE statement can be used to revoke roles from groups. Only Sentry admin users can revoke the role from a group.
REVOKE ROLE <role name> [, <role name>] FROM GROUP <group name> [,GROUP <group name>]
GRANT <Privilege> Statement
Use the GRANT <Privilege> statement to grant privileges on an object to a role. The statement uses the following syntax:
GRANT <privilege> [, <privilege> ] ON <object type> <object name> TO ROLE <role name> [,ROLE <role name>]
GRANT SELECT <column name> ON TABLE <table name> TO ROLE <role name>;
GRANT <Privilege> ON URIs (HDFS and S3A)
If the GRANT for Sentry URI does not specify the complete scheme, or the URI mentioned in Hive DDL statements does not have a scheme, Sentry automatically completes the URI by applying the default scheme based on the HDFS configuration provided in the fs.defaultFS property. Using the same HDFS configuration, Sentry can also auto-complete URIs in case the URI is missing a scheme and an authority component.
When a user attempts to access a URI, Sentry will check to see if the user has the required privileges. During the authorization check, if the URI is incomplete, Sentry will complete the URI using the default HDFS scheme. Note that Sentry does not check URI schemes for completion when they are being used to grant privileges. This is because users can GRANT privileges on URIs that do not have a complete scheme or do not already exist on the filesystem.
For example, in CDH 5.8 and later, the following CREATE EXTERNAL TABLE statement works even though the statement does not include the URI scheme.
GRANT ALL ON URI 'hdfs://namenode:XXX/path/to/table' TO ROLE <role name>; CREATE EXTERNAL TABLE foo LOCATION 'namenode:XXX/path/to/table' TO ROLE <role name>;Similarly, the following CREATE EXTERNAL TABLE statement works even though it is missing scheme and authority components.
GRANT ALL ON URI 'hdfs://namenode:XXX/path/to/table' TO ROLE <role name>; CREATE EXTERNAL TABLE foo LOCATION '/path/to/table'
- HDFS: hdfs://host:port/path/to/hdfs/table
- S3: s3a://host:port/path/to/s3/table
REVOKE <Privilege> Statement
You can use the REVOKE <Privilege> statement to revoke previously-granted privileges that a role has on an object.
REVOKE <privilege> [, <privilege> ] ON <object type> <object name> FROM ROLE <role name> [,ROLE <role name>]For example, you can revoke previously-granted SELECT privileges on specific columns of a table with the following statement:
REVOKE SELECT <column name> ON TABLE <table name> FROM ROLE <role name>;
GRANT <Privilege> ... WITH GRANT OPTION
GRANT <privilege> ON <object type> <object name> TO ROLE <role name> WITH GRANT OPTIONOnly a role with GRANT option on a specific privilege or its parent privilege can revoke that privilege from other roles. Once the following statement is executed, all privileges with and without grant option are revoked.
REVOKE <privilege> ON <object type> <object name> FROM ROLE <role name>Hive does not currently support revoking only the WITH GRANT OPTION from a privilege previously granted to a role. To remove the WITH GRANT OPTION, revoke the privilege and grant it again without the WITH GRANT OPTION flag.
SET ROLE Statement
Sentry enforces restrictions on queries based on the roles and privileges that the user has. A user can have multiple roles and a role can have multiple privileges.
The SET ROLE command enforces restrictions at the role level, not at the user level. When you use the SET ROLE command to make a role active, the role becomes current for the session. If a role is not current for the session, it is inactive and the user does not have the privileges assigned to that role. A user can only use the SET ROLE command for roles that have been granted to the user.
To list the roles that are current for the user, use the SHOW CURRENT ROLES command. By default, all roles that are assigned to the user are current.
You can use the following SET ROLE commands:
- SET ROLE NONE
- Makes all roles for the user inactive. When no role is current, the user does not have any privileges and cannot execute a query.
- SET ROLE ALL
- Makes all roles that have been granted to the user active. All privileges assigned to those roles are applied. When the user executes a query, the query is filtered based on those privileges.
- SET ROLE role name
- Makes a single role active. The privileges assigned to that role are applied. When the user executes a query, the query is filtered based on the privileges assigned to that role.
- To list the database(s) for which the current user has database, table, or column-level access:
- To list the table(s) for which the current user has table or column-level access:
To list the column(s) to which the current user has SELECT access:
SHOW COLUMNS (FROM|IN) <table name> [(FROM|IN) <database name>];
- To list all the roles in the system (only for sentry admin users):
To list all the roles in effect for the current user session:
SHOW CURRENT ROLES;
- To list all the roles assigned to the given group name (only allowed for Sentry admin users and others users that are
part of the group specified by group name):
SHOW ROLE GRANT GROUP group name;
The SHOW statement can also be used to list the privileges that have been granted to a role or all the grants given to a role for a particular object.To list all the grants for the given <role name> (only allowed for Sentry admin users and other users that have been granted the role specified by <role name>). The following command will also list any column-level privileges:
SHOW GRANT ROLE <role name>;
- To list all the grants for a role on the given <object name> (only allowed for Sentry admin users and other
users that have been granted the role specified by <role name>). The following command will also list any column-level
SHOW GRANT ROLE <role name> on <object type> <object name>;
Example: Using Grant/Revoke Statements to Match an Existing Policy File
[groups] # Assigns each Hadoop group to its set of roles manager = analyst_role, junior_analyst_role analyst = analyst_role jranalyst = junior_analyst_role customers_admin = customers_admin_role admin = admin_role [roles] # The UIRs below define a landing skid which # the user can use to import or export data from the system. # Since the server runs as the user "hive" files in that directory # must either have the group hive and read/write set or # be world read/write. analyst_role = server=server1->db=analyst1, \ server=server1->db=jranalyst1->table=*->action=select server=server1->uri=hdfs://ha-nn-uri/landing/analyst1 junior_analyst_role = server=server1->db=jranalyst1, \ server=server1->uri=hdfs://ha-nn-uri/landing/jranalyst1 # Implies everything on server1. admin_role = server=server1
The following sections show how you can use the new GRANT statements to assign privileges to roles (and assign roles to groups) to match the sample policy file above.
CREATE ROLE analyst_role; GRANT ALL ON DATABASE analyst1 TO ROLE analyst_role; GRANT SELECT ON DATABASE jranalyst1 TO ROLE analyst_role; GRANT ALL ON URI 'hdfs://ha-nn-uri/landing/analyst1' \ TO ROLE analyst_role;
CREATE ROLE junior_analyst_role; GRANT ALL ON DATABASE jranalyst1 TO ROLE junior_analyst_role; GRANT ALL ON URI 'hdfs://ha-nn-uri/landing/jranalyst1' \ TO ROLE junior_analyst_role;
CREATE ROLE admin_role; GRANT ALL ON SERVER server1 TO ROLE admin_role;
GRANT ROLE admin_role TO GROUP admin; GRANT ROLE analyst_role TO GROUP analyst; GRANT ROLE jranalyst_role TO GROUP jranalyst;