Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ARTEMIS-3106 - add some doc for SASL SCRAM-SHA 

Update docs/user-manual/en/security.md
Co-authored-by: Robbie Gemmell <robbie@apache.org>
This commit is contained in:
gtully 2021-09-23 17:10:36 +01:00 committed by Gary Tully
parent 0527e07129
commit 28a10450b7
2 changed files with 108 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/SCRAMLoginModule.java
View File

@ -17,7 +17,7 @@
package org.apache.activemq.artemis.spi.core.security.jaas; 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 { public class SCRAMLoginModule extends AbstractPrincipalLoginModule {

134
docs/user-manual/en/security.md
View File

@ -1004,15 +1004,28 @@ guests=guest
``` ```
#### Krb5LoginModule #### SCRAMPropertiesLoginModule
The SCRAM properties login module implements the SASL challenge response for the SCRAM-SHA mechanism.
The Kerberos login module is used to propagate a validated SASL GSSAPI kerberos token The data in the properties file reference via `org.apache.activemq.jaas.properties.user` needs to be
identity into a validated JAAS UserPrincipal. This allows subsequent login modules to generated by the login module it's self, as part of user registration. It contains proof of knowledge
do role mapping for the kerberos identity. of passwords, rather than passwords themselves. For more usage detail refer to [SCRAM-SHA SASL Mechanism](#SCRAM-SHA-SASL-Mechanism).
``` ```
org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required 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.SCRAMLoginModule
};
``` ```
#### ExternalCertificateLoginModule #### ExternalCertificateLoginModule
@ -1038,11 +1051,70 @@ org.apache.activemq.artemis.spi.core.security.jaas.PrincipalConversionLoginModul
principalClassList=org.apache.x.Principal,org.apache.y.Principal 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 simplest way to make the login configuration available to JAAS is to add
the directory containing the file, `login.config`, to your CLASSPATH. 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 ### Kerberos Authentication
You must have the Kerberos infrastructure set up in your deployment environment 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
On the server, the Kerberos authenticated Peer Principal can be added to the 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.
### 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 Subject's principal set as an Apache ActiveMQ Artemis UserPrincipal using the
Apache ActiveMQ Artemis `Krb5LoginModule` login module. The corresponding Apache ActiveMQ Artemis `Krb5LoginModule` or `SCRAMLoginModule` login modules.
[PropertiesLoginModule](#propertiesloginmodule) or 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 [LDAPLoginModule](#ldaploginmodule) can then be used to map the authenticated
Kerberos Peer Principal to an Apache ActiveMQ Artemis Principal to an Apache ActiveMQ Artemis
[Role](#role-based-security-for-addresses). Note that the Kerberos Peer [Role](#role-based-security-for-addresses).
Principal does not exist as an Apache ActiveMQ Artemis user, only as a role Note that in the case of Kerberos, the Peer Principal does not exist as an Apache ActiveMQ Artemis user, only as a role
member. 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 initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
connectionURL="ldap://localhost:1024" connectionURL="ldap://localhost:1024"
authentication=GSSAPI authentication=GSSAPI
@ -1117,17 +1204,9 @@ org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
roleSearchMatching="(member={0})" roleSearchMatching="(member={0})"
roleSearchSubtree=false 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 ### Basic Security Manager
As the name suggests, the `ActiveMQBasicSecurityManager` is _basic_. It is not 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. 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 ## 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. 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. Note: EXTERNAL will only be chosen if a subject is available from the TLS client certificate.