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
Gary Tully
parent
0527e07129
commit
28a10450b7
|
|
@ -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 {
|
||||
|
||||
|
|
|
|||
|
|
@ -1004,15 +1004,28 @@ guests=guest
|
|||
```
|
||||
|
||||
|
||||
#### 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.
|
||||
#### 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).
|
||||
|
||||
```
|
||||
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
|
||||
|
|
@ -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
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue