This is an automated email from the ASF dual-hosted git repository.
gtully pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
The following commit(s) were added to refs/heads/main by this push:
new 28a1045 ARTEMIS-3106 - add some doc for SASL SCRAM-SHA
28a1045 is described below
commit 28a10450b7cba082b9de86eaa16d59cfcca38207
Author: gtully <gary.tu...@gmail.com>
AuthorDate: Thu Sep 23 17:10:36 2021 +0100
ARTEMIS-3106 - add some doc for SASL SCRAM-SHA
Update docs/user-manual/en/security.md
Co-authored-by: Robbie Gemmell <rob...@apache.org>
---
.../spi/core/security/jaas/SCRAMLoginModule.java | 2 +-
docs/user-manual/en/security.md | 132 +++++++++++++++++----
2 files changed, 107 insertions(+), 27 deletions(-)
diff --git
a/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/SCRAMLoginModule.java
b/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/SCRAMLoginModule.java
index 4da5200..e4b44f7 100644
---
a/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/SCRAMLoginModule.java
+++
b/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/SCRAMLoginModule.java
@@ -17,7 +17,7 @@
package org.apache.activemq.artemis.spi.core.security.jaas;
/**
- * Handles the actual login after channel authentication has succeed
+ * Handles the actual login after channel authentication has succeeded
*/
public class SCRAMLoginModule extends AbstractPrincipalLoginModule {
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
index 3fa7de3..96619ba 100644
--- a/docs/user-manual/en/security.md
+++ b/docs/user-manual/en/security.md
@@ -1004,15 +1004,28 @@ guests=guest
```
-#### Krb5LoginModule
+#### SCRAMPropertiesLoginModule
+The SCRAM properties login module implements the SASL challenge response for
the SCRAM-SHA mechanism.
+The data in the properties file reference via
`org.apache.activemq.jaas.properties.user` needs to be
+generated by the login module it's self, as part of user registration. It
contains proof of knowledge
+of passwords, rather than passwords themselves. For more usage detail refer to
[SCRAM-SHA SASL Mechanism](#SCRAM-SHA-SASL-Mechanism).
-The Kerberos login module is used to propagate a validated SASL GSSAPI
kerberos token
-identity into a validated JAAS UserPrincipal. This allows subsequent login
modules to
-do role mapping for the kerberos identity.
+```
+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";
+};
+```
+
+#### SCRAMLoginModule
+The SCRAM login module converts a valid SASL SCRAM-SHA Authenticated identity
into a JAAS User Principal. This
+Principal can then be used for [role mapping](#Role-Mapping).
```
-org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
- ;
+{
+ org.apache.activemq.artemis.spi.core.security.jaas.SCRAMLoginModule
+};
```
#### ExternalCertificateLoginModule
@@ -1038,11 +1051,70 @@
org.apache.activemq.artemis.spi.core.security.jaas.PrincipalConversionLoginModul
principalClassList=org.apache.x.Principal,org.apache.y.Principal
;
```
-
+
+#### Krb5LoginModule
+
+The Kerberos login module is used to propagate a validated SASL GSSAPI
kerberos token
+identity into a validated JAAS UserPrincipal. This allows subsequent login
modules to
+do role mapping for the kerberos identity.
+
+```
+org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
+ ;
+```
+
The simplest way to make the login configuration available to JAAS is to add
the directory containing the file, `login.config`, to your CLASSPATH.
+### SCRAM-SHA SASL Mechanism
+
+SCRAM (Salted Challenge Response Authentication Mechanism) is an
authentication mechanism that can establish mutual
+authentication using passwords. Apache ActiveMQ Artemis supports SCRAM-SHA-256
and SCRAM-SHA-512 SASL mechanisms to provide authentication for AMQP
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. The
client is challenged to offer proof it knows the password of the authenticating
user, and the server is challenged to offer proof it had the password to
initialise its authentication store. Only the proof is exchanged.
+- The server and client each generate a new challenge for each authentication
exchange, making it resilient against replay attacks.
+
+
+#### Configuring the server to use SCRAM-SHA
+
+The desired SCRAM-SHA mechanisms must be enabled on the AMQP acceptor in
+`broker.xml` by adding them to the `saslMechanisms` list url parameter. In this
+example, SASL is restricted to only 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 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 artemis-users.properties file.
+
+````
+java -cp "<distro-lib-dir>/*"
org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule
<username> <password> [<iterations>]
+````
+
+An sample of the output can be found in the amqp examples,
examples/protocols/amqp/sasl-scram/src/main/resources/activemq/server0/artemis-users.properties
+
### Kerberos Authentication
You must have the Kerberos infrastructure set up in your deployment environment
@@ -1087,22 +1159,37 @@ amqp-sasl-gssapi {
};
```
-#### Role Mapping
+##### TLS Kerberos Cipher Suites
+
+The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) defines TLS Kerberos
+cipher suites that can be used by TLS to negotiate Kerberos authentication. The
+cypher suites offered by rfc2712 are dated and insecure and rfc2712 has been
+superseded by SASL GSSAPI. However, for clients that don't support SASL (core
+client), using TLS can provide Kerberos authentication over an *unsecure*
+channel.
+
-On the server, the Kerberos authenticated Peer Principal can be added to the
+### Role Mapping
+
+On the server, a Kerberos or SCRAM-SHA JAAS authenticated Principal must be
added to the
Subject's principal set as an Apache ActiveMQ Artemis UserPrincipal using the
-Apache ActiveMQ Artemis `Krb5LoginModule` login module. The
-[PropertiesLoginModule](#propertiesloginmodule) or
+corresponding Apache ActiveMQ Artemis `Krb5LoginModule` or `SCRAMLoginModule`
login modules.
+They are separate to allow conversion and role mapping to be as restrictive or
permissive as desired.
+
+The [PropertiesLoginModule](#propertiesloginmodule) or
[LDAPLoginModule](#ldaploginmodule) can then be used to map the authenticated
-Kerberos Peer Principal to an Apache ActiveMQ Artemis
-[Role](#role-based-security-for-addresses). Note that the Kerberos Peer
-Principal does not exist as an Apache ActiveMQ Artemis user, only as a role
+ Principal to an Apache ActiveMQ Artemis
+[Role](#role-based-security-for-addresses).
+Note that in the case of Kerberos, the Peer Principal does not exist as an
Apache ActiveMQ Artemis user, only as a role
member.
+In the following example, any existing Kerberos authenticated peer will
convert to an Apache ActiveMQ Artemis user principal and will
+have role mapping applied by the LDAPLoginModule as appropriate.
```
-org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
+activemq {
+ org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
;
-org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
+ org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
connectionURL="ldap://localhost:1024";
authentication=GSSAPI
@@ -1117,17 +1204,9 @@
org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
roleSearchMatching="(member={0})"
roleSearchSubtree=false
;
+};
```
-#### TLS Kerberos Cipher Suites
-
-The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) defines TLS Kerberos
-cipher suites that can be used by TLS to negotiate Kerberos authentication. The
-cypher suites offered by rfc2712 are dated and insecure and rfc2712 has been
-superseded by SASL GSSAPI. However, for clients that don't support SASL (core
-client), using TLS can provide Kerberos authentication over an *unsecure*
-channel.
-
### Basic Security Manager
As the name suggests, the `ActiveMQBasicSecurityManager` is _basic_. It is not
@@ -1269,7 +1348,8 @@ Note: Role mapping is additive. That means the user will
keep the original role(
Note: This role mapping only affects the roles which are used to authorize
queue access through the configured acceptors. It can not be used to map the
role required to access the web console.
## SASL
-[AMQP](using-AMQP.md) supports SASL. The following mechanisms are supported;
PLAIN, EXTERNAL, ANONYMOUS, GSSAPI.
+[AMQP](using-AMQP.md) supports SASL. The following mechanisms are supported:
+ PLAIN, EXTERNAL, ANONYMOUS, GSSAPI, SCRAM-SHA.
The published list can be constrained via the amqp acceptor `saslMechanisms`
property.
Note: EXTERNAL will only be chosen if a subject is available from the TLS
client certificate.
