[jboss-cvs] JBoss Messaging SVN: r6746 - in trunk/docs/user-manual/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 12 13:44:49 EDT 2009
Author: timfox
Date: 2009-05-12 13:44:49 -0400 (Tue, 12 May 2009)
New Revision: 6746
Modified:
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/modules/security.xml
Log:
security chapter
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-12 16:34:38 UTC (rev 6745)
+++ trunk/docs/user-manual/en/master.xml 2009-05-12 17:44:49 UTC (rev 6746)
@@ -9,6 +9,7 @@
<!ENTITY using-core SYSTEM "modules/using-core.xml">
<!ENTITY embedding-jbm SYSTEM "modules/embedding-jbm.xml">
<!ENTITY security SYSTEM "modules/security.xml">
+ <!ENTITY wildcard-syntax SYSTEM "modules/wildcard-syntax.xml">
<!ENTITY persistence SYSTEM "modules/persistence.xml">
<!ENTITY management SYSTEM "modules/management.xml">
<!ENTITY large-messages SYSTEM "modules/large-messages.xml">
@@ -54,6 +55,7 @@
&using-core;
&embedding-jbm;
&security;
+ &wildcard-syntax;
&persistence;
&management;
&large-messages;
Modified: trunk/docs/user-manual/en/modules/security.xml
===================================================================
--- trunk/docs/user-manual/en/modules/security.xml 2009-05-12 16:34:38 UTC (rev 6745)
+++ trunk/docs/user-manual/en/modules/security.xml 2009-05-12 17:44:49 UTC (rev 6746)
@@ -1,31 +1,238 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="security">
<title>Security</title>
- <para>blah</para>
-
+ <para>This chapter describes how security works with JBoss Messaging and how you can configure
+ it.</para>
<section>
- <title>Configuring role based security for addresses</title>
- <para></para>
+ <title>Role based security for addresses</title>
+ <para>JBoss Messaging contains a flexible role-based security model for applying security to
+ queues, based on their addresses.</para>
+ <para>As explained in section [LINK] JBoss Messaging 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>JBoss Messaging core is JMS agnostic. It does not have any concept of a JMS Topic. A
+ JMS Topic is implemented in core as an address (the topic name) with zero or more queues
+ bound to it. Each queue bound to that address represents a topic subscription. A JMS
+ Queue is implemented as an address (the JMS Queue name) with one queue bound to it which
+ represents the JMS Queue.</para>
+ <para>By convention, all JMS Queues map to core queues where the core queue name has the
+ string <literal>jms.queue.</literal> prepended to it. E.g. the JMS Queue with the name
+ "orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The
+ address aty which the core queue is bound is also given by the core queue name.</para>
+ <para>For JMS Topics the address at which the queues that represent the subscriptions are
+ bound is given by prepending the string "jms.topic." to the name of the JMS Topic. E.g.
+ the JMS Topic with name "news.europe" would map to the core address
+ "jms.topic.news.europe"</para>
+ <para>In other words if you send a JMS Message to a JMS Queue with name "orders.europe" it
+ will get routed on the server to any core queues bound to the address
+ "jms.queue.orders.europe". If you send a JMS Message to a JMS Topic with name
+ "news.europe" it will get routed on the server to any core queues bound to the address
+ "jms.topic.news.europe".</para>
+ <para>JBoss Messaging 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>Six 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>createTempQueue</literal>. This permission allows the user to create
+ a temporary queue under matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>deleteTempQueue</literal>. This permission allows the user to delete
+ a temporarry 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>
+ </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
+ >jbm-configuration.xml</literal> or <literal>jbm-queues.xml</literal> file:</para>
+ <programlisting>
+<security match="globalqueues.europe.#">
+ <permission type="createDurableQueue" roles="admin"/>
+ <permission type="deleteDurableQueue" roles="admin"/>
+ <permission type="createTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="deleteTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="send" roles="admin, europe-users"/>
+ <permission type="consume" roles="admin, europe-users"/>
+</security>
+ </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 the chapter [LINK]. 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>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. JBoss Messaging 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 section
+ [LINK]</para>
+ <para>There can be zero or more <literal>security</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 security block:</para>
+ <programlisting>
+<security match="globalqueues.europe.orders.#">
+ <permission type="send" roles="europe-users"/>
+ <permission type="consume" roles="europe-users"/>
+</security>
+ </programlisting>
+ <para>In this security 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 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 send and
+ consume for the role europe-users. The permissions createDurableQueue,
+ deleteDurableQueue, createTempQueue, deleteTempQueue are not inherited from the other
+ security block.</para>
+ <para>By not inheriting permissions, it allows you to effectively deny permissions in more
+ specific security blocks by simply not specifying them. Otherwise it would not be
+ possible to deny permissions in sub-groups of addresses.</para>
</section>
-
<section>
- <title>SSL</title>
- <para></para>
+ <title>Secure Sockets 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 JBoss Messaging allows that
+ traffic to be encrypted using the Secure Sockets Transport (SSL).</para>
+ <para>For more information on configuring the SSL transport please see the section
+ [LINK]</para>
</section>
-
<section>
<title>Basic user credentials</title>
- <para></para>
+ <para> JBoss Messaging ships with a security manager implementation that reads user
+ credentials, i.e. usernames, passwords and role information from an xml file on the
+ classpath <literal>jbm-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:jboss:messaging" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-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>default-user</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 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>Then we 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>
- <title>JAAS</title>
- <para></para>
+ <title>Changing the security manager</title>
+ <para>If you do not want to use the default security manager which reads user credentials
+ from the <literal>jbm-users.xml</literal> file, then you can specify the security
+ manager that JBoss Messaging uses by editing the <literal>jbm-jboss-beans.xml</literal>
+ file and changing the class of the security manager that gets injected into the JBoss
+ Messaging server when the JBoss Microcontainer starts up the beans.</para>
+ <para>Let's take a look at a snippet from the default beans file:</para>
+ <programlisting>
+<bean name="JBMSecurityManager" class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+</bean>
+ </programlisting>
+ <para>The class <literal
+ >org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl</literal> is the
+ security manager that reads user credentials from the <literal>jbm-users.xml</literal>
+ file. So if you don't want to use that you can replace this with the class name of the
+ security manager of your choice.</para>
+ <para>JBoss Messaging 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.jboss.messaging.core.security.SecurityManager</literal>
+ interface, and specifying the classname of your implementation in the <literal
+ >jbm-jboss-beans.xml</literal> file.</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 in your pre-built implementations.</para>
+ <para>To use the JAAS security manager. Specify the class name <literal
+ >org.jboss.messaging.integration.security.JAASSecurityManager</literal> in the
+ <literal>jbm-jboss-beans.xml</literal> file.</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 JAASSecurityManager in the beans file. Here's an example:</para>
+ <programlisting>
+<bean name="JBMSecurityManager" class="org.jboss.messaging.integration.security.JAASSecurityManager">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ <attribute name="ConfigurationName">MyJAASConfigurationName</attribute>
+ <attribute name="CallbackHandler"><inject bean="MyJAASCallbackHandler"/></attribute>
+ <attribute name="Configuration"><inject bean="MyJAASConfiguration"/></attribute>
+
+</bean>
+ </programlisting>
+ <para>Note that you need to feed the JAAS security manager with three attributes:</para>
+ <itemizedlist>
+ <listitem><para>ConfigurationName: Jeff please complete</para></listitem>
+ <listitem><para>CallbackHandler: Jeff please complete</para></listitem>
+ <listitem><para>Configuration: Jeff please complete</para></listitem>
+ </itemizedlist>
+ <para>TODO Blah blah Jeff please complete</para>
+ </section>
<section>
- <title>JBoss AS security manager</title>
- <para></para>
+ <title>JBoss AS Security Manager</title>
+ <para> The JBoss AS security manager is used when running JBoss Messaging inside JBoss
+ Application server and when you want tight integration with JBoss Application Server's
+ security model.</para>
+ <para>When running inside JBoss Application Server you will, by default, be using this
+ security manager. The class name of this security manager is <literal
+ >org.jboss.messaging.integration.security.JBossASSecurityManager</literal></para>
+ <para>Take a look at one of the default <literal>jbm-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>
-
</chapter>
More information about the jboss-cvs-commits
mailing list