yifan-c commented on code in PR #2372: URL: https://github.com/apache/cassandra/pull/2372#discussion_r1274104899
########## doc/modules/cassandra/pages/getting-started/mtlsauthenticators.adoc: ########## @@ -0,0 +1,125 @@ += Getting started with mTLS authenticators + +When a certificate based authentication protocol like TLS is used for client and +Internode connections, `MutualTlsAuthenticator` & `MutualTlsInternodeAuthenticator` +can be used for the authentication by leveraging the client certificates from the +SSL handshake. + +After SSL handshake, identity from the client certificates is extracted and only +authorized users will be granted access. + +== What is an Identity + +One can define their own identity for certificates by extracting some fields or +information from the certificates. one can implement the interface `MutualTlsCertificateValidator` +to provide logic for validating & extracting identity from the certificates. + +There is a default implementation of `MutualTlsCertificateValidator` with +https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/[SPIFFE] as the identity +of the certifactes.This requires spiffe to be present in the SAN of the certificate. +One can implement their own validator that suits their needs. + +For example, instead of using `SPIFFE` based validator a `CN` based validator can be +implemented. + +== Configuring mTLS authenticator for client connections + +Note that the following steps uses SPIFFE identity as an example, If you are using +a custom validator, use appropriate identity in place of `spiffe://testdomain.com/testIdentifier/testValue`. + +*STEP 1: Add authorized users to system_auth.identity_to_roles table* + +Note that only superusers can add/remove identities. Client certificates with the identities +in this table will be trusted by C*. +[source, plaintext] +---- +ADD IDENTITY 'spiffe://testdomain.com/testIdentifier/testValue' TO ROLE 'read_only_user' +---- + +*STEP 2: Configure Cassandra.yaml with right properties* + +`client_encryption_options` configuration for mTLS connections +[source, plaintext] +---- +client_encryption_options: + enabled: true + optional: false + keystore: conf/.keystore + keystore_password: cassandra + truststore: conf/.truststore + truststore_password: cassandra + require_client_auth: false // to enable mTLS +---- +Configure mTLS authenticator and the validator for client connections . If you are +implementing a custom validator, use that instead of Spiffe validator +[source, plaintext] +---- +authenticator: + class_name : org.apache.cassandra.auth.MutualTlsAuthenticator + parameters : + validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator +---- + +*STEP 3: Bounce the cluster* + +After the bounce, C* will accept mTLS connections from the clients and if their +identity is present in the `identity_to_roles` table, access will be granted. + +== Configuring mTLS authenticator for Internode connections + +Internode authenticator trusts certificates which have the same identity as the node. +When a node is making an outbound connection to another node, it uses the +certificate configured in `server_encryption_options.outbound_keystore`. +During the start of the node, identity is extracted from the outbound keystore and +connections from other nodes who have the same identity will be trusted. + +For example, if the if a node has `testIdentity` embedded in the certificate in +outbound keystore, It trusts connections from other nodes when their certificates +have `testIdentity` embedded in them. + +*STEP 1: Configure server_encryption_options in cassandra.yaml* + +[source, plaintext] +---- +server_encryption_options: + internode_encryption: all + optional: true + keystore: conf/.keystore + keystore_password: cassandra + outbound_keystore: conf/.outbound_keystore + outbound_keystore_password: cassandra + require_client_auth: true // for enabling mTLS + truststore: conf/.truststore + truststore_password: cassandra +---- + +*STEP 2: Configure Internode Authenticator and Validator* + +Configure mTLS Internode authenticator and validator. If you are +implementing a custom validator, use that instead of Spiffe validator +[source, plaintext] +---- +internode_authenticator: + class_name : org.apache.cassandra.auth.MutualTlsInternodeAuthenticator + parameters : + validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator +---- + +*STEP 3: Bounce the cluster* +Once the cluster is bounced all internode communications will be authenticated by mTLS +authenticator. Note that if new nodes join the ring a bounce is not required. + +== Migration from existing password based authentication +* For client connections, since the migration will not happen overnight, +the operators can run cassandra in optional mTLS mode and use +`MutualTlsWithPasswordFallbackAuthenticator` which will accept both mTLS & password +based connections, based on the type of connection client is making. These settings +can be configured in `cassandra.yaml`. Once all the clients migrate to using mTLS, +turn off optional mode and set the authenticator to be `MutualTlsAuthenticator`. From +that point only mTLS client connections will be accepted. + +* For Internode connections, while doing rolling upgrades from non-mTLS based configuration +to mTLS based configuration, use optional mode for the new nodes to be able to connect to +old nodes which are still using non-mTLS based configuation during upgrade. After this, change Review Comment: ```suggestion old nodes which are still using non-mTLS based configuration during upgrade. After this, change ``` ########## src/java/org/apache/cassandra/auth/AuthConfig.java: ########## @@ -61,7 +61,7 @@ public static void applyAuth() // the configuration options regarding credentials caching are only guaranteed to // work with PasswordAuthenticator, so log a message if some other authenticator // is in use and non-default values are detected - if (!(authenticator instanceof PasswordAuthenticator) + if (!(authenticator instanceof PasswordAuthenticator || authenticator instanceof MutualTlsAuthenticator) Review Comment: Is the condition equivalent to `!authenticator.requireAuthentication()`? ########## doc/modules/cassandra/pages/getting-started/mtlsauthenticators.adoc: ########## @@ -0,0 +1,125 @@ += Getting started with mTLS authenticators + +When a certificate based authentication protocol like TLS is used for client and +Internode connections, `MutualTlsAuthenticator` & `MutualTlsInternodeAuthenticator` +can be used for the authentication by leveraging the client certificates from the +SSL handshake. + +After SSL handshake, identity from the client certificates is extracted and only +authorized users will be granted access. + +== What is an Identity + +One can define their own identity for certificates by extracting some fields or +information from the certificates. one can implement the interface `MutualTlsCertificateValidator` +to provide logic for validating & extracting identity from the certificates. + +There is a default implementation of `MutualTlsCertificateValidator` with +https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/[SPIFFE] as the identity +of the certifactes.This requires spiffe to be present in the SAN of the certificate. Review Comment: ```suggestion of the certificates.This requires spiffe to be present in the SAN of the certificate. ``` ########## doc/modules/cassandra/pages/getting-started/mtlsauthenticators.adoc: ########## @@ -67,16 +67,23 @@ identity is present in the `identity_to_roles` table, access will be granted. == Configuring mTLS authenticator for Internode connections -Internode authenticator trusts certificates which have the same identity as the node. +Internode authenticator trusts certificates whose identities are present in +`internode_authenticator.parameters.trusted_peer_identities` if configured. + +Otherwise, it trusts conections which have the same identity as the node. Review Comment: ```suggestion Otherwise, it trusts connections which have the same identity as the node. ``` ########## doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc: ########## @@ -2235,6 +2235,57 @@ LIST ROLES; but only roles with the `LOGIN` privilege are included in the output. +[[databaseIdentity]] +=== Database Identities + +[[AddIdentityStmt]] +==== ADD IDENTITY + +_Syntax:_ + +bc(syntax).. + +::= ADD IDENTITY ( IF NOT EXISTS )? TO ROLE ? + +_Sample:_ + +bc(sample). + +ADD IDENTITY 'id1' TO ROLE 'role1'; + +Only a `SUPERUSER` can add an identity Review Comment: Is it still true? Asking because `org.apache.cassandra.cql3.statements.CreateRoleStatement#authorize` checks for CREATE permission not SUPERUSER. -- 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]
