Implementation of CEP-55 - Generation of role names

patch by Stefan Miklosovic; reviewed by Bernardo Botella for CASSANDRA-20897

Author: smiklosovic

CHANGES.txt

@@ -1,4 +1,5 @@
 5.1
+ * Implementation of CEP-55 - Generation of role names (CASSANDRA-20897)
  * Add cqlsh autocompletion for the identity mapping feature (CASSANDRA-20021)
  * Add DDL Guardrail enabling administrators to disallow creation/modification of keyspaces with durable_writes = false (CASSANDRA-20913)
  * Optimize Counter, Meter and Histogram metrics using thread local counters (CASSANDRA-20250)

NEWS.txt

@@ -102,10 +102,13 @@ New features
     - Authentication mode is exposed in system_views.clients table, nodetool clientstats and ClientMetrics 
       to help operators identify which authentication modes are being used. nodetool clientstats introduces --verbose flag 
       behind which this information is visible.
-    - CEP-24 - Password validation / generation. When built-in 'password_validator' guardrail is enabled, it will
+    - CEP-24 - Password validation / generation. When built-in 'password_policy' guardrail is enabled, it will
       generate a password of configured password strength policy upon role creation or alteration
       when 'GENERATED PASSWORD' clause is used. Character sets supported are: English, Cyrillic, modern Cyrillic,
       German, Polish and Czech.
+    - CEP-55 - Role name generation and validation. When built-in 'role_name_policy' guardrail is enabled, it will
+      generate a role name automatically, without operators intervention. It is possible to configure
+      this policy for both generation and as well as validation of role names.
     - There is new MBean of name org.apache.cassandra.service.snapshot:type=SnapshotManager which exposes user-facing
       snapshot operations. Snapshot-related methods on StorageServiceMBean are still present and functional
       but marked as deprecated.

conf/cassandra.yaml

@@ -2507,20 +2507,41 @@ drop_compact_storage_enabled: false
 # This would also apply to system keyspaces.
 # maximum_replication_factor_warn_threshold: -1
 # maximum_replication_factor_fail_threshold: -1
-#
+
+#role_name_policy:
+#  # Implementation class of a validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no validator.
+#  #validator_class_name: YourValidatorOfRoleNames
+#  # Implementation class of related generator which generates values which are valid when
+#  # tested against this validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no generator.
+#  # There is currently only one generator possible to configure - UUIDRoleNameGenerator
+#  generator_class_name: UUIDRoleNameGenerator
+#  # Minimum generated size of a name when name_size option is specified in CQL.
+#  # This can not be less than 10 and more than 32.
+#  #min_generated_name_size: 10
+
+# If this is set to false, then it is not possible to call reconfiguration
+# method in GuardrailsMBean. It will effectively forbid the reconfiguration of role_name_policy in runtime.
+# You would need to stop the node, change the configuration in cassandra.yaml and start the node again.
+# Defaults to true, which means that reconfiguration of role_name_policy via JMX is possible.
+#role_name_policy_reconfiguration_enabled: true
+
 # Guardrail to warn or fail when setting / altering a password.
 # Supported character sets are (both upper and lower-case): English, Cyrillic and modern Cyrillic, Czech, German, Polish.
 # Password is invalid if all characters are from non-supported character set. If a password is otherwise valid,
 # but it contains characters from unsupported language, these characters contribute only to password length rule.
 # All digits and all following special characters are supported too: !"#$%&()*+,-./:;<=>?@[\]^_`{|}~
-#password_validator:
+#password_policy:
 #  # Implementation class of a validator. When not in form of FQCN, the
-#  # package name org.apache.cassandra.db.guardrails.validators is prepended.
+#  # package name org.apache.cassandra.db.guardrails is prepended.
 #  # By default, there is no validator.
-#  class_name: CassandraPasswordValidator
+#  validator_class_name: CassandraPasswordValidator
 #  # Implementation class of related generator which generates values which are valid when
 #  # tested against this validator. When not in form of FQCN, the
-#  # package name org.apache.cassandra.db.guardrails.generators is prepended.
+#  # package name org.apache.cassandra.db.guardrails is prepended.
 #  # By default, there is no generator.
 #  generator_class_name: CassandraPasswordGenerator
 #  # There are four characteristics:
@@ -2571,7 +2592,7 @@ drop_compact_storage_enabled: false
 # method in GuardrailsMBean. It will effectively forbid the reconfiguration of password validator in runtime.
 # You would need to stop the node, change the configuration in cassandra.yaml and start the node again.
 # Defaults to true, which means that reconfiguration of password validator via JMX is possible.
-# password_validator_reconfiguration_enabled: true
+#password_policy_reconfiguration_enabled: true
 
 # Guardrail to enable a CREATE or ALTER TABLE statement when default_time_to_live is set to 0
 # and the table is using TimeWindowCompactionStrategy compaction or a subclass of it.

conf/cassandra_latest.yaml

@@ -2290,6 +2290,98 @@ drop_compact_storage_enabled: false
 # maximum_replication_factor_warn_threshold: -1
 # maximum_replication_factor_fail_threshold: -1
 
+#role_name_policy:
+#  # Implementation class of a validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no validator.
+#  #validator_class_name: YourValidatorOfRoleNames
+#  # Implementation class of related generator which generates values which are valid when
+#  # tested against this validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no generator.
+#  # There is currently only one generator possible to configure - UUIDRoleNameGenerator
+#  generator_class_name: UUIDRoleNameGenerator
+#  # Minimum generated size of a name when name_size option is specified in CQL.
+#  # This can not be less than 10 and more than 32.
+#  #min_generated_name_size: 10
+
+# If this is set to false, then it is not possible to call reconfiguration
+# method in GuardrailsMBean. It will effectively forbid the reconfiguration of role_name_policy in runtime.
+# You would need to stop the node, change the configuration in cassandra.yaml and start the node again.
+# Defaults to true, which means that reconfiguration of role_name_policy via JMX is possible.
+#role_name_policy_reconfiguration_enabled: true
+
+# If this is set to false, then it is not possible to call reconfiguration
+# method in GuardrailsMBean. It will effectively forbid the reconfiguration of role_name_policy in runtime.
+# You would need to stop the node, change the configuration in cassandra.yaml and start the node again.
+# Defaults to true, which means that reconfiguration of role_name_policy via JMX is possible.
+#rolename_validator_reconfiguration_enabled: true
+
+# Guardrail to warn or fail when setting / altering a password.
+# Supported character sets are (both upper and lower-case): English, Cyrillic and modern Cyrillic, Czech, German, Polish.
+# Password is invalid if all characters are from non-supported character set. If a password is otherwise valid,
+# but it contains characters from unsupported language, these characters contribute only to password length rule.
+# All digits and all following special characters are supported too: !"#$%&()*+,-./:;<=>?@[\]^_`{|}~
+#password_policy:
+#  # Implementation class of a validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no validator.
+#  validator_class_name: CassandraPasswordValidator
+#  # Implementation class of related generator which generates values which are valid when
+#  # tested against this validator. When not in form of FQCN, the
+#  # package name org.apache.cassandra.db.guardrails is prepended.
+#  # By default, there is no generator.
+#  generator_class_name: CassandraPasswordGenerator
+#  # There are four characteristics:
+#  # upper-case, lower-case, special character and digit.
+#  # If this value is set e.g. to 3, a password has to consist of 3 out of 4 characteristics.
+#  # For example, it has to contain at least 2 upper-case characters, 2 lower-case, and 2 digits to pass,
+#  # but it does not have to contain any special characters.
+#  # If number of characteristics found in the password is less than or equal to this number, it will emit warning.
+#  characteristic_warn: 3
+#  # If number of characteristics found in the password is less than or equal to this number, it will emit failure.
+#  characteristic_fail: 2
+#  # Maximum length of a password. Defaults to 1000.
+#  max_length: 1000
+#  # If password is shorter than this value, the validator will emit a warning.
+#  length_warn: 12
+#  # If a password is shorter than this value, the validator will emit a failure.
+#  length_fail: 8
+#  # If a password does not contain at least n upper-case characters, the validator will emit a warning.
+#  upper_case_warn: 2
+#  # If a password does not contain at least n upper-case characters, the validator will emit a failure.
+#  upper_case_fail: 1
+#  # If a password does not contain at least n lower-case characters, the validator will emit a warning.
+#  lower_case_warn: 2
+#  # If a password does not contain at least n lower-case characters, the validator will emit a failure.
+#  lower_case_fail: 1
+#  # If a password does not contain at least n digits, the validator will emit a warning.
+#  digit_warn: 2
+#  # If a password does not contain at least n digits, the validator will emit a failure.
+#  digit_fail: 1
+#  # If a password does not contain at least n special characters, the validator will emit a warning.
+#  special_warn: 2
+#  # If a password does not contain at least n special characters, the validator will emit a failure.
+#  special_fail: 1
+#  # If a password contain illegal sequences that at least this long, it is invalid.
+#  # Illegal sequences might be either alphabetical (form 'abcde'),
+#  # numerical (form '34567'), or US qwerty (form 'asdfg') as well as sequencies from supported character sets.
+#  # The minimum value for this property is 3, by default it is set to 5.
+#  illegal_sequence_length: 5
+#  # Dictionary to check the passwords against. Defaults to no dictionary.
+#  # Whole dictionary is cached into memory. Use with caution with relatively big dictionaries.
+#  # Entries in a dictionary, one per line, have to be sorted per String's compareTo contract.
+#  #dictionary: /path/to/dictionary/file
+#  # If set to true, a user will be informed what policies a suggested password is missing in order to be valid.
+#  # Defaults to true.
+#  detailed_messages: true
+
+# If this is set to false, then it is not possible to call reconfiguration
+# method in GuardrailsMBean. It will effectively forbid the reconfiguration of password validator in runtime.
+# You would need to stop the node, change the configuration in cassandra.yaml and start the node again.
+# Defaults to true, which means that reconfiguration of password validator via JMX is possible.
+#password_policy_reconfiguration_enabled: true
+
 # Guardrail to enable a CREATE or ALTER TABLE statement when default_time_to_live is set to 0
 # and the table is using TimeWindowCompactionStrategy compaction or a subclass of it.
 # It is suspicious to use default_time_to_live set to 0 with such compaction strategy.

doc/cql3/CQL.textile

@@ -1329,7 +1329,7 @@ h3(#createRoleStmt). CREATE ROLE
 __Syntax:__
 
 bc(syntax).. 
-<create-role-stmt> ::= CREATE ROLE ( IF NOT EXISTS )? <identifier> ( WITH <option> ( AND <option> )* )?
+<create-role-stmt> ::= CREATE (GENERATED)? ROLE ( IF NOT EXISTS )? <identifier> ( WITH <option> ( AND <option> )* )?
 
 <option> ::= ("HASHED")? PASSWORD = <string>
            | GENERATED PASSWORD
@@ -1352,6 +1352,8 @@ CREATE ROLE carlos WITH OPTIONS = { 'custom_option1' : 'option1_value', 'custom_
 CREATE ROLE rob WITH LOGIN = true and PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS;
 CREATE ROLE hob WITH LOGIN = true and PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1' };
 CREATE ROLE tom WITH LOGIN = true and GENERATED PASSWORD;
+CREATE GENERATED ROLE WITH GENERATED PASSWORD;
+CREATE GENERATED ROLE WITH PASSWORD = 'password_e';
 
 
 By default roles do not possess @LOGIN@ privileges or @SUPERUSER@ status.
@@ -1370,9 +1372,13 @@ Use the @WITH PASSWORD@ clause to set a password for internal authentication, en
 If internal authentication has not been set up or the role does not have @LOGIN@ privileges, the @WITH PASSWORD@ clause is not necessary.
 
 When @WITH GENERATED PASSWORD@ is used, Cassandra provides out-of-the-box CassandraPasswordValidator and CassandraPasswordGenerator
-under "password_validator" configuration property in cassandra.yaml. The usage of this clause will generate a password for a given password strength policy, as configured,
+under "password_policy" configuration property in cassandra.yaml. The usage of this clause will generate a password for a given password strength policy, as configured,
 and such password is returned to a client in CQL shell after query is executed. @GENERATED PASSWORD@ can not be used together with @HASHED PASSWORD@ nor with @PASSWORD@ alone.
 
+When @GENERATED@ is used in front of @ROLE@, it is possible to generate a role name automatically. This is possible if `role_name_policy` is enabled in the configuration.
+The usage of this clause will generate a role name based on given `generator_class_name` in `role_name_policy` section in cassandra.yaml. Generated role name (together with generated password) will
+be returned in CQL response to a caller. Custom implementations of `IRoleManager` are able to specify custom response to return to a caller if default behaviour is not desired.
+
 h4(#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.
@@ -1522,7 +1528,6 @@ bc(syntax)..
 <create-user-statement> ::= CREATE USER ( IF NOT EXISTS )? <identifier> ( WITH <option> ( AND <option> )* )?
 
 <option> ::= ("HASHED")? PASSWORD = <string>
-           | GENERATED PASSWORD
            | SUPERUSER
            | NOSUPERUSER
 p. 
@@ -1532,7 +1537,6 @@ __Sample:__
 bc(sample). 
 CREATE USER alice WITH PASSWORD 'password_a' SUPERUSER;
 CREATE USER bob WITH PASSWORD 'password_b' NOSUPERUSER;
-CREATE USER tom WITH GENERATED PASSWORD;
 
 @CREATE USER@ is equivalent to @CREATE ROLE@ where the @LOGIN@ option is @true@. So, the following pairs of statements are equivalent:
 
@@ -1561,7 +1565,6 @@ bc(syntax)..
 <alter-user-statement> ::= ALTER USER (IF EXISTS)? <identifier> ( WITH <option> ( AND <option> )* )?
 
 <option> ::= ("HASHED")? PASSWORD = <string>
-           | GENERATED PASSWORD
            | SUPERUSER
            | NOSUPERUSER
 p. 
@@ -2729,6 +2732,7 @@ h3. 3.4.8
 
 * Add support for the BETWEEN operator in WHERE clauses (see "CASSANDRA-19604":https://issues.apache.org/jira/browse/CASSANDRA-19604)
 * Add support for GENERATED PASSWORD clause (see "CASSANDRA-17457":https://issues.apache.org/jira/browse/CASSANDRA-17457)
+* Add support for GENERATED ROLE clause (see "CASSANDRA-17457":https://issues.apache.org/jira/browse/CASSANDRA-20902)
 
 h3. 3.4.7
 

doc/modules/cassandra/nav.adoc

@@ -110,6 +110,7 @@
 **** xref:cassandra:managing/operating/transientreplication.adoc[Transient replication]
 **** xref:cassandra:managing/operating/virtualtables.adoc[Virtual tables]
 **** xref:cassandra:managing/operating/password_validation.adoc[Password validation]
+**** xref:cassandra:managing/operating/role_name_generation.adoc[Role name generation]
 **** xref:cassandra:managing/operating/onboarding-to-accord.adoc[]
 *** xref:cassandra:managing/tools/index.adoc[Tools]
 **** xref:cassandra:managing/tools/cqlsh.adoc[cqlsh: the CQL shell]

doc/modules/cassandra/pages/managing/operating/index.adoc

@@ -20,4 +20,5 @@
 * xref:cassandra:managing/operating/transientreplication.adoc[Transient replication]
 * xref:cassandra:managing/operating/virtualtables.adoc[Virtual tables]
 * xref:cassandra:managing/operating/password_validation.adoc[Password validation]
+* xref:cassandra:managing/operating/role_name_generation.adoc[Role name generation]
 * xref:cassandra:managing/operating/onboarding-to-accord.adoc[]

doc/modules/cassandra/pages/managing/operating/password_validation.adoc

@@ -50,7 +50,7 @@ the password guardrail provides `CassandraPasswordValidator` by extending `Value
 while passwords are generated by `CassandraPasswordGenerator` by extending `ValueGenerator`.
 Both components work with passwords as `String` type values.
 
-Password validation and generation are configured in `cassandra.yaml` file under the `password_validator` section.
+Password validation and generation are configured in `cassandra.yaml` file under the `password_policy` section.
 Let’s explore the key configuration properties available.
 
 First, the `class_name` and `generator_class_name` parameters
@@ -66,7 +66,7 @@ However, the framework is designed with flexibility in mind, allowing organizati
 and generation rules that align with their specific security policies and business requirements.
 
 ----
-password_validator:
+password_policy:
 # Implementation class of a validator. When not in form of FQCN, the
 # package name org.apache.cassandra.db.guardrails.validators is prepended.
 # By default, there is no validator.
@@ -243,12 +243,6 @@ We can create a role with generated password like this:
 cassandra@cqlsh> CREATE ROLE alice WITH GENERATED PASSWORD AND LOGIN = true;
 ----
 
-or by `CREATE USER`:
-
-----
-cassandra@cqlsh> CREATE USER alice WITH GENERATED PASSWORD;
-----
-
 When a password is generated for `alice` she can log in:
 
 ----
@@ -274,7 +268,7 @@ classname = PlainTextAuthProvider
 ----
 
 It is also possible to configure password validators in such a way that a user does not see why a password failed.
-This is driven by configuration property for `password_validator` called `detailed_messages`. When set to `false`,
+This is driven by configuration property for `password_policy` called `detailed_messages`. When set to `false`,
 the violations will be very brief:
 
 ----
@@ -299,11 +293,12 @@ implementation and may be addressed in future updates.
 Since this solution is based on guardrails which are configurable via JMX in runtime, same hold for
 password validator, also configured via `GuardrailsMBean` as any other guardrails. There are two methods exposed:
 
-* `Map<String, Object> getPasswordValidatorConfig()` - gets password validator configuration
-* `void reconfigurePasswordValidator(Map<String, Object> config)` - reconfigures the password validator by reading
-and parsing the configuration from the provided map. Reconfiguration of password validator in runtime is considered
+* `Map<String, Object> getPasswordPolicy()` - gets password validator configuration as JSON string,
+* `void setPasswordPolicy(String value)` - reconfigures the password validator by reading
+and parsing the configuration from the provided String, being JSON representation of configuration map.
+Reconfiguration of password validator in runtime is considered
 to be very sensitive operation. If an operator evaluates the reconfiguration in runtime is not allowed, they
-might set `password_validator_reconfiguration_enabled` to `false` in `cassandra.yaml` to disable it.
+might set `password_policy_reconfiguration_enabled` to `false` in `cassandra.yaml` to disable it.
 
 === Diagnostic events