289 lines
18 KiB
XML
289 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<chapter id="security">
|
||
<title>Security</title>
|
||
<para>This chapter describes how security works with ActiveMQ and how you can configure it. To
|
||
disable security completely simply set the <literal>security-enabled</literal> property to
|
||
false in the <literal>activemq-configuration.xml</literal> file.</para>
|
||
<para>For performance reasons security is cached and invalidated every so long. To change this
|
||
period set the property <literal>security-invalidation-interval</literal>, which is in
|
||
milliseconds. The default is <literal>10000</literal> ms.</para>
|
||
<section id="security.settings.roles">
|
||
<title>Role based security for addresses</title>
|
||
<para>ActiveMQ contains a flexible role-based security model for applying security to queues,
|
||
based on their addresses.</para>
|
||
<para>As explained in <xref linkend="using-core"/>, ActiveMQ core consists mainly of sets of
|
||
queues bound to addresses. A message is sent to an address and the server looks up the
|
||
set of queues that are bound to that address, the server then routes the message to
|
||
those set of queues.</para>
|
||
<para>ActiveMQ allows sets of permissions to be defined against the queues based on their
|
||
address. An exact match on the address can be used or a wildcard match can be used using
|
||
the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
|
||
<para>Seven different permissions can be given to the set of queues which match the address.
|
||
Those permissions are:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>createDurableQueue</literal>. This permission allows the user to
|
||
create a durable queue under matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>deleteDurableQueue</literal>. This permission allows the user to
|
||
delete a durable queue under matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>createNonDurableQueue</literal>. This permission allows the user to create
|
||
a non-durable queue under matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>deleteNonDurableQueue</literal>. This permission allows the user to delete
|
||
a non-durable queue under matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>send</literal>. This permission allows the user to send a message to
|
||
matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>consume</literal>. This permission allows the user to consume a
|
||
message from a queue bound to matching addresses.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>manage</literal>. This permission allows the user to invoke
|
||
management operations by sending management messages to the management
|
||
address.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>For each permission, a list of roles who are granted that permission is specified. If
|
||
the user has any of those roles, he/she will be granted that permission for that set of
|
||
addresses.</para>
|
||
<para>Let's take a simple example, here's a security block from <literal
|
||
>activemq-configuration.xml</literal> or <literal>activemq-queues.xml</literal>
|
||
file:</para>
|
||
<programlisting>
|
||
<security-setting match="globalqueues.europe.#">
|
||
<permission type="createDurableQueue" roles="admin"/>
|
||
<permission type="deleteDurableQueue" roles="admin"/>
|
||
<permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
|
||
<permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
|
||
<permission type="send" roles="admin, europe-users"/>
|
||
<permission type="consume" roles="admin, europe-users"/>
|
||
</security-setting></programlisting>
|
||
<para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
|
||
delimited by the '<literal>.</literal>' character. For a full description of the
|
||
wildcard syntax please see <xref linkend="wildcard-syntax"/>. The above security block
|
||
applies to any address that starts with the string "globalqueues.europe.":</para>
|
||
<para>Only users who have the <literal>admin</literal> role can create or delete durable
|
||
queues bound to an address that starts with the string "globalqueues.europe."</para>
|
||
<para>Any users with the roles <literal>admin</literal>, <literal>guest</literal>, or
|
||
<literal>europe-users</literal> can create or delete temporary queues bound to an
|
||
address that starts with the string "globalqueues.europe."</para>
|
||
<para>Any users with the roles <literal>admin</literal> or <literal>europe-users</literal>
|
||
can send messages to these addresses or consume messages from queues bound to an address
|
||
that starts with the string "globalqueues.europe."</para>
|
||
<para>The mapping between a user and what roles they have is handled by the security
|
||
manager. ActiveMQ 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.</para>
|
||
<para>For more information on configuring the security manager, please see <xref
|
||
linkend="change-security-manager"/>.</para>
|
||
<para>There can be zero or more <literal>security-setting</literal> elements in each xml
|
||
file. Where more than one match applies to a set of addresses the <emphasis>more
|
||
specific</emphasis> match takes precedence.</para>
|
||
<para>Let's look at an example of that, here's another <literal>security-setting</literal>
|
||
block:</para>
|
||
<programlisting>
|
||
<security-setting match="globalqueues.europe.orders.#">
|
||
<permission type="send" roles="europe-users"/>
|
||
<permission type="consume" roles="europe-users"/>
|
||
</security-setting></programlisting>
|
||
<para>In this <literal>security-setting</literal> 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 <emphasis>only</emphasis> from the latter
|
||
security-setting block.</para>
|
||
<para>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 <literal
|
||
>send</literal> and <literal>consume</literal> for the role europe-users. The
|
||
permissions <literal>createDurableQueue</literal>, <literal
|
||
>deleteDurableQueue</literal>, <literal>createNonDurableQueue</literal>, <literal
|
||
>deleteNonDurableQueue</literal> are not inherited from the other security-setting
|
||
block.</para>
|
||
<para>By not inheriting permissions, it allows you to 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.</para>
|
||
</section>
|
||
<section>
|
||
<title>Secure Sockets Layer (SSL) Transport</title>
|
||
<para>When messaging clients are connected to servers, or servers are connected to other
|
||
servers (e.g. via bridges) over an untrusted network then ActiveMQ allows that traffic to
|
||
be encrypted using the Secure Sockets Layer (SSL) transport.</para>
|
||
<para>For more information on configuring the SSL transport, please see <xref
|
||
linkend="configuring-transports"/>.</para>
|
||
</section>
|
||
<section>
|
||
<title>Basic user credentials</title>
|
||
<para>ActiveMQ ships with a security manager implementation that reads user credentials, i.e.
|
||
user names, passwords and role information from an xml file on the classpath called
|
||
<literal>activemq-users.xml</literal>. This is the default security manager.</para>
|
||
<para>If you wish to use this security manager, then users, passwords and roles can easily
|
||
be added into this file.</para>
|
||
<para>Let's take a look at an example file:</para>
|
||
<programlisting>
|
||
<configuration xmlns="urn:activemq"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
|
||
|
||
<defaultuser name="guest" password="guest">
|
||
<role name="guest"/>
|
||
</defaultuser>
|
||
|
||
<user name="tim" password="marmite">
|
||
<role name="admin"/>
|
||
</user>
|
||
|
||
<user name="andy" password="doner_kebab">
|
||
<role name="admin"/>
|
||
<role name="guest"/>
|
||
</user>
|
||
|
||
<user name="jeff" password="camembert">
|
||
<role name="europe-users"/>
|
||
<role name="guest"/>
|
||
</user>
|
||
|
||
</configuration></programlisting>
|
||
<para>The first thing to note is the element <literal>defaultuser</literal>. This defines
|
||
what user will be assumed when the client does not specify a username/password when
|
||
creating a session. In this case they will be the user <literal>guest</literal> and have
|
||
the role also called <literal>guest</literal>. Multiple roles can be specified for a
|
||
default user.</para>
|
||
<para>We then have three more users, the user <literal>tim</literal> has the role <literal
|
||
>admin</literal>. The user <literal>andy</literal> has the roles <literal
|
||
>admin</literal> and <literal>guest</literal>, and the user <literal>jeff</literal>
|
||
has the roles <literal>europe-users</literal> and <literal>guest</literal>.</para>
|
||
</section>
|
||
<section id="change-security-manager">
|
||
<title>Changing the security manager</title>
|
||
<para>If you do not want to use the default security manager then you can specify a
|
||
different one by editing the file <literal>activemq-beans.xml</literal> (or <literal
|
||
>activemq-jboss-beans.xml</literal> if you're running JBoss Application Server) and
|
||
changing the class for the <literal>ActiveMQSecurityManager</literal> bean.</para>
|
||
<para>Let's take a look at a snippet from the default beans file:</para>
|
||
<programlisting>
|
||
<bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
|
||
<start ignored="true"/>
|
||
<stop ignored="true"/>
|
||
</bean></programlisting>
|
||
<para>The class <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl</literal>
|
||
is the default security manager that is used by the standalone server.</para>
|
||
<para>ActiveMQ ships with two other security manager implementations you can use
|
||
off-the-shelf; one a JAAS security manager and another for integrating with JBoss
|
||
Application Sever security, alternatively you could write your own implementation by
|
||
implementing the <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManager</literal>
|
||
interface, and specifying the classname of your implementation in the file <literal
|
||
>activemq-beans.xml</literal> (or <literal>activemq-jboss-beans.xml</literal> if
|
||
you're running JBoss Application Server).</para>
|
||
<para>These two implementations are discussed in the next two sections.</para>
|
||
</section>
|
||
<section>
|
||
<title>JAAS Security Manager</title>
|
||
<para>JAAS stands for 'Java Authentication and Authorization Service' and is a standard part
|
||
of the Java platform. It provides a common API for security authentication and
|
||
authorization, allowing you to plugin your pre-built implementations.</para>
|
||
<para>To configure the JAAS security manager to work with your pre-built JAAS infrastructure
|
||
you need to specify the security manager as a <literal>JAASSecurityManager</literal> in
|
||
the beans file. Here's an example:</para>
|
||
<programlisting>
|
||
<bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
|
||
<start ignored="true"/>
|
||
<stop ignored="true"/>
|
||
|
||
<property name="ConfigurationName">org.apache.activemq.jms.example.ExampleLoginModule</property>
|
||
<property name="Configuration">
|
||
<inject bean="ExampleConfiguration"/>
|
||
</property>
|
||
<property name="CallbackHandler">
|
||
<inject bean="ExampleCallbackHandler"/>
|
||
</property>
|
||
</bean></programlisting>
|
||
<para>Note that you need to feed the JAAS security manager with three properties:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>ConfigurationName: the name of the <literal>LoginModule</literal>
|
||
implementation that JAAS must use</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Configuration: the <literal>Configuration</literal> implementation used by
|
||
JAAS</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>CallbackHandler: the <literal>CallbackHandler</literal> implementation to use
|
||
if user interaction are required</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<section>
|
||
<title>Example</title>
|
||
<para>See <xref linkend="examples.jaas"/> for an example which shows how ActiveMQ can be
|
||
configured to use JAAS.</para>
|
||
</section>
|
||
</section>
|
||
<section>
|
||
<title>JBoss AS Security Manager</title>
|
||
<para>The JBoss AS security manager is used when running ActiveMQ inside the JBoss
|
||
Application server. This allows tight integration with the JBoss Application Server's
|
||
security model.</para>
|
||
<para>The class name of this security manager is <literal
|
||
>org.apache.activemq.integration.jboss.security.JBossASSecurityManager</literal></para>
|
||
<para>Take a look at one of the default <literal>activemq-jboss-beans.xml</literal> files for
|
||
JBoss Application Server that are bundled in the distribution for an example of how this
|
||
is configured.</para>
|
||
<section>
|
||
<title>Configuring Client Login</title>
|
||
<para>JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet
|
||
or EJB sets security credentials on the current security context and these are used throughout the call.
|
||
If you would like these credentials to be used by ActiveMQ when sending or consuming messages then
|
||
set <literal>allowClientLogin</literal> to true. This will bypass ActiveMQ authentication and propagate the
|
||
provided Security Context. If you would like ActiveMQ to authenticate using the propagated security then set the
|
||
<literal>authoriseOnClientLogin</literal> to true also.</para>
|
||
<para>There is more info on using the JBoss client login module <ulink
|
||
url="http://community.jboss.org/wiki/ClientLoginModule">here</ulink> </para>
|
||
<note><para>If messages are sent non blocking then there is a chance that these could arrive on the server after
|
||
the calling thread has completed meaning that the security context has been cleared. If this is the case then messages
|
||
will need to be sent blocking</para></note>
|
||
</section>
|
||
<section>
|
||
<title>Changing the Security Domain</title>
|
||
<para>The name of the security domain used by the JBoss AS security manager defaults to <literal>java:/jaas/activemq
|
||
</literal>. This can be changed by specifying <literal>securityDomainName</literal> (e.g. java:/jaas/myDomain).
|
||
</para>
|
||
</section>
|
||
</section>
|
||
<section>
|
||
<title>Changing the username/password for clustering</title>
|
||
<para>In order for cluster connections to work correctly, each node in the cluster must make
|
||
connections to the other nodes. The username/password they use for this should always be
|
||
changed from the installation default to prevent a security risk.</para>
|
||
<para>Please see <xref linkend="management"/> for instructions on how to do this.</para>
|
||
</section>
|
||
</chapter>
|