bschoening commented on code in PR #4112: URL: https://github.com/apache/cassandra/pull/4112#discussion_r2615821289
########## doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc: ########## @@ -1809,632 +1787,7 @@ doing'', you can force the execution of this query by using SELECT firstname, lastname FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING; -[[databaseRoles]] -=== Database Roles - -[[createRoleStmt]] -==== CREATE ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/create_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/create_role.cql[] - -By default roles do not possess `LOGIN` privileges or `SUPERUSER` -status. - -link:#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 the `CREATE` permission on the database roles -resource may issue `CREATE ROLE` requests (see the -link:#permissions[relevant section] below), 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. - -[[createRolePwd]] -===== 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. - -[[createRoleConditional]] -===== 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,sql] -include::cassandra:example$CQL/create_role_ifnotexists.cql[] - -[[alterRoleStmt]] -==== ALTER ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/alter_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/alter_role.cql[] - -If the role does not exist, the statement will return an error, unless `IF EXISTS` is used in which case the operation is a no-op. - -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` -link:#permissions[permission] on that role - -[[dropRoleStmt]] -==== DROP ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/drop_role_statement.bnf[] - -_Sample:_ - -[source,sql] ----- -DROP ROLE alice; -DROP ROLE IF EXISTS bob; ----- - -`DROP ROLE` requires the client to have `DROP` -link:#permissions[permission] 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. - -[[grantRoleStmt]] -==== GRANT ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/grant_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra: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,sql] ----- -GRANT role_a TO role_b; -GRANT role_b TO role_a; ----- - -[source,sql] ----- -GRANT role_a TO role_b; -GRANT role_b TO role_c; -GRANT role_c TO role_a; ----- - -[[revokeRoleStmt]] -==== REVOKE ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/revoke_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra: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. - -[[listRolesStmt]] -===== LIST ROLES - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/list_roles_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/list_roles.cql[] - -Return all known roles in the system, this requires `DESCRIBE` -permission on the database roles resource. - -[source,sql] -include::cassandra:example$CQL/list_roles_of.cql[] - -Enumerate all roles granted to `alice`, including those transitively -acquired. - -[source,sql] -include::cassandra:example$CQL/list_roles_nonrecursive.cql[] - -List all roles directly granted to `bob`. - -[[createUserStmt]] -==== CREATE USER - -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. - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/create_user_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/create_user.cql[] - -`CREATE USER` is equivalent to `CREATE ROLE` where the `LOGIN` option is -`true`. So, the following pairs of statements are equivalent: - -[source,sql] ----- -include::cassandra:example$CQL/create_user_role.cql[] ----- - -[[alterUserStmt]] -==== ALTER USER - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/alter_user_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/alter_user.cql[] - -If the user does not exist, the statement will return an error, unless `IF EXISTS` is used in which case the operation is a no-op. - -[[dropUserStmt]] -==== DROP USER - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/drop_user_statement.bnf[] - -_Sample:_ - -[source,sql] ----- -DROP USER alice; -DROP USER IF EXISTS bob; ----- - -[[listUsersStmt]] -==== LIST USERS - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/list_users_statement.bnf[] - -_Sample:_ - -[source,sql] -LIST USERS; - -This statement is equivalent to - -[source,sql] -LIST ROLES; - -but only roles with the `LOGIN` privilege are included in the output. - -[[databaseIdentity]] -=== Database Identities - -[[AddIdentityStmt]] -==== ADD IDENTITY - -_Syntax:_ - -[source,bnf] -::= ADD IDENTITY ( IF NOT EXISTS )? TO ROLE ? - -_Sample:_ - -[source,sql] -ADD IDENTITY 'id1' TO ROLE 'role1'; - -Only a user with privileges to add roles can add identities - -Role names & Identity names should be quoted if they contain non-alphanumeric characters. - -[[addIdentityConditional]] -===== Adding an identity conditionally - -Attempting to add an existing identity results in an invalid query -condition unless the `IF NOT EXISTS` option is used. If the option is -used and the identity exists, the statement is a no-op. - -[source,sql] -ADD IDENTITY IF NOT EXISTS 'id1' TO ROLE 'role1'; - Review Comment: Good catch, that should be moved to security.adoc, right? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
