Chapter 5. Securing brokers

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. For a given acceptor, add the sslEnabled key and set the value to true. In addition, add the keyStorePath and keyStorePassword keys. Set values that correspond to your broker key store. For example:

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

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. For the acceptor that you previously configured for one-way TLS, add the needClientAuth key. Set the value to true. For example:

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

3. The configuration in the preceding step 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 broker needs to import the client’s certificate into a trust store. In this case, add the trustStorePath and trustStorePassword keys. Set values that correspond to your broker trust store. 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>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Within the security-settings element, add a security-setting element to configure permissions. For example:

   <security-settings>
       <security-setting match="#">
           <permission type="createDurableQueue" roles="user"/>
           <permission type="deleteDurableQueue" roles="user"/>
           <permission type="createNonDurableQueue" roles="user"/>
           <permission type="deleteNonDurableQueue" roles="user"/>
           <permission type="send" roles="user"/>
           <permission type="consume" roles="user"/>
       </security-setting>
   </security-settings>

   The preceding configuration assigns specific permissions for all queues to members of the user role.

3. Open the <broker_instance_dir>/etc/login.config file.

4. Configure the LDAP login module, based on the directory service you are using.

   1. If you are using the Microsoft Active Directory directory service, add a configuration that resembles this example:

      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,OU=System,DC=example,DC=com"
           connectionPassword=redhat.123
           connectionProtocol=s
           connectionTimeout="5000"
           authentication=simple
           userBase="dc=example,dc=com"
           userSearchMatching="(CN={0})"
           userSearchSubtree=true
           readTimeout="5000"
           roleBase="dc=example,dc=com"
           roleName=cn
           roleSearchMatching="(member={0})"
           roleSearchSubtree=true
           ;
      };

      Note

      If you are using Microsoft Active Directory, and a value that you need to specify for an attribute of connectionUsername contains a space (for example, OU=System Accounts), then you must enclose the value in a pair of double quotes ("") and use a backslash (\) to escape each double quote in the pair. For example, connectionUsername="CN=Administrator,CN=Users,OU=\"System Accounts\",DC=example,DC=com".

   2. If you are using the ApacheDS directory service, add a configuration that resembles this example:

      activemq {
        org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
           debug=true
           initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
           connectionURL="ldap://localhost:10389"
           connectionUsername="uid=admin,ou=system"
           connectionPassword=secret
           connectionProtocol=s
           connectionTimeout=5000
           authentication=simple
           userBase="dc=example,dc=com"
           userSearchMatching="(uid={0})"
           userSearchSubtree=true
           userRoleName=
           readTimeout=5000
           roleBase="dc=example,dc=com"
           roleName=cn
           roleSearchMatching="(member={0})"
           roleSearchSubtree=true
           ;
      };

      debug

      Turn debugging on (true) or off (false). The default value is false.

      initialContextFactory

      Must always be set to com.sun.jndi.ldap.LdapCtxFactory

      connectionURL

      Location of the directory server using an LDAP URL, __<ldap://Host:Port>. One can optionally qualify this URL, by adding a forward slash, /, followed by the DN of a particular node in the directory tree. The default port of Apache DS is 10389 while for Microsoft AD the default is 389.

      connectionUsername

      Distinguished Name (DN) of the user that opens the connection to the directory server. For example, uid=admin,ou=system. Directory servers generally require clients to present username/password credentials in order to open a connection.

      connectionPassword

      Password that matches the DN from connectionUsername. In the directory server, in the Directory Information Tree (DIT), the password is normally stored as a userPassword attribute in the corresponding directory entry.

      connectionProtocol

      Any value is supported but is effectively unused. This option must be set explicitly because it has no default value.

      connectionTimeout

      Specify the maximum time, in milliseconds, that the broker can take to connect to the directory server. If the broker cannot connect to the directory sever within this time, it aborts the connection attempt. If you specify a value of zero or less for this property, the timeout value of the underlying TCP protocol is used instead. If you do not specify a value, the broker waits indefinitely to establish a connection, or the underlying network times out.

      When connection pooling has been requested for a connection, then this property specifies the maximum time that the broker waits for a connection when the maximum pool size has already been reached and all connections in the pool are in use. If you specify a value of zero or less, the broker waits indefinitely for a connection to become available. Otherwise, the broker aborts the connection attempt when the maximum wait time has been reached.

      authentication

      Specifies the authentication method used when binding to the LDAP server. This parameter can be set to either simple (which requires a username and password) or none (which allows anonymous access).

      userBase

      Select a particular subtree of the DIT to search for user entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=User,ou=ActiveMQ,ou=system, the search for user entries is restricted to the subtree beneath the ou=User,ou=ActiveMQ,ou=system node.

      userSearchMatching

      Specify an LDAP search filter, which is applied to the subtree selected by userBase. See the Section 5.4.1.1, “Search matching parameters” section below for more information.

      userSearchSubtree

      Specify the search depth for user entries, relative to the node specified by userBase. This option is a Boolean. Specifying a value of false means that the search tries to match one of the child entries of the userBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE). Specifying a value of true means that the search tries to match any entry belonging to the subtree of the userBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).

      userRoleName

      Name of the attribute of the user entry that contains a list of role names for the user. Role names are interpreted as group names by the broker’s authorization plug-in. If this option is omitted, no role names are extracted from the user entry.

      readTimeout

      Specify the maximum time, in milliseconds, that the broker can wait to receive a response from the directory server to an LDAP request. If the broker does not receive a response from the directory server in this time, the broker aborts the request. If you specify a value of zero or less, or you do not specify a value, the broker waits indefinitely for a response from the directory server to an LDAP request.

      roleBase

      If role data is stored directly in the directory server, one can use a combination of role options (roleBase, roleSearchMatching, roleSearchSubtree, and roleName) as an alternative to (or in addition to) specifying the userRoleName option. This option selects a particular subtree of the DIT to search for role/group entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=Group,ou=ActiveMQ,ou=system, the search for role/group entries is restricted to the subtree beneath the ou=Group,ou=ActiveMQ,ou=system node.

      roleName

      Attribute type of the role entry that contains the name of the role/group (such as C, O, OU, etc.). If this option is omitted the role search feature is effectively disabled.

      roleSearchMatching

      Specify an LDAP search filter, which is applied to the subtree selected by roleBase. See the Section 5.4.1.1, “Search matching parameters” section below for more information.

      roleSearchSubtree

      Specify the search depth for role entries, relative to the node specified by roleBase. If set to false (which is the default) the search tries to match one of the child entries of the roleBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE). If true it tries to match any entry belonging to the subtree of the roleBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).

      Note

      Apache DS uses the OID portion of DN path. Microsoft Active Directory uses the CN portion. For example, you might use a DN path such as oid=testuser,dc=example,dc=com in Apache DS, while you might use a DN path such as cn=testuser,dc=example,dc=com in Microsoft Active Directory.

5. Start or restart the broker (service or process).

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Within the security-settings element, add the security-setting-plugin element. For example:

   <security-settings>
       <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
           <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
           <setting name="connectionURL" value="ldap://localhost:1024"/>`ou=destinations,o=ActiveMQ,ou=system`
           <setting name="connectionUsername" value="uid=admin,ou=system"/>
           <setting name="connectionPassword" value="secret"/>
           <setting name="connectionProtocol" value="s"/>
           <setting name="authentication" value="simple"/>
       </security-setting-plugin>
   </security-settings>

   class-name

   The implementation is org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin.

   initialContextFactory

   The initial context factory used to connect to LDAP. It must always be set to com.sun.jndi.ldap.LdapCtxFactory (that is, the default value).

   connectionURL

   Specifies the location of the directory server using an LDAP URL, <ldap://Host:Port>. You can optionally qualify this URL by adding a forward slash, /, followed by the distinguished name (DN) of a particular node in the directory tree. For example, ldap://ldapserver:10389/ou=system. The default value is ldap://localhost:1024.

   connectionUsername

   The DN of the user that opens the connection to the directory server. For example, uid=admin,ou=system. Directory servers generally require clients to present username/password credentials in order to open a connection.

   connectionPassword

   The password that matches the DN from connectionUsername. In the directory server, in the Directory Information Tree (DIT), the password is normally stored as a userPassword attribute in the corresponding directory entry.

   connectionProtocol

   Currently unused. In the future, this option might allow you to select the Secure Socket Layer (SSL) for the connection to the directory server. This option must be set explicitly because it has no default value.

   authentication

   Specifies the authentication method used when binding to the LDAP server. Valid values for this parameter are simple (username and password) or none (anonymous). The default value is simple.

   Note

   Simple Authentication and Security Layer (SASL) authentication is not supported.

1. From a command prompt, use the mask utility to encrypt the password:

   $ <broker_instance_dir>/bin/artemis mask <password>

   result: 3a34fd21b82bf2a822fa49a8d8fa115d

2. Open the <broker_instance_dir>/etc/login.config file. Locate the connectionPassword parameter:

   connectionPassword = <password>

3. Replace the plain-text password with the encrypted value:

   connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115d

4. Wrap the encrypted value with the identifier "ENC()":

   connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/broker.xml configuration file.

3. Add the name-value pair saslMechanisms=GSSAPI to the query string of the URL for the acceptor.

   <acceptor name="amqp">
     tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI
   </acceptor>

   The preceding configuration means that the acceptor uses the GSSAPI mechanism when authenticating Kerberos credentials.

4. (Optional) The PLAIN and ANONYMOUS SASL mechanisms are also supported. To specify multiple mechanisms, use a comma-separated list. For example:

   <acceptor name="amqp">
     tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN
   </acceptor>

   The result is an acceptor that uses both the GSSAPI and PLAIN SASL mechanisms.

5. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/login.config configuration file.

3. Add a configuration scope named amqp-sasl-gssapi. The following example shows configuration for the Krb5LoginModule found in Oracle and OpenJDK versions of the JDK.

   amqp-sasl-gssapi {
       com.sun.security.auth.module.Krb5LoginModule required
       isInitiator=false
       storeKey=true
       useKeyTab=true
       principal="amqp/my_broker_host@example.com"
       debug=true;
   };

   amqp-sasl-gssapi

   By default, the GSSAPI mechanism implementation on the broker uses a JAAS configuration scope named amqp-sasl-gssapi to obtain its Kerberos acceptor credentials.

   Krb5LoginModule

   This version of the Krb5LoginModule is provided by the Oracle and OpenJDK versions of the JDK. Verify the fully qualified class name of the Krb5LoginModule and its available options by referring to the documentation from your Java vendor.

   useKeyTab

   The Krb5LoginModule is configured to use a Kerberos keytab when authenticating a principal. Keytabs are generated using tooling from your Kerberos environment. See the documentation from your vendor for details about generating Kerberos keytabs.

   principal

   The Principal is set to amqp/my_broker_host@example.com. This value must correspond to the service principal created in your Kerberos environment. See the documentation from your vendor for details about creating service principals.

4. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/login.config configuration file.

3. Add configuration for the AMQ Broker Krb5LoginModule and the LDAPLoginModule. Verify the configuration options by referring to the documentation from your LDAP provider.

   An example configuration is shown below.

   org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
       ;
   org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
       initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
       connectionURL="ldap://localhost:1024"
       authentication=GSSAPI
       saslLoginConfigScope=broker-sasl-gssapi
       connectionProtocol=s
       userBase="ou=users,dc=example,dc=com"
       userSearchMatching="(krb5PrincipalName={0})"
       userSearchSubtree=true
       authenticateUser=false
       roleBase="ou=system"
       roleName=cn
       roleSearchMatching="(member={0})"
       roleSearchSubtree=false
       ;

   Note

   The version of the Krb5LoginModule shown in the preceding example is distributed with AMQ Broker and transforms the Kerberos identity into a broker identity that can be used by other AMQ modules for role mapping.

4. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Open the <broker_instance_dir>/etc/boostrap.xml configuration file.

2. In the security-manager element, for the class-name attribute, specify the class that is a user-defined implementation of the org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager5 interface. For example:

   <broker xmlns="http://activemq.org/schema">
      ...
      <security-manager class-name="com.myclass.MySecurityManager">
         <property key="myKey1" value="myValue1"/>
         <property key="myKey2" value="myValue2"/>
      </security-manager>
      ...
   </broker>

Procedure

1. Navigate to the directory that contains the custom security manager example. The following example assumed that you downloaded the example to a directory called amq-broker-examples.

   $ cd amq-broker-examples/examples/features/standard/security-manager

2. Run the example.

   $ mvn verify

Procedure

1. From a command prompt, use the mask utility to encrypt a password:

   $ <broker_instance_dir>/bin/artemis mask <password>

   result: 3a34fd21b82bf2a822fa49a8d8fa115d

2. Open the <broker_instance_dir>/etc/broker.xml configuration file containing the plain-text password that you want to mask:

   <cluster-password>
     <password>
   </cluster-password>

3. Replace the plain-text password with the encrypted value:

   <cluster-password>
     3a34fd21b82bf2a822fa49a8d8fa115d
   </cluster-password>

4. Wrap the encrypted value with the identifier ENC():

   <cluster-password>
     ENC(3a34fd21b82bf2a822fa49a8d8fa115d)
   </cluster-password>

Procedure

1. Use the mask utility to encrypt each password in a configuration file. For the key parameter, specify a string of characters with which to encrypt the password. Use the same key string to encrypt each password.

   $ <broker_instance_dir>/bin/artemis mask --key <key> <password>

   Warning

   Ensure that you keep a record of the key string that you specify when you run the mask utility to encrypt passwords. You must configure the same key value in an environment variable to allow the broker to decrypt passwords.

   For more information about encrypting passwords in configuration files, see Section 5.9.2, “Encrypting a password in a configuration file”.

2. From a command prompt, set the ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY environment variable to the key string that you specified when you encrypted each password.

   $ export ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY= <key>

3. Start the broker.

   $ ./artemis run

4. Unset the ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY environment variable.

   $ unset ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY

   Note

   If you unset the ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY environment variable after you start the broker, you must set it again to the same key string before you start the broker each subsequent time.