jyothsnakonisa commented on code in PR #2372: URL: https://github.com/apache/cassandra/pull/2372#discussion_r1276618063
########## doc/modules/cassandra/pages/getting-started/mtlsauthenticators.adoc: ########## @@ -0,0 +1,133 @@ += 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 certificates.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 users with permissions to create/modify roles 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 whose identities are present in +`internode_authenticator.parameters.trusted_peer_identities` if configured. + +Otherwise, it trusts connections 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 if +`trusted_peer_identities` is not configured. + +For example, 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. + +There is an optional configuration `node_identity` that can be used to verify identity +extracted from the keystore to avoid any configuration errors. + +*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 Review Comment: If the authenticator is not mTLS authenticator, then `require_client_auth: false` should be the configuration. In case of internode mtls authentication, we need to explicitly set this to be true. -- 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]
