[GitHub] [activemq-artemis] gtully commented on a change in pull request #3770: ARTEMIS-3106 - add some doc for SASL SCRAM-SHA

[GitBox <gi...@apache.org>]

gtully commented on a change in pull request #3770:
URL: https://github.com/apache/activemq-artemis/pull/3770#discussion_r715454162



##########
File path: docs/user-manual/en/security.md
##########
@@ -1087,22 +1087,77 @@ amqp-sasl-gssapi {
 };
 ```
 
+#### SCRAM-SHA SASL Mechanism
+
+SCRAM (Salted Challenge Response Authentication Mechanism) is an authentication protocol that can establish mutual
+authentication using passwords. Apache ActiveMQ Artemis AMQP supports SASL SCRAM-SHA-512 to provide authentication
+on both unencrypted and TLS-encrypted client connections.
+
+The following properties of SCRAM make it safe to use SCRAM-SHA even on unencrypted connections:
+
+- The passwords are not sent in the clear over the communication channel. Both the client and the server are
+challenged to offer proof that they know the password of the authenticating user. Only the proof is exchanged.
+- The server and client each generate a new challenge for each authentication exchange. This means that the exchange is resilient against
+replay attacks.
+
+
+##### Configuring the server to use SCRAM-SHA
+
+The `SCRAM-SHA-256` SASL mechanism must be enabled on the AMQP acceptor in
+`broker.xml` by adding it to the `saslMechanisms` list url parameter. In this
+example, SASL is restricted to just the SCRAM-SHA-256 mechanism:
+
+````
+  <acceptor name="amqp">tcp://localhost:5672?protocols=AMQP;saslMechanisms=SCRAM-SHA-256;saslLoginConfigScope=amqp-sasl-scram
+````
+
+Of note is the reference to the sasl login config scope ``saslLoginConfigScope=amqp-sasl-scram`` that holds the relevant SCRAM login module.
+The mechanism  makes use of JAAS to complete the SASL exchanges.
+
+An example configuration scope for `login.config` that will implement SCRAM-SHA-256 using property files, is as follows:
+
+```
+amqp-sasl-scram {
+   org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule required
+       org.apache.activemq.jaas.properties.user="artemis-users.properties"
+       org.apache.activemq.jaas.properties.role="artemis-roles.properties";
+};
+```
+
+##### Configuring a user with SCRAM-SHA data on the server
+
+With SCRAM-SHA, the server's users properties file do not contain any passwords, instead they contain derivative data that
+can be used to respond to a challenge.
+The secure encoded form of the password must be generated or registered using the main method of
+org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule from the artemis-server module and inserting
+the resulting lines into your desired user properties file.
+
+````
+java -cp ... org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule <username> <password> [<iterations>]

Review comment:
       I had the same thought, but -cp lib/* did not work, till it is quoted from the shell! will tidy this up. thanks for all the feedback, much appreciated




-- 
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: gitbox-unsubscribe@activemq.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org