이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 6. Security
This chapter covers the various security options available to administrators, and how they are configured. Administrators can use the information provided in this chapter to tailor the functions of the AMQ Broker security subsystems to their needs.
6.1. Accessing the AMQ Management Console
Starting with AMQ Broker 7.1.0, you can access the AMQ Management Console only from the local host by default. You must modify the configuration in BROKER_INSTANCE_DIR/etc/jolokia-access.xml
to enable remote access. For more information, see Securing AMQ Management Console and AMQ Broker Connections.
6.2. Securing Network Connections
There are two basic use cases for transport layer security (TLS):
- Server-side (or one-way); where only the server presents a certificate. This is the most common use case.
- Client-side (or two-way); where both the server and the client present certificates. This is sometimes called mutual authentication.
6.2.1. Configuring Server-Side Certificates
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.
6.2.2. Configuring Client-Side Certificates
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>
Client-side Considerations
AMQ Broker supports multiple protocols, and each protocol and platform has different ways to specify TLS parameters. However, in the case of a client using the Core protocol (a bridge) the TLS parameters are configured on the connector URL much like on the broker’s acceptor.
TLS Configuration Details
Below are configuration details to be aware of:
Option | Note |
---|---|
|
Must be |
|
When used on an
When used on a |
|
When used on an
When used on a |
|
When used on an
When used on a |
|
When used on an
When used on a |
|
Whether used on an |
|
Whether used on an |
|
This property is only for an |
6.2.3. Adding Certificate-based Authentication
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:
- To further constrain the set of acceptable users, because only the user Distinguished Names (DNs) explicitly listed in the relevant properties file are eligible to be authenticated.
- To associate a list of groups with the received user identity, facilitating integration with authorization.
- To require the presence of an incoming certificate (by default, the TLS layer is configured to treat the presence of a client certificate as optional).
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.
Prerequisites
-
Certificate login configured in
login.config
file. -
A valid
artemis-users.properties
file. -
A valid
artemis-roles.properties
file. - The Subject DNs from the user certificate(s)
Procedure
Obtain the Subject DNs from user certificates
Export the certificate from the KeyStore file into a temporary file. Substitute your required values into the following command:
keytool -export -file __FILENAME__ -alias broker-localhost -keystore broker.ks -storepass __PASSWORD__
Print the contents of the exported certificate:
keytool -printcert -file __FILENAME__
The output is similar to that shown below:
Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown 1 Issuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Serial number: 4537c82e Valid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007 Certificate fingerprints: MD5: 3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37 SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C
- 1
- The subject DN. The format used to enter the subject DN depends on your platform. The string above could also be represented as;
Owner: `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`
Configuring certificate-based authentication
-
Open the
login.config
file and reference the user and roles properties files. Open the files declared in the previous step and supply the required information:
Users and their corresponding DNs should be listed in the
artemis-users.properties
file. The available roles and the users who hold those roles are defined in theartemis-roles.properties
file.Examples of the syntax of these files is shown below.
Ensure your security domain alias (in this instance, activemq) is referenced in
bootstrap.xml
as shown below:<jaas-security domain="activemq"/>
-
Open the
Example Configuration
The following example shows how to configure certificate login module in the login.config
file:
Example 6.1. login.config
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 };
- 1
- Configure the JAAS realm. This example uses a single
org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
- 2
- Toggle debugging on (
true
) or off (false
). Default isfalse
. - 3
- Define the file used to store user data (relative to the directory containing the
login.config
file). - 4
- Define the file used to store role data (relative to the directory containing the
login.config
file).
The artemis-users.properties
file consists of a list of properties with the user=StringifiedSubjectDN
(where the string encoding is specified by RFC 2253):
Example 6.2. artemis-users.properties
system=CN=system,O=Progress,C=US 1
user=CN=humble user,O=Progress,C=US
guest=CN=anon,O=Progress,C=DE
- 1
- The user named
system
is mapped to theCN=system,O=Progress,C=US
subject DN.
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:
Example 6.3. artemis-roles.properties
admins=system
users=system,user 1
guests=guest
- 1
- Multiple users can be included as a comma-separated entry.
6.2.4. Adding Certificate-based Authentication for AMQP Clients
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:
- The broker reads the TLS/SSL certificate of the client to obtain an identity from the certificate’s subject.
- The certificate subject is mapped to a broker identity by the certificate login module. The broker then authorizes the mapped user based on their roles.
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.
Open the resource containing the URI for editing:
amqps://localhost:5500
Add the parameter
sslEnabled=true
to enable TSL/SSL for the connection:amqps://localhost:5500?sslEnabled=true
Add parameters related to the TrustStore and KeyStore of the client to enable the exchange of TSL/SSL certificates with the broker:
amqps://localhost:5500?sslEnabled=true&trustStorePath=TRUST_STORE_PATH&trustStorePassword=TRUST_STORE_PASSWORD&keyStorePath=KEY_STORE_PATH&keyStorePassword=KEY_STORE_PASSWORD
Add the parameter
saslMechanisms=EXTERNAL
to request that the broker authenticate the client by using the identity found in its TSL/SSL certificate:amqps://localhost:5500?sslEnabled=true&trustStorePath=TRUST_STORE_PATH&trustStorePassword=TRUST_STORE_PASSWORD&keyStorePath=KEY_STORE_PATH&keyStorePassword=KEY_STORE_PASSWORD&saslMechanisms=EXTERNAL
Additional Resources
- For more information about certificate-based authentication in AMQ Broker, see Section 6.2.3, “Adding Certificate-based Authentication”.
- For more information about configuring your AMQP client, go to the Red Hat Customer Portal for product documentation specific to your client.
6.2.5. Using Multiple Login Modules
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.
Prerequisites
The prerequisites for different authentication combinations differ based on the methods being implemented. Prerequisites for the most common multiple login scenario are:
-
A valid
artemis-users.properties
file -
A valid
artemis-roles.properties
file -
A
login.config
file configured for anonymous access
Procedure
-
Edit the
login.config
file to add entries for the desired authentication modules. - Set the parameters in each module entry as required for your environment.
Ensure your security domain alias (in this instance, activemq) is referenced in
bootstrap.xml
as shown below:Example 6.4.
bootstrap.xml
<jaas-security domain="activemq"/>
Example Configuration
The following examples illustrate the cascading nature of multiple login configurations:
Example 6.5. login.config
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
.
Example 6.6. login.config
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"; };
6.2.6. Configure Multiple Security Settings for Address Groups and Sub-groups
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>
- 1
- The ‘#’ character signifies "any sequence of words". Words are delimited by the ‘.’ character. For a full description of the wildcard syntax, see AMQ Broker Wildcard Syntax. The above security block applies to any address that starts with the string globalqueues.europe.
- 2 3
- Only users who have the
admin
role can create or delete durable queues bound to an address that starts with the string globalqueues.europe. - 4 5
- Any users with the roles
admin
,guest
, oreurope-users
can create or delete temporary queues bound to an address that starts with the string globalqueues.europe. - 6 7
- Any users with the roles
admin
oreurope-users
can send messages to these addresses or consume messages from queues bound to an address that starts with the string globalqueues.europe.
The mapping between users and what roles they have is handled by a component called the security manager. The security manager reads user credentials from a properties file stored on the broker. By default, AMQ Broker uses the org.apache.activemq.artemis.spi.core.security.ActiveMQJAASSecurityManager
security manager. This default security manager provides integration with JAAS and Red Hat JBoss Enterprise Application Platform (JBoss EAP) 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.
6.2.7. Setting Resource Limits
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.
6.2.7.1. Configuring Connection and Queue Limits
Here is an example of the XML used to set resource limits:
<resource-limit-settings> <resource-limit-setting match="myUser"> <max-connections>5</max-connections> <max-queues>3</max-queues> </resource-limit-setting> </resource-limit-settings>
Unlike the match
from address-setting
, this match
does not use any wildcard syntax. It is a simple 1:1 mapping of the limits to a user.
-
max-connections
. Defines how many connections the matched user can make to the broker. The default is-1
, which means there is no limit. -
max-queues
. Defines how many queues the matched user can create. The default is-1
, which means there is no limit.
6.3. Integrating with LDAP
6.3.1. Using LDAP for Authentication
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
.
Procedure
Open the
BROKER_INSTANCE_DIR/etc/broker.xml
file and add the following lines:<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>
-
Open the
BROKER_INSTANCE_DIR/etc/login.config
file. - Locate and edit the appropriate alias block with the appropriate parameters (see the examples included below).
- Start or restart the broker (service or process).
Apache DS uses the OID
portion of DN path; however, Microsoft AD does not, and instead uses the CN
portion.
For example; The DN path oid=testuser,dc=example,dc=com
would be used in Apache DS, while cn=testuser,dc=example,dc=com
would be used in Microsoft AD.
Example 6.7. Example Apache DS login.config
configuration
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 connectionTimeout=5000 7 authentication=simple 8 userBase="dc=example,dc=com" 9 userSearchMatching="(uid={0})" 10 userSearchSubtree=true 11 userRoleName= 12 readTimeout=5000 13 roleBase="dc=example,dc=com" 14 roleName=cn 15 roleSearchMatching="(member={0})" 16 roleSearchSubtree=true 17 ; };
Example 6.8. Example Microsoft Active Directory login.config
Configuration
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 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 ; };
- 1
- Toggle debugging on (
true
) or off (false
). Default isfalse
. - 2
- The
initialContextFactory
parameter must always be set tocom.sun.jndi.ldap.LdapCtxFactory
- 3
- Specify the 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 is10389
while for Microsoft AD the default is389
. - 4
- 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. - 5
- The password that matches the DN from
connectionUsername
. In the directory server, in the DIT, the password is normally stored as auserPassword
attribute in the corresponding directory entry. - 6
- Any value is supported but is effectively unused. This option must be set explicitly because it has no default value.
- 7
- 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.
- 8
- Specify the authentication method used when binding to the LDAP server. This parameter can be set to either
simple
(which requires a username and password) ornone
(which allows anonymous access). - 9
- 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 theou=User,ou=ActiveMQ,ou=system
node. - 10
- Specify an LDAP search filter, which is applied to the subtree selected by
userBase
. See the Search Matching section below for more information. - 11
- Specify the search depth for user entries, relative to the node specified by
userBase
. This option is a boolean. A setting offalse
indicates it tries to match one of the child entries of theuserBase
node (maps tojavax.naming.directory.SearchControls.ONELEVEL_SCOPE
), whiletrue
indicates it tries to match any entry belonging to the subtree of theuserBase
node (maps tojavax.naming.directory.SearchControls.SUBTREE_SCOPE
). - 12
- Specify the name of the multi-valued attribute of the user entry that contains a list of role names for the user (where the 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.
- 13
- 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.
- 14
- If role data is stored directly in the directory server, one can use a combination of role options (
roleBase
,roleSearchMatching
,roleSearchSubtree
, androleName
) as an alternative to (or in addition to) specifying theuserRoleName
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 toou=Group,ou=ActiveMQ,ou=system
, the search for role/group entries is restricted to the subtree beneath theou=Group,ou=ActiveMQ,ou=system
node. - 15
- Specify the 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.
- 16
- Specify an LDAP search filter, which is applied to the subtree selected by
roleBase
. See the Search Matching section below for more information. - 17
- Specify the search depth for role entries, relative to the node specified by
roleBase
. If set tofalse
(which is the default) the search tries to match one of the child entries of theroleBase
node (maps tojavax.naming.directory.SearchControls.ONELEVEL_SCOPE
). Iftrue
it tries to match any entry belonging to the subtree of the roleBase node (maps tojavax.naming.directory.SearchControls.SUBTREE_SCOPE
).
Search Matching
- userSearchMatching
Before passing to the LDAP search operation, the string value provided in this configuration parameter is subjected to string substitution, as implemented by the
java.text.MessageFormat
class.
This means that the special string,
{0}
, is substituted by the username, as extracted from the incoming client credentials. After substitution, the string is interpreted as an LDAP search filter (the syntax is defined by the IETF standard RFC 2254).
For example, if this option is set to
(uid={0})
and the received username isjdoe
, the search filter becomes(uid=jdoe)
after string substitution.
If the resulting search filter is applied to the subtree selected by the user base,
ou=User,ou=ActiveMQ,ou=system
, it would match the entry,uid=jdoe,ou=User,ou=ActiveMQ,ou=system
.
A short introduction to the search filter syntax is available from Oracle’s JNDI tutorial
- roleSearchMatching
This works in a similar manner to the
userSearchMatching
option, except that it supports two substitution strings.
The substitution string
{0}
substitutes the full DN of the matched user entry (that is, the result of the user search). For example, for the user,jdoe
, the substituted string could beuid=jdoe,ou=User,ou=ActiveMQ,ou=system
.
The substitution string
{1}
substitutes the received username. For example,jdoe
.
If this option is set to
(member=uid={1})
and the received username isjdoe
, the search filter becomes(member=uid=jdoe)
after string substitution (assuming ApacheDS search filter syntax).
If the resulting search filter is applied to the subtree selected by the role base,
ou=Group,ou=ActiveMQ,ou=system
, it matches all role entries that have amember
attribute equal touid=jdoe
(the value of amember
attribute is a DN).
This option must always be set, even if role searching is disabled, because it has no default value. If OpenLDAP is used, the syntax of the search filter is
(member:=uid=jdoe)
.
6.3.2. Configure LDAP Authorization
The LegacyLDAPSecuritySettingPlugin
security settings plugin reads the security information previously handled in AMQ 6 by LDAPAuthorizationMap
and cachedLDAPAuthorizationMap
and converts this information to corresponding AMQ 7 security settings, where possible.
The security implementations for brokers in AMQ 6 and AMQ 7 do not match exactly. Therefore, the plugin performs some translation between the two versions to achieve near-equivalent functionality.
Shown below is an example of the plugin configuration:
<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>
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 isldap://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 DIT, the password is normally stored as auserPassword
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) ornone
(anonymous). The default value issimple
.NoteSimple Authentication and Security Layer (SASL) authentication is not supported.
Other settings not shown in the preceding configuration example are:
destinationBase
-
Specifies the DN of the node whose children provide the permissions for all destinations. In this case, the DN is a literal value (that is, no string substitution is performed on the property value). For example, a typical value of this property is
ou=destinations,o=ActiveMQ,ou=system
The default value isou=destinations,o=ActiveMQ,ou=system
. filter
-
Specifies an LDAP search filter, which is used when looking up the permissions for any kind of destination. The search filter attempts to match one of the children or descendants of the queue or topic node. The default value is
(cn=*)
. roleAttribute
-
Specifies an attribute of the node matched by
filter
whose value is the DN of a role. The default value isuniqueMember
. adminPermissionValue
-
Specifies a value that matches the
admin
permission. The default value isadmin
. readPermissionValue
-
Specifies a value that matches the
read
permission. The default value isread
. writePermissionValue
-
Specifies a value that matches the
write
permission. The default value iswrite
. enableListener
-
Specifies whether to enable a listener that automatically receives updates made in the LDAP server and update the broker’s authorization configuration in real time. The default value is
true
. mapAdminToManage
-
Specifies whether to map the legacy (that is, AMQ 6)
admin
permission to the AMQ 7manage
permission. See details of the mapping semantics in the table below. The default value isfalse
.
The name of the queue or topic defined in LDAP serves as the "match" for the security setting, the permission value is mapped from the AMQ 6 type to the AMQ 7 type, and the role is mapped as-is. Because the name of the queue or topic defined in LDAP serves as the match for the security setting, the security setting may not be applied as expected to JMS destinations. This is because AMQ 7 always prefixes JMS destinations with "jms.queue." or "jms.topic.", as necessary.
AMQ 6 has three permission types - read
, write
, and admin
. These permission types are described on the ActiveMQ website; http://activemq.apache.org/security.html.
AMQ 7 has the following permission types:
-
createAddress
-
deleteAddress
-
createDurableQueue
-
deleteDurableQueue
-
createNonDurableQueue
-
deleteNonDurableQueue
-
send
-
consume
-
manage
-
browse
This table shows how the security settings plugin maps AMQ 6 permission types to AMQ 7 permission types:
AMQ 6 permission type | AMQ 7 permission type |
---|---|
read | consume, browse |
write | send |
admin |
createAddress, deleteAddress, createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue, manage (if |
As described below, there are some cases in which the plugin performs some translation between the AMQ 6 and AMQ 7 permission types to achieve equivalence:
-
The mapping does not include the AMQ 7
manage
permission type by default because there is no analogous permission type in AMQ 6. However, ifmapAdminToManage
is set totrue
, the plugin maps the AMQ 6admin
permission to the AMQ 7manage
permission. -
The
admin
permission type in AMQ 6 determines whether the broker automatically creates a destination if the destination does not exist and the user sends a message to it. AMQ 7 automatically allows automatic creation of a destination if the user has permission to send messages to the destination. Therefore, the plugin maps the legacyadmin
permission to the AMQ 7 permissions shown above, by default. The plugin also maps the AMQ 6admin
permission to the AMQ 7manage
permission ifmapAdminToManage
is set totrue
.
6.3.3. Encrypting the Password in the login.config File
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.
Prerequisites
-
Ensure that you have modified the
login-config
file to add the required properties as described in Section 6.3.2, “Configure LDAP Authorization”.
Procedure
The following procedure explains how to mask the value of the connectionPassword
found in the BROKER_INSTANCE_DIR/etc/login.config
file.
From a command prompt, use the
mask
utility to encrypt the password:$ BROKER_INSTANCE_DIR/bin/artemis mask PASSWORD
The encrypted password is displayed on the screen:
result: 3a34fd21b82bf2a822fa49a8d8fa115d
Open the
BROKER_INSTANCE_DIR/etc/login.config
file and locate theconnectionPassword
:connectionPassword = PASSWORD
Replace the plain text password with the encrypted value that you created in Step 1:
connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115d
Wrap the encrypted value with the identifier
"ENC()"
:connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"
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.
Additional Resources
For more information about the configuration files included with AMQ Broker, see AMQ Broker configuration files and locations.
6.4. Integrating with Kerberos
When sending and receiving messages with the AMQP protocol, clients can send Kerberos security credentials that AMQ Broker authenticates by using the GSSAPI mechanism from the Simple Authentication and Security Layer (SASL) framework. Kerberos credentials can also be used for authorization by mapping an authenticated user to an assigned role configured in an LDAP directory or text-based properties file.
You can use SASL in tandem with Transport Layer Sockets (TLS) to secure your messaging applications. SASL provides user authentication, and TLS provides data integrity.
You must deploy and configure a Kerberos infrastructure before AMQ Broker can authenticate and authorize Kerberos credentials. See your operating system documentation for more information about deploying Kerberos. If your operating system is RHEL 7, for example, see the chapter Using Kerberos. A Kerberos Authentication Overview is available for Windows as well.
You must deploy and configure a Kerberos infrastructure before AMQ Broker can authenticate and authorize Kerberos credentials.
Users of an Oracle or IBM JDK should install the Java Cryptography Extension (JCE). See the documentation from the Oracle version of the JCE or the IBM version of the JCE for more information.
6.4.1. Enabling Network Connections to Use Kerberos
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
Stop the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis stop
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
-
Open the
broker.xml
configuration file located underBROKER_INSTANCE_DIR/etc
Add the name-value pair
saslMechanisms=GSSAPI
to the query string of the URL for theacceptor
, as shown in the following example:<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI </acceptor>
The result is an acceptor that uses the GSSAPI mechanism when authenticating Kerberos credentials.
(Optional) The
PLAIN
andANONYMOUS
SASL mechanisms are also supported. If you want to use these other mechanisms in addition toGSSAPI
, add them to the list ofsaslMechanisms
. Be sure to separate each value with a comma. In the following example, the name-value pairsaslMechanisms=GSSAPI
is modified to add the valuePLAIN
.<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
andPLAIN
SASL mechanisms.Start the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis run
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe start
Related Information
See About Acceptors for more information about acceptors.
6.4.2. Authenticating Clients with Kerberos Credentials
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
Stop the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis stop
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
-
Open the
login.config
configuration file located underBROKER_INSTANCE_DIR/etc
. Add a configuration scope named
amqp-sasl-gssapi
tologin.config
. The following example shows configuration for theKrb5LoginModule
found in Oracle and OpenJDK versions of the JDK.NoteVerify the fully qualified class name of the
Krb5LoginModule
and its available options by referring to the documentation from your Java vendor.amqp-sasl-gssapi { 1 com.sun.security.auth.module.Krb5LoginModule required 2 isInitiator=false storeKey=true useKeyTab=true 3 principal="amqp/my_broker_host@example.com" 4 debug=true; };
- 1
- By default, the GSSAPI mechanism implementation on the broker uses a JAAS configuration scope named
amqp-sasl-gssapi
to obtain its Kerberos acceptor credentials. - 2
- This version of the
Krb5LoginModule
is provided by the Oracle and OpenJDK versions of the JDK. Verify the fully qualified class name of theKrb5LoginModule
and its available options by referring to the documentation from your Java vendor. - 3
- 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. - 4
- 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.
Start the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis run
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe start
Related Information
See Network Connections and Kerberos, for more information about enabling the GSSAPI mechanism in AMQ Broker.
6.4.2.1. Using an Alternative Configuration Scope
You can specify an alternative configuration scope by adding the parameter saslLoginConfigScope
to the URL of an AMQP acceptor. In the following configuration example, the parameter saslLoginConfigScope
is given the value alternative-sasl-gssapi
. The result is an acceptor that uses the alternative scope named alternative-sasl-gssapi
, which was declared in the BROKER_INSTANCE_DIR/etc/login.config
configuration file.
<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN;saslLoginConfigScope=alternative-sasl-gssapi` </acceptor>
6.4.3. Authorizing Clients with Kerberos Credentials
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.
The Kerberos Peer Principal does not exist as a broker user, only as a role member.
Prerequisites
You must enable the GSSAPI mechanism of an acceptor before it can authorize AMQP connections using Kerberos security credentials.
Procedure
Stop the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis stop
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
-
Open the
login.config
configuration file located underBROKER_INSTANCE_DIR/etc
. Add configuration for the AMQ Broker
Krb5LoginModule
and theLDAPLoginModule
.NoteVerify the configuration options by referring to the documentation from your LDAP provider.
org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required ; 1 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 ;
- 1
- This version of the
Krb5LoginModule
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.
Start the broker.
If the broker is running on Linux:
BROKER_INSTANCE_DIR/bin/artemis run
If the broker is running on Windows as a service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe start
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
.
6.5. Encrypting Passwords in Configuration Files
By default, AMQ Broker stores all passwords in configuration files as plain text. Be sure to secure all configuration files with the correct permissions to prevent unauthorized access. You can also encrypt, or mask, the plain text passwords to prevent unwanted viewers from reading them.
A masked password is the encrypted version of a plain text password. The encrypted version is generated by the mask
command-line utility provided by AMQ Broker. For more information about the mask
utility, see the command-line help documentation:
$ BROKER_INSTANCE_DIR/bin/artemis help mask
To mask a password, replace its plain text value with the encrypted one. The masked password must be wrapped by the identifier ENC()
so that it is decrypted when the actual value is needed.
In the following example, the configuration file BROKER_INSTANCE_DIR/etc/bootstrap.xml
contains masked passwords for the attributes keyStorePassword
and trustStorePassword
.
Example with bootstrap.xml
<web bind="https://localhost:8443" path="web" keyStorePassword="ENC(-342e71445830a32f95220e791dd51e82)" trustStorePassword="ENC(32f94e9a68c45d89d962ee7dc68cb9d1)"> <app url="activemq-branding" war="activemq-branding.war"/> </web>
You can use masked passwords only with the following configuration files.
Supported Configuration Files
- broker.xml
- bootstrap.xml
- management.xml
- artemis-users.properties
-
login.config (for use with the
LDAPLoginModule
)
Configuration files are found at BROKER_INSTANCE_DIR/etc
.
artemis-users.properties
supports only masked passwords that have been hashed. When a user is created upon broker creation, artemis-users.properties
contains hashed passwords by default. The default PropertiesLoginModule
will not decode the passwords in artemis-users.properties
file but will instead hash the input and compare the two hashed values for password verification. Changing the hashed password to a masked password does not allow access to the AMQ Console.
broker.xml
, bootstrap.xml
, management.xml
, and login.config
support passwords that are masked but not hashed.
Procedure
As an example, the following procedure explains how to mask the value of the cluster-password
configuration element found in the file BROKER_INSTANCE_DIR/etc/broker.xml
.
From a command prompt, use the
mask
utility to encrypt a password:$ BROKER_INSTANCE_DIR/bin/artemis mask PASSWORD
The encrypted password is displayed on the screen:
result: 3a34fd21b82bf2a822fa49a8d8fa115d
Open the configuration file containing the plain text password you want to mask:
<cluster-password> PASSWORD </cluster-password>
Replace the plain text password with the encrypted value that you created in Step 1:
<cluster-password> 3a34fd21b82bf2a822fa49a8d8fa115d </cluster-password>
Wrap the encrypted value with the identifier
ENC()
:<cluster-password> ENC(3a34fd21b82bf2a822fa49a8d8fa115d) </cluster-password>
The configuration file now contains a masked password. Because the password is wrapped with the ENC()
identifier, AMQ Broker decrypts it before it is used.
Additional Resources
For more information about the configuration files included with AMQ Broker, see AMQ Broker configuration files and locations.
6.6. Tracking Messages from Validated Users
To enable tracking and logging the origins of messages (for example, for security-auditing purposes), you can use the _AMQ_VALIDATED_USER
message key.
In the broker.xml
configuration file, if the populate-validated-user
option is set to true
, then the broker adds the name of the validated user to the message using the _AMQ_VALIDATED_USER
key. For JMS and STOMP clients, this message key maps to the JMSXUserID
key.
The broker cannot add the validated user name to a message produced by an AMQP JMS client. Modifying the properties of an AMQP message after it has been sent by a client is a violation of the AMQP protocol.
For a user authenticated based on his/her SSL certificate, the validated user name populated by the broker is the name to which the certificate’s Distinguished Name (DN) maps.
In the broker.xml
configuration file, if security-enabled
is false
and populate-validated-user
is true
, then the broker populates whatever user name, if any, that the client provides. The populate-validated-user
option is false
by default.
You can configure the broker to reject a message that doesn’t have a user name (that is, the JMSXUserID
key) already populated by the client when it sends the message. You might find this option useful for AMQP clients, because the broker cannot populate the validated user name itself for messages sent by these clients.
To configure the broker to reject messages without JMSXUserID
set by the client, add the following configuration to the broker.xml
configuration file:
<reject-empty-validated-user>true</reject-empty-validated-user>
By default, reject-empty-validated-user
is set to false
.
6.7. Disabling Security
Security is enabled by default. Broker security can be enabled or disabled by setting the <security-enabled>
parameter in the <core>
element of the broker.xml
configuration file.
Procedure
-
Open the
broker.xml
file. -
Locate the
<security-enabled>
parameter. Edit the entry as needed:
Set the parameter to
false
to disable security:<security-enabled>false</security-enabled>
-
If necessary, change the
security-invalidation-interval
entry (which periodically invalidates secure logins) to a different value (in ms). The default is10000
.
6.8. Using a Custom Security Manager
The broker uses a component called the security manager to handle authentication and authorization. By default, AMQ Broker uses the org.apache.activemq.artemis.spi.core.security.ActiveMQJAASSecurityManager
security manager. This default security manager provides integration with JAAS and Red Hat JBoss Enterprise Application Platform (JBoss EAP) security.
However, a system administrator might want more control over the implementation of broker security. In this case, it is possible to specify a custom security manager in the broker configuration. A custom security manager is a user-defined class that implements the org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager3
interface.
6.8.1. Specifying a Custom Security Manager
The following procedure shows how to specify a custom security manager in your broker configuration.
Procedure
-
Open the
<broker-instance-dir>/etc/boostrap.xml
configuration file. In the
security-manager
element, for theclass-name
attribute, specify the class that is a user-defined implementation of theorg.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager3
interface. For example:<broker xmlns="http://activemq.org/schema"> <security-manager class-name="com.foo.MySecurityManager"> <property key="myKey1" value="myValue1"/> <property key="myKey2" value="myValue2"/> </security-manager> ... </broker>
Additional Resources
-
For more information about the
org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager3
interface, see Interface ActiveMQSecurityManager3 in the ActiveMQ Artemis Core JMS API documentation.
6.8.2. Running the Custom Security Manager Example Program
AMQ Broker includes an example program that demonstrates how to implement a custom security manager. In the example, the custom security manager logs details for authentication and authorization and then passes the details to an instance of org.apache.activemq.artemis.spi.core.security.ActiveMQJAASSecurityManager
(that is, the default security manager).
The following procedure shows you how to run the custom security manager example program.
Prerequisites
- Your machine must be set up to run AMQ Broker example programs. For more information, see Running the AMQ Broker examples.
Procedure
Navigate to the directory to the directory that contains the custom security manager example.
$ cd <install-dir>/examples/features/standard/security-manager
Run the example.
$ mvn verify
NoteIf you would prefer to manually create and start a broker instance when running the example program, replace the command in the preceding step with
mvn -PnoServer verify
.