| role_name ::= identifier | string= Security |
| |
| [[cql-roles]] |
| == Database Roles |
| |
| CQL uses database roles to represent users and group of users. |
| Syntactically, a role is defined by: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/role_name.bnf[] |
| ---- |
| |
| |
| [[create-role-statement]] |
| === CREATE ROLE |
| |
| Creating a role uses the `CREATE ROLE` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/create_role_statement.bnf[] |
| ---- |
| |
| For instance: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/create_role.cql[] |
| ---- |
| |
| By default roles do not possess `LOGIN` privileges or `SUPERUSER` |
| status. |
| |
| xref:cql/security.adoc#cql-permissions[Permissions] on database resources are granted to |
| roles; types of resources include keyspaces, tables, functions and roles |
| themselves. Roles may be granted to other roles to create hierarchical |
| permissions structures; in these hierarchies, permissions and |
| `SUPERUSER` status are inherited, but the `LOGIN` privilege is not. |
| |
| If a role has the `LOGIN` privilege, clients may identify as that role |
| when connecting. For the duration of that connection, the client will |
| acquire any roles and privileges granted to that role. |
| |
| Only a client with with the `CREATE` permission on the database roles |
| resource may issue `CREATE ROLE` requests (see the |
| xref:cql/security.adoc#cql-permissions[relevant section]), unless the client is a |
| `SUPERUSER`. Role management in Cassandra is pluggable and custom |
| implementations may support only a subset of the listed options. |
| |
| Role names should be quoted if they contain non-alphanumeric characters. |
| |
| ==== Setting credentials for internal authentication |
| |
| Use the `WITH PASSWORD` clause to set a password for internal |
| authentication, enclosing the password in single quotation marks. |
| |
| If internal authentication has not been set up or the role does not have |
| `LOGIN` privileges, the `WITH PASSWORD` clause is not necessary. |
| |
| ==== Restricting connections to specific datacenters |
| |
| If a `network_authorizer` has been configured, you can restrict login |
| roles to specific datacenters with the `ACCESS TO DATACENTERS` clause |
| followed by a set literal of datacenters the user can access. Not |
| specifiying datacenters implicitly grants access to all datacenters. The |
| clause `ACCESS TO ALL DATACENTERS` can be used for explicitness, but |
| there's no functional difference. |
| |
| ==== Creating a role conditionally |
| |
| Attempting to create an existing role results in an invalid query |
| condition unless the `IF NOT EXISTS` option is used. If the option is |
| used and the role exists, the statement is a no-op: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/create_role_ifnotexists.cql[] |
| ---- |
| |
| [[alter-role-statement]] |
| === ALTER ROLE |
| |
| Altering a role options uses the `ALTER ROLE` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/alter_role_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/alter_role.cql[] |
| ---- |
| |
| ==== Restricting connections to specific datacenters |
| |
| If a `network_authorizer` has been configured, you can restrict login |
| roles to specific datacenters with the `ACCESS TO DATACENTERS` clause |
| followed by a set literal of datacenters the user can access. To remove |
| any data center restrictions, use the `ACCESS TO ALL DATACENTERS` |
| clause. |
| |
| Conditions on executing `ALTER ROLE` statements: |
| |
| * a client must have `SUPERUSER` status to alter the `SUPERUSER` status |
| of another role |
| * a client cannot alter the `SUPERUSER` status of any role it currently |
| holds |
| * a client can only modify certain properties of the role with which it |
| identified at login (e.g. `PASSWORD`) |
| * to modify properties of a role, the client must be granted `ALTER` |
| `permission <cql-permissions>` on that role |
| |
| [[drop-role-statement]] |
| === DROP ROLE |
| |
| Dropping a role uses the `DROP ROLE` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/drop_role_statement.bnf[] |
| ---- |
| |
| `DROP ROLE` requires the client to have `DROP` |
| `permission <cql-permissions>` on the role in question. In addition, |
| client may not `DROP` the role with which it identified at login. |
| Finally, only a client with `SUPERUSER` status may `DROP` another |
| `SUPERUSER` role. |
| |
| Attempting to drop a role which does not exist results in an invalid |
| query condition unless the `IF EXISTS` option is used. If the option is |
| used and the role does not exist the statement is a no-op. |
| |
| [NOTE] |
| .Note |
| ==== |
| DROP ROLE intentionally does not terminate any open user sessions. |
| Currently connected sessions will remain connected and will retain the |
| ability to perform any database actions which do not require |
| xref:cql/security.adoc#authorization[authorization]. |
| However, if authorization is enabled, xref:cql/security.adoc#cql-permissions[permissions] of the dropped role are also revoked, |
| subject to the xref:cql/security.adoc#auth-caching[caching options] configured in xref:cql/configuring.adoc#cassandra.yaml[cassandra-yaml] file. |
| Should a dropped role be subsequently recreated and have new xref:security.adoc#grant-permission-statement[permissions] or |
| xref:security.adoc#grant-role-statement[roles]` granted to it, any client sessions still |
| connected will acquire the newly granted permissions and roles. |
| ==== |
| |
| [[grant-role-statement]] |
| === GRANT ROLE |
| |
| Granting a role to another uses the `GRANT ROLE` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/grant_role_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_role.cql[] |
| ---- |
| |
| This statement grants the `report_writer` role to `alice`. Any |
| permissions granted to `report_writer` are also acquired by `alice`. |
| |
| Roles are modelled as a directed acyclic graph, so circular grants are |
| not permitted. The following examples result in error conditions: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/role_error.cql[] |
| ---- |
| |
| [[revoke-role-statement]] |
| === REVOKE ROLE |
| |
| Revoking a role uses the `REVOKE ROLE` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/revoke_role_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/revoke_role.cql[] |
| ---- |
| |
| This statement revokes the `report_writer` role from `alice`. Any |
| permissions that `alice` has acquired via the `report_writer` role are |
| also revoked. |
| |
| [[list-roles-statement]] |
| === LIST ROLES |
| |
| All the known roles (in the system or granted to specific role) can be |
| listed using the `LIST ROLES` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/list_roles_statement.bnf[] |
| ---- |
| |
| For instance: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_roles.cql[] |
| ---- |
| |
| returns all known roles in the system, this requires `DESCRIBE` |
| permission on the database roles resource. |
| |
| This example enumerates all roles granted to `alice`, including those transitively |
| acquired: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_roles_of.cql[] |
| ---- |
| |
| This example lists all roles directly granted to `bob` without including any of the |
| transitively acquired ones: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_roles_nonrecursive.cql[] |
| ---- |
| |
| == Users |
| |
| Prior to the introduction of roles in Cassandra 2.2, authentication and |
| authorization were based around the concept of a `USER`. For backward |
| compatibility, the legacy syntax has been preserved with `USER` centric |
| statements becoming synonyms for the `ROLE` based equivalents. In other |
| words, creating/updating a user is just a different syntax for |
| creating/updating a role. |
| |
| [[create-user-statement]] |
| === CREATE USER |
| |
| Creating a user uses the `CREATE USER` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/create_user_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/create_user.cql[] |
| ---- |
| |
| The `CREATE USER` command is equivalent to `CREATE ROLE` where the `LOGIN` option is `true`. |
| So, the following pairs of statements are equivalent: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/create_user_role.cql[] |
| ---- |
| |
| [[alter-user-statement]] |
| === ALTER USER |
| |
| Altering the options of a user uses the `ALTER USER` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/alter_user_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/alter_user.cql[] |
| ---- |
| |
| [[drop-user-statement]] |
| === DROP USER |
| |
| Dropping a user uses the `DROP USER` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/drop_user_statement.bnf[] |
| ---- |
| |
| [[list-users-statement]] |
| === LIST USERS |
| |
| Existing users can be listed using the `LIST USERS` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/list_users_statement.bnf[] |
| ---- |
| |
| Note that this statement is equivalent to xref:security.adoc#list-roles-statement[`LIST ROLES], but only roles with the `LOGIN` privilege are included in the output. |
| |
| == Data Control |
| |
| [[cql-permissions]] |
| === Permissions |
| |
| Permissions on resources are granted to roles; there are several |
| different types of resources in Cassandra and each type is modelled |
| hierarchically: |
| |
| * The hierarchy of Data resources, Keyspaces and Tables has the |
| structure `ALL KEYSPACES` -> `KEYSPACE` -> `TABLE`. |
| * Function resources have the structure `ALL FUNCTIONS` -> `KEYSPACE` -> |
| `FUNCTION` |
| * Resources representing roles have the structure `ALL ROLES` -> `ROLE` |
| * Resources representing JMX ObjectNames, which map to sets of |
| MBeans/MXBeans, have the structure `ALL MBEANS` -> `MBEAN` |
| |
| Permissions can be granted at any level of these hierarchies and they |
| flow downwards. So granting a permission on a resource higher up the |
| chain automatically grants that same permission on all resources lower |
| down. For example, granting `SELECT` on a `KEYSPACE` automatically |
| grants it on all `TABLES` in that `KEYSPACE`. Likewise, granting a |
| permission on `ALL FUNCTIONS` grants it on every defined function, |
| regardless of which keyspace it is scoped in. It is also possible to |
| grant permissions on all functions scoped to a particular keyspace. |
| |
| Modifications to permissions are visible to existing client sessions; |
| that is, connections need not be re-established following permissions |
| changes. |
| |
| The full set of available permissions is: |
| |
| * `CREATE` |
| * `ALTER` |
| * `DROP` |
| * `SELECT` |
| * `MODIFY` |
| * `AUTHORIZE` |
| * `DESCRIBE` |
| * `EXECUTE` |
| |
| Not all permissions are applicable to every type of resource. For |
| instance, `EXECUTE` is only relevant in the context of functions or |
| mbeans; granting `EXECUTE` on a resource representing a table is |
| nonsensical. Attempting to `GRANT` a permission on resource to which it |
| cannot be applied results in an error response. The following |
| illustrates which permissions can be granted on which types of resource, |
| and which statements are enabled by that permission. |
| |
| [cols=",,",options="header",] |
| |=== |
| |Permission |Resource |Operations |
| |
| | `CREATE` | `ALL KEYSPACES` | `CREATE KEYSPACE` and `CREATE TABLE` in any keyspace |
| |
| | `CREATE` | `KEYSPACE` | `CREATE TABLE` in specified keyspace |
| |
| | `CREATE` | `ALL FUNCTIONS` | `CREATE FUNCTION` in any keyspace and `CREATE AGGREGATE` in any keyspace |
| |
| | `CREATE` | `ALL FUNCTIONS IN KEYSPACE` | `CREATE FUNCTION` and `CREATE AGGREGATE` in specified keyspace |
| |
| | `CREATE` | `ALL ROLES` | `CREATE ROLE` |
| |
| | `ALTER` | `ALL KEYSPACES` | `ALTER KEYSPACE` and `ALTER TABLE` in any keyspace |
| |
| | `ALTER` | `KEYSPACE` | `ALTER KEYSPACE` and `ALTER TABLE` in specified keyspace |
| |
| | `ALTER` | `TABLE` | `ALTER TABLE` |
| |
| | `ALTER` | `ALL FUNCTIONS` | `CREATE FUNCTION` and `CREATE AGGREGATE`: replacing any existing |
| |
| | `ALTER` | `ALL FUNCTIONS IN KEYSPACE` | `CREATE FUNCTION` and `CREATE AGGREGATE`: replacing existing in specified keyspace |
| |
| | `ALTER` | `FUNCTION` | `CREATE FUNCTION` and `CREATE AGGREGATE`: replacing existing |
| |
| | `ALTER` | `ALL ROLES` | `ALTER ROLE` on any role |
| |
| | `ALTER` | `ROLE` | `ALTER ROLE` |
| |
| | `DROP` | `ALL KEYSPACES` | `DROP KEYSPACE` and `DROP TABLE` in any keyspace |
| |
| | `DROP` | `KEYSPACE` | `DROP TABLE` in specified keyspace |
| |
| | `DROP` | `TABLE` | `DROP TABLE` |
| |
| | `DROP` | `ALL FUNCTIONS` | `DROP FUNCTION` and `DROP AGGREGATE` in any keyspace |
| |
| | `DROP` | `ALL FUNCTIONS IN KEYSPACE` | `DROP FUNCTION` and `DROP AGGREGATE` in specified keyspace |
| |
| | `DROP` | `FUNCTION` | `DROP FUNCTION` |
| |
| | `DROP` | `ALL ROLES` | `DROP ROLE` on any role |
| |
| | `DROP` | `ROLE` | `DROP ROLE` |
| |
| | `SELECT` | `ALL KEYSPACES` | `SELECT` on any table |
| |
| | `SELECT` | `KEYSPACE` | `SELECT` on any table in specified keyspace |
| |
| | `SELECT` | `TABLE` | `SELECT` on specified table |
| |
| | `SELECT` | `ALL MBEANS` | Call getter methods on any mbean |
| |
| | `SELECT` | `MBEANS` | Call getter methods on any mbean matching a wildcard pattern |
| |
| | `SELECT` | `MBEAN` | Call getter methods on named mbean |
| |
| | `MODIFY` | `ALL KEYSPACES` | `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE` on any table |
| |
| | `MODIFY` | `KEYSPACE` | `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE` on any table in specified |
| keyspace |
| |
| | `MODIFY` | `TABLE` | `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE` on specified table |
| |
| | `MODIFY` | `ALL MBEANS` | Call setter methods on any mbean |
| |
| | `MODIFY` | `MBEANS` | Call setter methods on any mbean matching a wildcard pattern |
| |
| | `MODIFY` | `MBEAN` | Call setter methods on named mbean |
| |
| | `AUTHORIZE` | `ALL KEYSPACES` | `GRANT PERMISSION` and `REVOKE PERMISSION` on any table |
| |
| | `AUTHORIZE` | `KEYSPACE` | `GRANT PERMISSION` and `REVOKE PERMISSION` on any table in specified keyspace |
| |
| | `AUTHORIZE` | `TABLE` | `GRANT PERMISSION` and `REVOKE PERMISSION` on specified table |
| |
| | `AUTHORIZE` | `ALL FUNCTIONS` | `GRANT PERMISSION` and `REVOKE PERMISSION` on any function |
| |
| | `AUTHORIZE` | `ALL FUNCTIONS IN KEYSPACE` | `GRANT PERMISSION` and `REVOKE PERMISSION` in specified keyspace |
| |
| | `AUTHORIZE` | `FUNCTION` | `GRANT PERMISSION` and `REVOKE PERMISSION` on specified function |
| |
| | `AUTHORIZE` | `ALL MBEANS` | `GRANT PERMISSION` and `REVOKE PERMISSION` on any mbean |
| |
| | `AUTHORIZE` | `MBEANS` | `GRANT PERMISSION` and `REVOKE PERMISSION` on any mbean matching a wildcard pattern |
| |
| | `AUTHORIZE` | `MBEAN` | `GRANT PERMISSION` and `REVOKE PERMISSION` on named mbean |
| |
| | `AUTHORIZE` | `ALL ROLES` | `GRANT ROLE` and `REVOKE ROLE` on any role |
| |
| | `AUTHORIZE` | `ROLES` | `GRANT ROLE` and `REVOKE ROLE` on specified roles |
| |
| | `DESCRIBE` | `ALL ROLES` | `LIST ROLES` on all roles or only roles granted to another, specified role |
| |
| | `DESCRIBE` | `ALL MBEANS` | Retrieve metadata about any mbean from the platform's MBeanServer |
| |
| |
| | `DESCRIBE` | `MBEANS` | Retrieve metadata about any mbean matching a wildcard patter from the |
| platform's MBeanServer |
| |
| | `DESCRIBE` | `MBEAN` | Retrieve metadata about a named mbean from the platform's MBeanServer |
| |
| | `EXECUTE` | `ALL FUNCTIONS` | `SELECT`, `INSERT` and `UPDATE` using any function, and use of any |
| function in `CREATE AGGREGATE` |
| |
| | `EXECUTE` | `ALL FUNCTIONS IN KEYSPACE` | `SELECT`, `INSERT` and `UPDATE` using any function in specified keyspace |
| and use of any function in keyspace in `CREATE AGGREGATE` |
| |
| | `EXECUTE` | `FUNCTION` | `SELECT`, `INSERT` and `UPDATE` using specified function and use of the function in `CREATE AGGREGATE` |
| |
| | `EXECUTE` | `ALL MBEANS` | Execute operations on any mbean |
| |
| | `EXECUTE` | `MBEANS` | Execute operations on any mbean matching a wildcard pattern |
| |
| | `EXECUTE` | `MBEAN` | Execute operations on named mbean |
| |=== |
| |
| [[grant-permission-statement]] |
| === GRANT PERMISSION |
| |
| Granting a permission uses the `GRANT PERMISSION` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/grant_permission_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_perm.cql[] |
| ---- |
| |
| This example gives any user with the role `data_reader` permission to execute |
| `SELECT` statements on any table across all keyspaces: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_modify.cql[] |
| ---- |
| |
| To give any user with the role `data_writer` permission to perform |
| `UPDATE`, `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE` queries on all |
| tables in the `keyspace1` keyspace: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_drop.cql[] |
| ---- |
| |
| To give any user with the `schema_owner` role permissions to `DROP` a specific |
| `keyspace1.table1`: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_execute.cql[] |
| ---- |
| |
| This command grants any user with the `report_writer` role permission to execute |
| `SELECT`, `INSERT` and `UPDATE` queries which use the function |
| `keyspace1.user_function( int )`: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/grant_describe.cql[] |
| ---- |
| |
| This grants any user with the `role_admin` role permission to view any |
| and all roles in the system with a `LIST ROLES` statement. |
| |
| ==== GRANT ALL |
| |
| When the `GRANT ALL` form is used, the appropriate set of permissions is |
| determined automatically based on the target resource. |
| |
| ==== Automatic Granting |
| |
| When a resource is created, via a `CREATE KEYSPACE`, `CREATE TABLE`, |
| `CREATE FUNCTION`, `CREATE AGGREGATE` or `CREATE ROLE` statement, the |
| creator (the role the database user who issues the statement is |
| identified as), is automatically granted all applicable permissions on |
| the new resource. |
| |
| [[revoke-permission-statement]] |
| === REVOKE PERMISSION |
| |
| Revoking a permission from a role uses the `REVOKE PERMISSION` |
| statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/revoke_permission_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/revoke_perm.cql[] |
| ---- |
| |
| Because of their function in normal driver operations, certain tables |
| cannot have their `SELECT` permissions revoked. The |
| following tables will be available to all authorized users regardless of |
| their assigned role: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/no_revoke.cql[] |
| ---- |
| |
| [[list-permissions-statement]] |
| === LIST PERMISSIONS |
| |
| Listing granted permissions uses the `LIST PERMISSIONS` statement: |
| |
| [source, bnf] |
| ---- |
| include::example$BNF/list_permissions_statement.bnf[] |
| ---- |
| |
| For example: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_perm.cql[] |
| ---- |
| |
| Show all permissions granted to `alice`, including those acquired |
| transitively from any other roles: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_all_perm.cql[] |
| ---- |
| |
| Show all permissions on `keyspace1.table1` granted to `bob`, including |
| those acquired transitively from any other roles. This also includes any |
| permissions higher up the resource hierarchy which can be applied to |
| `keyspace1.table1`. For example, should `bob` have `ALTER` permission on |
| `keyspace1`, that would be included in the results of this query. Adding |
| the `NORECURSIVE` switch restricts the results to only those permissions |
| which were directly granted to `bob` or one of `bob`'s roles: |
| |
| [source,cql] |
| ---- |
| include::example$CQL/list_select_perm.cql[] |
| ---- |
| |
| Show any permissions granted to `carlos` or any of `carlos`'s roles, |
| limited to `SELECT` permissions on any resource. |