path: root/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml

<?xml version="1.0" encoding="utf-8"?>

<!--

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.

-->

<section id="Java-Broker-Security-ACLs">
  <title>Access Control Lists</title>
  <para>
    In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user.
    To enable, the &lt;acl/&gt; element is used within the &lt;security/&gt; element of the configuration XML.
    In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual
    hosts.  The  &lt;acl/&gt; configuration references a text file containing the ACL rules.
    By convention, this file should have a .acl extension.
  </para>


  <section role="h3" id="Java-Broker-Security-ACLs-EnablingACL">
    <title>
       Enabling ACLs
    </title>

    <para>
      To apply an ACL broker-wide, add the following to the config.xml (assuming that <replaceable>conf</replaceable> has been set to a suitable
      location such as ${QPID_HOME}/etc):
    </para>

    <programlisting>
      &lt;broker&gt;
        ...
        &lt;security&gt;
          ...
          &lt;acl&gt;<replaceable>${conf}/broker.acl</replaceable>&lt;/acl&gt;
        &lt;/security&gt;
      &lt;/broker&gt;
    </programlisting>

    <para>
    </para>

    <para>
      To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml:
    </para>

    <programlisting>
      &lt;virtualhost&gt;
        ...
        &lt;name&gt;test&lt;/name&gt;
        &lt;test&gt;
          ...
          &lt;security&gt;
            &lt;acl&gt;<replaceable>${conf}/vhost_test.acl</replaceable>&lt;/acl&gt;
          &lt;/security&gt;
        &lt;/test&gt;
      &lt;/virtualhost&gt;
    </programlisting>
  </section>

  <section role="h3" id="Java-Broker-Security-ACLs-WriteACL">
    <title>
       Writing .acl files
    </title>

    <para>
      The ACL file consists of a series of rules associating behaviour for a user or group. Use of groups can serve to make the ACL file more concise. See <link linkend="Java-Broker-Security-Group-Providers">Configuring Group Providers</link> for more information on defining groups.
    </para>
    <para>
      Each ACL rule grants or denies a particular action on an object to a user/group.  The rule may be augmented with one or more properties, restricting
      the rule's applicability.
    </para>
    <programlisting>
      ACL ALLOW alice CREATE QUEUE              # Grants alice permission to create all queues.
      ACL DENY bob CREATE QUEUE name="myqueue"  # Denies bob permission to create a queue called "myqueue"
    </programlisting>
    <para>
      The ACL is considered in strict line order with the first matching rule taking precedence over all those that follow. In the following
      example, if the user bob tries to create an exchange "myexch", the operation will be allowed by the first rule.  The second rule will
      never be considered.
    </para>
    <programlisting>
      ACL ALLOW bob ALL EXCHANGE
      ACL DENY bob CREATE EXCHANGE name="myexch"  # Dead rule
    </programlisting>
    <para>
      If the desire is to allow bob to create all exchanges except "myexch", order of the rules must be reversed:
    </para>
    <programlisting>
      ACL DENY bob CREATE EXCHANGE name="myexch"
      ACL ALLOW bob ALL EXCHANGE
    </programlisting>
    <para>
      All ACL files end with an implict rule denying all operations to all users.  It is as if each file ends with
      <programlisting>ACL DENY ALL ALL </programlisting>
      If instead you wish to <emphasis>allow</emphasis> all operations other than those controlled by earlier rules,
      add <programlisting>ACL ALLOW ALL ALL</programlisting> to the bottom of the ACL file.
    </para>
    <para>
      When writing a new ACL, a good approach is to begin with an .acl file containing only <programlisting>ACL DENY-LOG ALL ALL</programlisting>
      which will cause the Broker to deny all operations with details of the denial logged to the Qpid log file. Build up the ACL rule by rule,
      gradually working through the use-cases of your system.  Once the ACL is complete, consider switching the DENY-LOG actions to DENY
      to improve performamce and reduce log noise.
    </para>
    <para>
      ACL rules are very powerful: it is possible to write very granular rules specifying many broker objects and their
      properties.  Most projects probably won't need this degree of flexibility.  A reasonable approach is to choose to apply permissions
      at a certain level of abstraction (e.g. QUEUE) and apply them consistently across the whole system.
    </para>
  </section>

  <section role="h4" id="Java-Broker-Security-ACLs-Syntax">
    <title>
       Syntax
    </title>

    <para>
       ACL rules follow this syntax:
    </para>
    <programlisting>
     ACL {permission} {&lt;group-name&gt;|&lt;user-name>&gt;|ALL} {action|ALL} [object|ALL] [property="&lt;property-value&gt;"]
    </programlisting>

    <para>
       Comments may be introduced with the hash (#) character and are ignored.  Long lines can be broken with the slash (\) character.
    </para>
    <programlisting>
      # A comment
      ACL ALLOW admin CREATE ALL # Also a comment
      ACL DENY guest \
      ALL ALL   # A broken line
    </programlisting>
  </section>
  <table id="table-Java-Broker-Security-ACLs-Syntax_permissions">
    <title>List of ACL permission</title>
    <tgroup cols="2">
      <tbody>
        <row>
          <entry><command>ALLOW</command></entry>
          <entry><para>Allow the action</para></entry>
        </row>
        <row>
          <entry><command>ALLOW-LOG</command></entry>
          <entry><para> Allow the action and log the action in the log </para></entry>
        </row>
        <row>
          <entry><command>DENY</command></entry>
          <entry><para> Deny the action</para></entry>
        </row>
        <row>
          <entry><command>DENY-LOG</command></entry>
          <entry><para> Deny the action and log the action in the log</para></entry>
       </row>
     </tbody>
    </tgroup>
  </table>
  <table id="table-Java-Broker-Security-ACLs-Syntax_actions">
    <title>List of ACL actions</title>
    <tgroup cols="2">
      <tbody>
        <row>
          <entry> <command>CONSUME</command> </entry>
          <entry> <para> Applied when subscriptions are created </para> </entry>
        </row>
        <row>
          <entry> <command>PUBLISH</command> </entry>
          <entry> <para> Applied on a per message basis on publish message transfers</para> </entry>
        </row>
        <row>
          <entry> <command>CREATE</command> </entry>
          <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry>
        </row>
        <row>
          <entry> <command>ACCESS</command> </entry>
          <entry> <para> Applied when an object is read or accessed</para> </entry>
        </row>
        <row>
          <entry> <command>BIND</command> </entry>
          <entry> <para> Applied when queues are bound to exchanges</para> </entry>
        </row>
        <row>
          <entry> <command>UNBIND</command> </entry>
          <entry> <para> Applied when queues are unbound from exchanges</para> </entry>
        </row>
        <row>
          <entry> <command>DELETE</command> </entry>
          <entry> <para> Applied when objects are deleted </para> </entry>
        </row>
        <row>
          <entry> <command>PURGE</command> </entry> <entry>
          <para>Applied when purge the contents of a queue</para> </entry>
        </row>
        <row>
          <entry> <command>UPDATE</command> </entry>
          <entry> <para> Applied when an object is updated </para> </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <table id="table-Java-Broker-Security-ACLs-Syntax_objects">
    <title>List of ACL objects</title>
    <tgroup cols="2">
      <tbody>
        <row>
          <entry> <command>VIRTUALHOST</command> </entry>
          <entry> <para>A virtualhost (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>MANAGEMENT </command> </entry>
          <entry> <para>Management - for web and JMX (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>QUEUE</command> </entry>
          <entry> <para>A queue </para> </entry>
        </row>
        <row>
          <entry> <command>EXCHANGE</command> </entry>
        <entry> <para>An exchange </para> </entry>
        </row>
        <row>
          <entry> <command>USER</command> </entry>
          <entry> <para>A user (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>GROUP</command> </entry>
          <entry> <para>A group (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>METHOD</command> </entry>
          <entry> <para>Management or agent or broker method (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>LINK</command> </entry>
          <entry> <para>A federation or inter-broker link (not currently used in Java Broker)</para> </entry>
        </row>
        <row>
          <entry> <command>BROKER</command> </entry>
          <entry> <para>The broker (not currently used in Java Broker)</para> </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <table id="table-Java-Broker-Security-ACLs-Syntax_properties">
    <title>List of ACL properties</title>
    <tgroup cols="2">
      <tbody>
        <row>
          <entry><command>name</command> </entry>
          <entry> <para> String. Object name, such as a queue name, exchange name or JMX method name.  </para> </entry>
        </row>
        <row>
          <entry> <command>durable</command> </entry>
          <entry> <para> Boolean. Indicates the object is durable </para> </entry>
        </row>
        <row>
          <entry> <command>routingkey</command> </entry>
          <entry> <para> String. Specifies routing key </para> </entry>
        </row>
        <row>
          <entry> <command>passive</command> </entry>
          <entry> <para> Boolean. Indicates the presence of a <parameter>passive</parameter> flag </para> </entry>
        </row>
        <row>
          <entry> <command>autodelete</command> </entry>
          <entry> <para> Boolean. Indicates whether or not the object gets deleted when the connection is closed </para> </entry>
        </row>
        <row>
          <entry> <command>exclusive</command> </entry>
          <entry> <para> Boolean. Indicates the presence of an <parameter>exclusive</parameter> flag </para> </entry>
        </row>
        <row>
          <entry> <command>temporary</command> </entry>
          <entry> <para> Boolean. Indicates the presence of an <parameter>temporary</parameter> flag </para> </entry>
        </row>
        <row>
          <entry> <command>type</command> </entry>
          <entry> <para> String. Type of object, such as topic, fanout, or xml </para> </entry>
        </row>
        <row>
          <entry> <command>alternate</command> </entry>
          <entry> <para> String. Name of the alternate exchange </para> </entry>
        </row>
        <row>
          <entry> <command>queuename</command> </entry>
          <entry> <para> String. Name of the queue (used only when the object is something other than <parameter>queue</parameter> </para> </entry>
        </row>
        <row>
          <entry> <command>component</command> </entry>
          <entry> <para> String. JMX component name (Java Broker only)</para> </entry>
        </row>
        <row>
          <entry> <command>schemapackage</command> </entry>
          <entry> <para> String. QMF schema package name (Not used in Java Broker)</para> </entry>
        </row>
        <row>
          <entry> <command>schemaclass</command> </entry>
          <entry> <para> String. QMF schema class name (Not used in Java Broker)</para> </entry>
        </row>
        <row>
          <entry> <command>from_network</command> </entry>
          <entry>
            <para>
              Comma-separated strings representing IPv4 address ranges.
            </para>
            <para>
              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
            </para>
            <para>
              The rule matches if any of the address ranges match the IPv4 address of the messaging client.
              The address ranges are specified using either Classless Inter-Domain Routing notation
              (e.g. 192.168.1.0/24; see <ulink url="http://tools.ietf.org/html/rfc4632">RFC 4632</ulink>)
              or wildcards (e.g. 192.169.1.*).
            </para>
            <para>
              Java Broker only.
            </para>
          </entry>
        </row>
        <row>
          <entry> <command>from_hostname</command> </entry>
          <entry>
            <para>
              Comma-separated strings representing hostnames, specified using Perl-style regular
              expressions, e.g. .*\.example\.company\.com
            </para>
            <para>
              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
            </para>
            <para>
              The rule matches if any of the patterns match the hostname of the messaging client.
            </para>
            <para>
              To look up the client's hostname, Qpid uses Java's DNS support, which internally caches its results.
            </para>
            <para>
              You can modify the time-to-live of cached results using the *.ttl properties described on the
              Java <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html">Networking
              Properties</ulink> page.
            </para>
            <para>
              For example, you can either set system property sun.net.inetaddr.ttl from the command line
              (e.g. export QPID_OPTS="-Dsun.net.inetaddr.ttl=0") or networkaddress.cache.ttl in
              $JAVA_HOME/lib/security/java.security. The latter is preferred because it is JVM
              vendor-independent.
            </para>
            <para>
              Java Broker only.
            </para>
          </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <table id="table-Java-Broker-Security-ACLs-Syntax_javacomponents">
    <title>List of ACL rules</title>
    <tgroup cols="3">
      <tbody>
        <row>
          <entry> <command>UserManagement</command> </entry>
          <entry> <para>User maintainance; create/delete/view users, change passwords etc</para> </entry>
          <entry> <para>permissionable at broker level only</para> </entry>
        </row>
        <row>
          <entry> <command>ConfigurationManagement</command> </entry>
          <entry> <para>Dynammically reload configuration from disk.</para> </entry>
          <entry> <para>permissionable at broker level only</para> </entry>
        </row>
        <row>
          <entry> <command>LoggingManagement</command> </entry>
          <entry> <para>Dynammically control Qpid logging level</para> </entry>
          <entry> <para>permissionable at broker level only</para> </entry>
        </row>
        <row>
          <entry> <command>ServerInformation</command> </entry>
          <entry> <para>Read-only information regarding the Qpid: version number etc</para> </entry>
          <entry> <para>permissionable at broker level only</para> </entry>
        </row>
        <row>
          <entry> <command>VirtualHost.Queue</command> </entry>
          <entry> <para>Queue maintainance; copy/move/purge/view etc</para> </entry>
        </row>
        <row>
          <entry> <command>VirtualHost.Exchange</command> </entry>
          <entry> <para>Exchange maintenance; bind/unbind queues to exchanges</para> </entry>
        </row>
        <row>
          <entry> <command>VirtualHost.VirtualHost</command> </entry>
          <entry> <para>Virtual host maintainace; create/delete exchanges, queues etc</para> </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <section role="h4" id="Java-Broker-Security-ACLs-WorkedExamples">
    <title>
      Worked Examples
    </title>
    <para>
      Here are some example ACLs illustrating common use cases.
      In addition, note that the Java broker provides a complete example ACL file, located at etc/broker_example.acl.
    </para>
    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample1">
      <title>
        Worked example 1 - Management rights
      </title>
      <para>
        Suppose you wish to permission two users: a user 'operator' must be able to perform all Management operations, and
        a user 'readonly' must be enable to perform only read-only functions.  Neither 'operator' nor 'readonly'
        should be allowed to connect clients for messaging.
      </para>
      <programlisting>
# Deny (loggged) operator/readonly permission to connect messaging clients.
ACL DENY-LOG operator ACCESS VIRTUALHOST
ACL DENY-LOG readonly ACCESS VIRTUALHOST
# Give operator permission to perfom all other actions
ACL ALLOW operator ALL ALL
# Give readonly permission to execute only read-only actions
ACL ALLOW readonly ACCESS ALL
...
... rules for other users
...
# Explicitly deny all (log) to eveyone
ACL DENY-LOG ALL ALL
      </programlisting>
    </section>
    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample2">
      <title>
        Worked example 2 - User maintainer group
      </title>
      <para>
        Suppose you wish to restrict User Management operations to users belonging to a
        <link linkend="Java-Broker-Security-Group-Providers">group</link> 'usermaint'.  No other user
        is allowed to perform user maintainence  This example illustrates the permissioning of an individual component.
      </para>
      <programlisting>
# Give usermaint access to management and permission to execute all JMX Methods on the
# UserManagement MBean and perform all actions for USER objects
ACL ALLOW usermaint ACCESS MANAGEMENT
ACL ALLOW usermaint ALL METHOD component="UserManagement"
ACL ALLOW usermaint ALL USER
ACL DENY ALL ALL METHOD component="UserManagement"
ACL DENY ALL ALL USER
...
... rules for other users
...
ACL DENY-LOG ALL ALL
      </programlisting>
    </section>
    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample3">
      <title>
        Worked example 3 - Request/Response messaging
      </title>
      <para>
        Suppose you wish to permission a system using a request/response paradigm. Two users: 'client' publishes requests;
        'server' consumes the requests and generates a response.  This example illustrates the permissioning of AMQP exchanges
        and queues.
      </para>
      <programlisting>
# Allow client and server to connect to the virtual host.
ACL ALLOW client ACCESS VIRTUALHOST
ACL ALLOW server ACCESS VIRTUALHOST

# Client side
# Allow the 'client' user to publish requests to the request queue. As is the norm for the request/response paradigm, the client
# is required to create a temporary queue on which the server will respond.  Consequently, there are rules to allow the creation
# of the temporary queues and consumption of messages from it.
ACL ALLOW client CREATE QUEUE temporary="true"
ACL ALLOW client CONSUME QUEUE temporary="true"
ACL ALLOW client DELETE QUEUE temporary="true"
ACL ALLOW client BIND EXCHANGE name="amq.direct" temporary="true"
ACL ALLOW client UNBIND EXCHANGE name="amq.direct" temporary="true"
ACL ALLOW client PUBLISH EXCHANGE name="amq.direct" routingKey="example.RequestQueue"

# Server side
# Allow the 'server' user to consume from the request queue and publish a response to the temporary response queue created by
# client.  We also allow the server to create the request queue.
ACL ALLOW server CREATE QUEUE name="example.RequestQueue"
ACL ALLOW server CONSUME QUEUE name="example.RequestQueue"
ACL ALLOW server BIND EXCHANGE
ACL ALLOW server PUBLISH EXCHANGE name="amq.direct" routingKey="TempQueue*"

ACL DENY-LOG all all
      </programlisting>
    </section>
    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample4">
      <title>
        Worked example 4 - firewall-like access control
      </title>
      <para>
        This example illustrates how to set up an ACL that restricts the IP addresses and hostnames
        of messaging clients that can access a virtual host.
      </para>
      <programlisting>
################
# Hostname rules
################

# Allow messaging clients from company1.com and company1.co.uk to connect
ACL ALLOW all ACCESS VIRTUALHOST from_hostname=".*\.company1\.com,.*\.company1\.co\.uk"

# Deny messaging clients from hosts within the dev subdomain
ACL DENY-LOG all ACCESS VIRTUALHOST from_hostname=".*\.dev\.company1\.com"

##################
# IP address rules
##################

# Deny access to all users in the IP ranges 192.168.1.0-192.168.1.255 and 192.168.2.0-192.168.2.255,
# using the notation specified in RFC 4632, "Classless Inter-domain Routing (CIDR)"
ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
  from_network="192.168.1.0/24,192.168.2.0/24"

# Deny access to all users in the IP ranges 192.169.1.0-192.169.1.255 and 192.169.2.0-192.169.2.255,
# using wildcard notation.
ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
  from_network="192.169.1.*,192.169.2.*"

ACL DENY-LOG all all
      </programlisting>
    </section>
  </section>
</section>