Chapter 6. Security

One-way TLS is configured in the URL of the relevant acceptor in broker.xml. Here is a very basic acceptor configuration which does not use TLS:

<acceptor name="artemis">tcp://0.0.0.0:61616</acceptor>

Here is that same acceptor configured to use one-way TLS:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>

This acceptor uses three additional parameters - sslEnabled, keyStorePath, and keyStorePassword. These, at least, are required to enable one-way TLS.

Two-way TLS uses the same sslEnabled, keyStorePath, and keyStorePassword properties as one-way TLS, but it adds needClientAuth to tell the client it should present a certificate of its own. For example:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>

This configuration assumes that the client’s certificate is signed by a trusted provider. If the client’s certificate is not signed by a trusted provider (it is self-signed, for example) then the server needs to import the client’s certificate into a trust-store and configure the acceptor with trustStorePath and trustStorePassword. For example:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>

TLS Configuration Details

Below are configuration details to be aware of:

The JAAS certificate authentication login module requires TLS to be in use and clients must be configured with their own certificates. In this scenario, authentication is actually performed during the TLS handshake, not directly by the JAAS certificate authentication plug-in.

The role of the plug-in is as follows:

The JAAS certificate login module stores a collection of certificate DNs in a pair of flat files. The files associate a username and a list of group IDs with each Distinguished Name.

The certificate login module is implemented by the org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule class.

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule 1
        debug=true 2
        org.apache.activemq.jaas.textfiledn.user="artemis-users.properties" 3
        org.apache.activemq.jaas.textfiledn.role="artemis-roles.properties"; 4
};

The artemis-users.properties file consists of a list of properties with the user=StringifiedSubjectDN (where the string encoding is specified by RFC 2253):

system=CN=system,O=Progress,C=US 1
user=CN=humble user,O=Progress,C=US
guest=CN=anon,O=Progress,C=DE

The artemis-roles.properties file follows the pattern of role=user where user can be either a single user or a comma-separated list of users:

admins=system
users=system,user 1
guests=guest

Use the SASL EXTERNAL mechanism configuration parameter to configure your AQMP client for certificate-based authentication when connecting to a broker.

The broker authenticates the TSL/SSL certificate of your AMQP client in the same way that it authenticates any certificate:

Prerequisites

Before you can configure your AMQP clients to use certificate-based authentication, you must complete the following tasks:

Procedure

To enable your AMQP client to use certificate-based authentication, add configuration parameters to the URI that the client uses to connect to a broker.

Additional Resources

It is possible to combine login modules to accommodate more complex use cases. The most common reason to combine login modules is to support authentication for both anonymous users and users who submit credentials.

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient 1
      debug=true
      org.apache.activemq.jaas.properties.user="artemis-users.properties"
      org.apache.activemq.jaas.properties.role="artemis-roles.properties";

  org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient 2
      debug=true
      org.apache.activemq.jaas.guest.user="guest"
      org.apache.activemq.jaas.guest.role="restricted";
};

The following example shows how to configure a JAAS login entry for the use case where only those users with no credentials are logged in as guests. Note that the order of the login modules is reversed and the flag attached to the properties login module is changed to requisite.

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient 1
        debug=true
       credentialsInvalidate=true 2
       org.apache.activemq.jaas.guest.user="guest"
       org.apache.activemq.jaas.guest.role="guests";

    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite 3
        debug=true
        org.apache.activemq.jaas.properties.user="artemis-users.properties"
        org.apache.activemq.jaas.properties.role="artemis-roles.properties";
};

Below is an example security block from a broker.xml file. The various configuration options based on this example are explained in this section.

<security-setting match="globalqueues.europe.#"> 1
   <permission type="createDurableQueue" roles="admin"/> 2
   <permission type="deleteDurableQueue" roles="admin"/> 3
   <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/> 4
   <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/> 5
   <permission type="send" roles="admin, europe-users"/> 6
   <permission type="consume" roles="admin, europe-users"/> 7
</security-setting>

The mapping between a user and what roles they have is handled by the security manager. AMQ Broker ships with a user manager that reads user credentials from a file on disk, and can also plug into JAAS or JBoss Application Server security.

There can be multiple security-setting elements in each XML file, or none, depending on requirements. When the broker.xml file contains multiple security-setting elements that can apply to a set of addresses, the most specific match takes precedence.

Let us look at an example of that, here’s another security-setting block:

<security-setting match="globalqueues.europe.orders.#">
   <permission type="send" roles="europe-users"/>
   <permission type="consume" roles="europe-users"/>
</security-setting>

In this security-setting block the match globalqueues.europe.orders.# is more specific than the previous match 'globalqueues.europe.\#'. So any addresses which match 'globalqueues.europe.orders.\#' will take their security settings only from the latter security-setting block.

Note that settings are not inherited from the former block. All the settings will be taken from the more specific matching block, so for the address globalqueues.europe.orders.plastics the only permissions that exist are send and consume for the role europe-users. The permissions createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue are not inherited from the other security-setting block.

By not inheriting permissions, you can effectively deny permissions in more specific security-setting blocks by simply not specifying them. Otherwise it would not be possible to deny permissions in sub-groups of addresses.

Sometimes it is helpful to set particular limits on what certain users can do beyond the normal security settings related to authorization and authentication. For example, one can limit how many connections a user can create or how many queues a user can create.

<resource-limit-settings>
   <resource-limit-setting match="myUser">
      <max-connections>5</max-connections>
      <max-queues>3</max-queues>
   </resource-limit-setting>
</resource-limit-settings>

The LDAP login module enables authentication and authorization by checking the incoming credentials against user data stored in a central X.500 directory server. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule.

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
     debug=true 1
     initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory 2
     connectionURL="ldap://localhost:10389" 3
     connectionUsername="uid=admin,ou=system" 4
     connectionPassword=secret 5
     connectionProtocol=s 6
     authentication=simple 7
     userBase="dc=example,dc=com" 8
     userSearchMatching="(uid={0})" 9
     userSearchSubtree=true 10
     userRoleName= 11
     roleBase="dc=example,dc=com" 12
     roleName=cn 13
     roleSearchMatching="(member={0})" 14
     roleSearchSubtree=true 15
     ;
};

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
     debug=true
     initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
     connectionURL="LDAP://localhost:389"
     connectionUsername="CN=Administrator,CN=Users,DC=example,DC=com"
     connectionPassword=redhat.123
     connectionProtocol=s
     authentication=simple
     userBase="dc=example,dc=com"
     userSearchMatching="(CN={0})"
     userSearchSubtree=true
     roleBase="dc=example,dc=com"
     roleName=cn
     roleSearchMatching="(member={0})"
     roleSearchSubtree=true
     ;
};

The LegacyLDAPSecuritySettingPlugin security-setting-plugin will read the security information that was previously handled by LDAPAuthorizationMap and the cachedLDAPAuthorizationMap in Apache A-MQ 6 and turn it into corresponding security settings where possible.

The security implementations of the two brokers do not match perfectly so some translation must occur to achieve near equivalent functionality.

Here is an example of the plugin’s configuration:

<security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin"> 1
 <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/> 2
 <setting name="connectionURL" value="ldap://localhost:1024"/> 3
 <setting name="connectionUsername" value="uid=admin,ou=system"/> 4
 <setting name="connectionPassword" value="secret"/> 5
 <setting name="connectionProtocol" value="s"/> 6
 <setting name="authentication" value="simple"/> 7
</security-setting-plugin>

Other possible settings not shown in the example above are:

The name of the queue or topic defined in LDAP will serve as the "match" for the security-setting, the permission value will be mapped from the A-MQ 6 type to the AMQ 7 type, and the role will be mapped as-is. Since the name of the queue or topic coming from LDAP will server as the "match" for the security-setting the security-setting may not be applied as expected to JMS destinations since AMQ 7 always prefixes JMS destinations with "jms.queue." or "jms.topic." as necessary.

A-MQ 6 only has three permission types - read, write, and admin. These permission types are described on the ActiveMQ website; http://activemq.apache.org/security.html.

However, as described previously, AMQ 7 has 10 permission types:

The list below shows how the old types are mapped to the new types:

As mentioned, there are a few places where a translation was performed to achieve some equivalence:

Because organizations frequently securely store data with LDAP, the login.config file can contain the configuration required for the broker to communicate with the organization’s LDAP server. This configuration file usually includes a password to log in to the LDAP server, so this password needs to be masked.

The login.config file now contains a masked password. Because the password is wrapped with the ENC() identifier, AMQ Broker decrypts it before it is used.

AMQ Broker integrates with Kerberos security credentials by using the GSSAPI mechanism from the Simple Authentication and Security Layer (SASL) framework. To use Kerberos in AMQ Broker, each acceptor authenticating or authorizing clients that use a Kerberos credential must be configured to used the GSSAPI mechanism.

Prerequisites

You must deploy and configure a Kerberos infrastructure before AMQ Broker can authenticate and authorize Kerberos credentials.

Procedure

Related Information

See About Acceptors for more information about acceptors.

AMQ Broker supports Kerberos authentication of AMQP connections that use the GSSAPI mechanism from the Simple Authentication and Security Layer (SASL) framework.

A broker acquires its Kerberos acceptor credentials by using the Java Authentication and Authorization Service (JAAS). The JAAS library included with your Java installation is packaged with a login module, Krb5LoginModule, that authenticates Kerberos credentials. See the documentation from your Java vendor for more information about their Krb5LoginModule. For example, Oracle provides information about their Krb5LoginModule login module as part of their Java 8 documentation.

Prerequisites

You must enable the GSSAPI mechanism of an acceptor before it can authenticate AMQP connections using Kerberos security credentials.

Procedure

Related Information

See Network Connections and Kerberos, for more information about enabling the GSSAPI mechanism in AMQ Broker.

<acceptor name="amqp">
tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN;saslLoginConfigScope=alternative-sasl-gssapi`
</acceptor>

AMQ Broker is packaged with an implementation of the JAAS Krb5LoginModule for use by other security modules when mapping roles. The module adds a Kerberos-authenticated Peer Principal to the Subject’s principal set as an AMQ Broker UserPrincipal. The credentials can then be passed to a PropertiesLoginModule or LDAPLoginModule, which maps the Kerberos-authenticated Peer Principal to an AMQ Broker role.

Prerequisites

You must enable the GSSAPI mechanism of an acceptor before it can authorize AMQP connections using Kerberos security credentials.

Procedure

Related Information

See Network Connections and Kerberos for more information about enabling the GSSAPI mechanism in AMQ Broker.

See Users and Roles for more information about the PropertiesLoginModule.

See Integrating with LDAP for more information about the LDAPLoginModule.