You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2017/09/26 16:00:54 UTC
qpid-broker-j git commit: QPID-7923: [Java Broker] [ACL] Improve ACL
documentation
Repository: qpid-broker-j
Updated Branches:
refs/heads/master 3f5138a34 -> f61b8b903
QPID-7923: [Java Broker] [ACL] Improve ACL documentation
* Add attributes_names object property to document
* Rework the chapter including details about how access control providers can be installed at the Broker and Virtualhost levels.
* Rework the examples
Project: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/commit/f61b8b90
Tree: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/tree/f61b8b90
Diff: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/diff/f61b8b90
Branch: refs/heads/master
Commit: f61b8b903899ca587b61da30f59c2147b0952a7b
Parents: 3f5138a
Author: Keith Wall <kw...@apache.org>
Authored: Tue Sep 26 16:58:20 2017 +0100
Committer: Keith Wall <kw...@apache.org>
Committed: Tue Sep 26 16:58:25 2017 +0100
----------------------------------------------------------------------
.../plugins/RuleBasedAccessControlProvider.java | 2 +-
broker/etc/broker_example.acl | 106 ----
.../src/docbkx/Java-Broker-Security.xml | 2 +-
.../Java-Broker-Concepts-Other-Services.xml | 2 +-
...gement-Managing-Access-Control-Providers.xml | 2 +-
.../security/Java-Broker-Security-ACLs.xml | 576 -------------------
...a-Broker-Security-AccessControlProviders.xml | 564 ++++++++++++++++++
...curity-Authentication-Providers-External.xml | 2 +-
.../Java-Broker-Security-Group-Providers.xml | 2 +-
9 files changed, 570 insertions(+), 688 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/broker-plugins/access-control/src/main/java/org/apache/qpid/server/security/access/plugins/RuleBasedAccessControlProvider.java
----------------------------------------------------------------------
diff --git a/broker-plugins/access-control/src/main/java/org/apache/qpid/server/security/access/plugins/RuleBasedAccessControlProvider.java b/broker-plugins/access-control/src/main/java/org/apache/qpid/server/security/access/plugins/RuleBasedAccessControlProvider.java
index 2a8d7ed..1f45be0 100644
--- a/broker-plugins/access-control/src/main/java/org/apache/qpid/server/security/access/plugins/RuleBasedAccessControlProvider.java
+++ b/broker-plugins/access-control/src/main/java/org/apache/qpid/server/security/access/plugins/RuleBasedAccessControlProvider.java
@@ -38,7 +38,7 @@ public interface RuleBasedAccessControlProvider<X extends RuleBasedAccessControl
String DEFAULT_RESULT= "defaultResult";
String RULES = "rules";
- @ManagedAttribute( mandatory = true, defaultValue = "DENIED", validValues = { "ALLOWED", "DENIED" }, description = "the default resil to use if no rules match the requested operation")
+ @ManagedAttribute( mandatory = true, defaultValue = "DENIED", validValues = { "ALLOWED", "DENIED" }, description = "the default result to use if no rules match the requested operation")
Result getDefaultResult();
@ManagedAttribute( mandatory = true, defaultValue = "[ { \"identity\" : \"ALL\", \"objectType\" : \"ALL\", \"operation\" : \"ALL\", \"attributes\" : {}, \"outcome\" : \"ALLOW\"} ]", description = "the ordered list of ACL rules")
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/broker/etc/broker_example.acl
----------------------------------------------------------------------
diff --git a/broker/etc/broker_example.acl b/broker/etc/broker_example.acl
deleted file mode 100644
index 8e89610..0000000
--- a/broker/etc/broker_example.acl
+++ /dev/null
@@ -1,106 +0,0 @@
-#
-# 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.
-#
-
-### EXAMPLE ACL V2 FILE
-### NOTE: Rules are considered from top to bottom, and the first matching rule governs the decision.
-### Rules may refer to users or groups. Groups are currently defined in the etc/groups file.
-
-
-### WEB MANAGEMENT ####
-
-# To use web management, first give the user/group ACCESS MANAGEMENT permission
-ACL ALLOW webadmins ACCESS MANAGEMENT
-
-# ACL for web management console admins
-# All rules below are required for console admin users
-# to perform create/update/delete operations
-ACL ALLOW-LOG webadmins CREATE QUEUE
-ACL ALLOW-LOG webadmins UPDATE QUEUE
-ACL ALLOW-LOG webadmins DELETE QUEUE
-ACL ALLOW-LOG webadmins PURGE QUEUE
-ACL ALLOW-LOG webadmins CREATE EXCHANGE
-ACL ALLOW-LOG webadmins DELETE EXCHANGE
-ACL ALLOW-LOG webadmins BIND EXCHANGE
-ACL ALLOW-LOG webadmins UNBIND EXCHANGE
-ACL ALLOW-LOG webadmins CREATE GROUP
-ACL ALLOW-LOG webadmins DELETE GROUP
-ACL ALLOW-LOG webadmins UPDATE GROUP
-ACL ALLOW-LOG webadmins CREATE USER
-ACL ALLOW-LOG webadmins DELETE USER
-ACL ALLOW-LOG webadmins UPDATE USER
-
-ACL ALLOW-LOG webadmins UPDATE METHOD
-
-# authorise operations changing broker model
-ACL ALLOW-LOG webadmins CONFIGURE BROKER
-
-# authorise operations to view and download broker logs
-ACL ALLOW webadmins ACCESS_LOGS BROKER
-
-# at the moment only the following UPDATE METHOD rules are supported by web management console
-#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="moveMessages"
-#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="copyMessages"
-#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="deleteMessages"
-#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="clearQueue"
-
-### MESSAGING ###
-# The 'ACCESS VIRTUALHOST' rules below apply to messaging operations (as opposed to management operations)
-
-# Firewall examples
-
-# Deny access to all users from *.example.company1.com and *.example.company2.com
-ACL DENY-LOG all ACCESS VIRTUALHOST from_hostname=".*\.example\.company1.com,.*\.example\.company2.com"
-
-# 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.*"
-
-# Allow 'messaging-users' group to connect to all virtualhosts
-ACL ALLOW-LOG messaging-users ACCESS VIRTUALHOST
-
-# Deny messaging-users management
-ACL DENY-LOG messaging-users ACCESS MANAGEMENT
-
-
-# Client side
-# Allow the 'client' user to publish requests to the request queue and create, consume from, and delete temporary reply queues.
-ACL ALLOW-LOG client CREATE QUEUE temporary="true"
-ACL ALLOW-LOG client CONSUME QUEUE temporary="true"
-ACL ALLOW-LOG client DELETE QUEUE temporary="true"
-ACL ALLOW-LOG client BIND EXCHANGE name="amq.direct" temporary="true"
-ACL ALLOW-LOG client UNBIND EXCHANGE name="amq.direct" temporary="true"
-ACL ALLOW-LOG client PUBLISH EXCHANGE name="amq.direct" routingKey="example.RequestQueue"
-
-# Server side
-# Allow the 'server' user to create and consume from the request queue and publish a response to the temporary response queue created by
-# client.
-ACL ALLOW-LOG server CREATE QUEUE name="example.RequestQueue"
-ACL ALLOW-LOG server CONSUME QUEUE name="example.RequestQueue"
-ACL ALLOW-LOG server BIND EXCHANGE
-ACL ALLOW-LOG server PUBLISH EXCHANGE name="amq.direct" routingKey="TempQueue*"
-
-
-### DEFAULT ###
-
-# Deny all users from performing all operations
-ACL DENY-LOG all all
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/Java-Broker-Security.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/Java-Broker-Security.xml b/doc/java-broker/src/docbkx/Java-Broker-Security.xml
index 754e0b6..a7e389e 100644
--- a/doc/java-broker/src/docbkx/Java-Broker-Security.xml
+++ b/doc/java-broker/src/docbkx/Java-Broker-Security.xml
@@ -24,6 +24,6 @@
<title>Security</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security/Java-Broker-Security-Authentication-Providers.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security/Java-Broker-Security-Group-Providers.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security/Java-Broker-Security-ACLs.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security/Java-Broker-Security-AccessControlProviders.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security/Java-Broker-Security-Configuration-Encryption.xml"/>
</chapter>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/concepts/Java-Broker-Concepts-Other-Services.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/concepts/Java-Broker-Concepts-Other-Services.xml b/doc/java-broker/src/docbkx/concepts/Java-Broker-Concepts-Other-Services.xml
index ae3eef0..897fb40 100644
--- a/doc/java-broker/src/docbkx/concepts/Java-Broker-Concepts-Other-Services.xml
+++ b/doc/java-broker/src/docbkx/concepts/Java-Broker-Concepts-Other-Services.xml
@@ -30,7 +30,7 @@
<section xml:id="Java-Broker-Concepts-Access-Control-Providers">
<title>Access Control Providers</title>
<para><emphasis>Access Control Providers</emphasis> are used to authorize various operations relating to Broker objects.</para>
- <para>Access Control Provider configuration and management details are covered in <xref linkend="Java-Broker-Security-ACLs"/>.</para>
+ <para>Access Control Provider configuration and management details are covered in <xref linkend="Java-Broker-Security-AccessControlProviders"/>.</para>
</section>
<section xml:id="Java-Broker-Concepts-Group-Providers">
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml b/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml
index ff26971..1b1f6db 100644
--- a/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml
+++ b/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml
@@ -25,5 +25,5 @@
<para>An <link linkend="Java-Broker-Concepts-Access-Control-Providers">Access Control
Provider</link> governs who may do what within the Broker. It governs both messaging and
management.</para>
- <para>See <xref linkend="Java-Broker-Security-ACLs"/></para>
+ <para>See <xref linkend="Java-Broker-Security-AccessControlProviders"/></para>
</section>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/security/Java-Broker-Security-ACLs.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/security/Java-Broker-Security-ACLs.xml b/doc/java-broker/src/docbkx/security/Java-Broker-Security-ACLs.xml
deleted file mode 100644
index 8cd3f8e..0000000
--- a/doc/java-broker/src/docbkx/security/Java-Broker-Security-ACLs.xml
+++ /dev/null
@@ -1,576 +0,0 @@
-<?xml version="1.0"?>
-<!--
-
- 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml: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, an <emphasis>Access Control Provider</emphasis> needs to be configured on the <emphasis>Broker</emphasis>.
- The <emphasis>Access Control Provider</emphasis> of type "AclFile" uses local file to specify the ACL rules.
- By convention, this file should have a .acl extension.
- </para>
-
- <para>
- A Group Provider can be configured with ACL to define the user groups which can be used in ACL
- to determine the ACL rules applicable to the entire group. The configuration details for the Group Providers are described in
- <xref linkend="Java-Broker-Security-Group-Providers"/>. On creation of ACL Provider with group rules,
- the Group Provider should be added first. Otherwise, if the individual ACL rules are not defined for the logged principal
- the following invocation of management operations could be denied due to absence of the required groups.</para>
-
- <para>Only one <emphasis>Access Control Provider</emphasis> can be used by the Broker.
- If several <emphasis>Access Control Providers</emphasis> are configured on Broker level
- only one of them will be used (the latest one).
- </para>
-
- <para>
- The ACL Providers can be configured using <link linkend="Java-Broker-Management-Channel-REST-API">REST Management interfaces</link>
- and <link linkend="Java-Broker-Management-Channel-Web-Console">Web Management Console</link>.
- </para>
-
- <para>The following ACL Provider managing operations are available from Web Management Console:
- <itemizedlist>
- <listitem><para>A new ACL Provider can be added by clicking onto "Add Access Control Provider" on the Broker tab.</para></listitem>
- <listitem><para>An ACL Provider details can be viewed on the Access Control Provider tab.
- The tab is shown after clicking onto ACL Provider name in the Broker object tree or after clicking
- onto ACL Provider row in ACL Providers grid on the Broker tab.</para></listitem>
- <listitem><para>An existing ACL Provider can be deleted by clicking onto buttons "Delete Access Control Provider"
- on the Broker tab or Access Control Provider tab.</para></listitem>
- </itemizedlist>
- </para>
-
- <section role="h3" xml: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 implicit 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>
- <note>
- <para>
- Some rules can be restricted to the virtual host if property virtualhost_name is specified.
- <example>
- <title>Restrict rules to specific virtual hosts</title>
- <programlisting>
- ACL ALLOW bob CREATE QUEUE virtualhost_name="test"
- ACL ALLOW bob ALL EXCHANGE virtualhost_name="prod"
- </programlisting>
- </example>
- In the example above the first rule allows user "bob" to create queues on virtual host "test" only.
- The second rule allows user "bob" any action with exchanges on virtual host "prod".
- </para>
- </note>
- </section>
-
- <section role="h4" xml:id="Java-Broker-Security-ACLs-Syntax">
- <title>
- Syntax
- </title>
-
- <para>
- ACL rules follow this syntax:
- </para>
- <programlisting>
- ACL {permission} {<group-name>|<user-name>|ALL} {action|ALL} [object|ALL] [property="<property-value>"]
- </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 xml: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 xml:id="table-Java-Broker-Security-ACLs-Syntax_actions">
- <title>List of ACL actions</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry><para>Action</para></entry>
- <entry><para>Description</para></entry>
- <entry><para>Supported object types</para></entry>
- <entry><para>Supported properties</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> <command>CONSUME</command> </entry>
- <entry> <para> Applied when subscriptions are created </para> </entry>
- <entry><para>QUEUE</para></entry>
- <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
- </row>
- <row>
- <entry> <command>PUBLISH</command> </entry>
- <entry> <para> Applied on a per message basis on publish message transfers</para> </entry>
- <entry><para>EXCHANGE</para></entry>
- <entry><para>name, routingkey, virtualhost_name</para></entry>
- </row>
- <row>
- <entry> <command>CREATE</command> </entry>
- <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry>
- <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
- <entry><para>see properties on the corresponding object type</para></entry>
- </row>
- <row>
- <entry> <command>ACCESS</command> </entry>
- <entry> <para> Applied when an object is read or accessed</para> </entry>
- <entry><para>VIRTUALHOST, MANAGEMENT</para></entry>
- <entry><para>name (for VIRTUALHOST only)</para></entry>
- </row>
- <row>
- <entry> <command>BIND</command> </entry>
- <entry> <para> Applied when queues are bound to exchanges</para> </entry>
- <entry><para>EXCHANGE</para></entry>
- <entry><para>name, routingKey, queuename, virtualhost_name, temporary, durable</para></entry>
- </row>
- <row>
- <entry> <command>UNBIND</command> </entry>
- <entry> <para> Applied when queues are unbound from exchanges</para> </entry>
- <entry><para>EXCHANGE</para></entry>
- <entry><para>name, routingKey, queuename, virtualhost_name, temporary, durable</para></entry>
- </row>
- <row>
- <entry> <command>DELETE</command> </entry>
- <entry> <para> Applied when objects are deleted </para> </entry>
- <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
- <entry><para>see properties on the corresponding object type</para></entry>
- </row>
- <row>
- <entry> <command>PURGE</command> </entry> <entry>
- <para>Applied when purge the contents of a queue</para> </entry>
- <entry><para>QUEUE</para></entry>
- <entry><para> </para></entry>
- </row>
- <row>
- <entry> <command>UPDATE</command> </entry>
- <entry> <para> Applied when an object is updated </para> </entry>
- <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
- <entry><para>see EXCHANGE and QUEUE properties</para></entry>
- </row>
- <row>
- <entry> <command>CONFIGURE</command> </entry>
- <entry> <para> Applied when an object is configured via REST management interfaces.</para> </entry>
- <entry><para>BROKER</para></entry>
- <entry><para> </para></entry>
- </row>
- <row>
- <entry><command>ACCESS_LOGS</command> </entry>
- <entry><para>Allows/denies the specific user to download log file(s) over REST interfaces.</para> </entry>
- <entry><para>BROKER, VIRTUALHOST</para></entry>
- <entry><para>name (for VIRTUALHOST only)</para></entry>
- </row>
- <row>
- <entry><command>SHUTDOWN</command> </entry>
- <entry><para>Allows/denies the specific user to shutdown the Broker.</para> </entry>
- <entry><para>BROKER</para></entry>
- <entry><para/></entry>
- </row>
- <row>
- <entry><command>INVOKE</command> </entry>
- <entry><para>Allows/denies the specific user to invoke the named operation.</para> </entry>
- <entry><para>BROKER, VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
- <entry><para>method_name, name and virtualhost_name</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table xml:id="table-Java-Broker-Security-ACLs-Syntax_objects">
- <title>List of ACL objects</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry><para>Object type</para></entry>
- <entry><para>Description</para></entry>
- <entry><para>Supported actions</para></entry>
- <entry><para>Supported properties</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> <command>VIRTUALHOSTNODE</command> </entry>
- <entry> <para>A virtualhostnode or remote replication node</para> </entry>
- <entry><para>ALL, CREATE, UPDATE, DELETE, INVOKE</para> </entry>
- <entry><para>name</para> </entry>
- </row>
- <row>
- <entry> <command>VIRTUALHOST</command> </entry>
- <entry> <para>A virtualhost</para> </entry>
- <entry><para>ALL, CREATE, UPDATE, DELETE, ACCESS, ACCESS_LOGS, INVOKE</para> </entry>
- <entry><para>name</para> </entry>
- </row>
- <row>
- <entry> <command>QUEUE</command> </entry>
- <entry> <para>A queue </para> </entry>
- <entry><para>ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE, INVOKE</para></entry>
- <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
- </row>
- <row>
- <entry> <command>EXCHANGE</command> </entry>
- <entry><para>An exchange</para></entry>
- <entry><para>ALL, ACCESS, CREATE, DELETE, BIND, UNBIND, PUBLISH, UPDATE, INVOKE</para></entry>
- <entry><para>name, autodelete, temporary, durable, type, virtualhost_name, queuename(only for BIND and UNBIND), routingkey(only for BIND and UNBIND, PUBLISH)</para></entry>
- </row>
- <row>
- <entry> <command>USER</command> </entry>
- <entry> <para>A user</para> </entry>
- <entry><para>ALL, CREATE, DELETE, UPDATE, INVOKE</para></entry>
- <entry><para>name</para></entry>
- </row>
- <row>
- <entry> <command>GROUP</command> </entry>
- <entry> <para>A group</para> </entry>
- <entry><para>ALL, CREATE, DELETE, UPDATE, INVOKE</para></entry>
- <entry><para>name</para></entry>
- </row>
- <row>
- <entry> <command>BROKER</command> </entry>
- <entry> <para>The broker</para> </entry>
- <entry><para>ALL, CONFIGURE, ACCESS_LOGS, INVOKE</para></entry>
- <entry><para> </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table xml: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 or exchange 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>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. component name</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4632">RFC 4632</link>)
- or wildcards (e.g. 192.169.1.*).
- </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html">Networking
- Properties</link> 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>
- </entry>
- </row>
- <row>
- <entry><command>virtualhost_name</command></entry>
- <entry>
- <para>
- String. A name of virtual host to which the rule is applied.
- </para>
- </entry>
- </row>
- <row>
- <entry><command>method_name</command></entry>
- <entry>
- <para>
- String. The name of the method. Used with INVOKE ACL action.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <section role="h4" xml: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 Broker provides a complete example ACL file, located at etc/broker_example.acl.
- </para>
- <section role="h4" xml: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 (logged) 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" xml: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 maintenance This example illustrates the permissioning of an individual component.
- </para>
- <programlisting>
-# Give usermaint access to management and permission to create
-# and delete users through management
-ACL ALLOW usermaint ALL USER
-ACL ALLOW usermaint ALL GROUP
-ACL DENY ALL ALL USER
-ACL DENY ALL ALL GROUP
-...
-... rules for other users
-...
-ACL DENY-LOG ALL ALL
- </programlisting>
- </section>
- <section role="h4" xml: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" xml: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 role="h4" xml:id="Java-Broker-Security-ACLs-WorkedExample5">
- <title>
- Worked example 5 - REST management ACL example for queue operator
- </title>
- <para>
- This example illustrates how to set up an ACL that restricts usage of REST management interfaces.
- </para>
- <programlisting>
-# allow to the users from operators group to do the following
- access virtualhost "default"
- create, delete, update and invoke any method on queues
- invoke any method "getStatistics" on virtaul host
-
-ACL ALLOW-LOG operators ACCESS MANAGEMENT
-ACL ALLOW-LOG operators ALL QUEUE
-ACL ALLOW-LOG operators INVOKE VIRTUALHOST method_name="getStatistics"
-
-ACL DENY-LOG all all
- </programlisting>
- </section>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/security/Java-Broker-Security-AccessControlProviders.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/security/Java-Broker-Security-AccessControlProviders.xml b/doc/java-broker/src/docbkx/security/Java-Broker-Security-AccessControlProviders.xml
new file mode 100644
index 0000000..d5b4ce1
--- /dev/null
+++ b/doc/java-broker/src/docbkx/security/Java-Broker-Security-AccessControlProviders.xml
@@ -0,0 +1,564 @@
+<?xml version="1.0"?>
+<!--
+
+ 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Security-AccessControlProviders">
+ <title>Access Control Providers</title>
+ <para>
+ The Access Control Provider governs the actions that a user may perform.
+ </para>
+ <para>There are two points within the hierarchy that enforce access control: the Broker itself and at each Virtual
+ Host. When an access decision needs to be made, the nearest control point configure with a provider is consulted
+ for a decision. The example, when making a decision about the ability to say, consume from, a Queue, if the
+ Virtual Host is configured with Access Control Provider it is consulted. Unless a decision is made, the decision
+ is delegated to the Access Control Provider configured at the Broker.
+ </para>
+ <para>Access Control Providers are configured with a list of ACL rules. The rules determine to which object
+ the user has access and what actions the user may perform on those objects. Rules are ordered and are considered
+ top to bottom. The first matching rule makes the access decision.
+ </para>
+ <para>
+ ACL rules may be written in terms of group names. A rule written in terms of a group name applies to the user if
+ he is a member of that group. Groups information is obtained from the
+ <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Providers</link>
+ and
+ <link linkend="Java-Broker-Security-Group-Providers">Group Providers</link>. Writing ACL in terms of groups is
+ recommended.
+ </para>
+ <para>
+ The Access Control Providers can be configured using
+ <link linkend="Java-Broker-Management-Channel-REST-API">REST Management interfaces</link>
+ and <link linkend="Java-Broker-Management-Channel-Web-Console">Web Management Console</link>.
+ </para>
+ <section role="h3" xml:id="Java-Broker-Security-AccessControlProviders-Types">
+ <title>Types</title>
+ <para>There are currently two types of Access Control Provider implementing ACL rules.
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>RulesBased</emphasis> - a provider that stores the rules-set within
+ the Broker's or VirtualHost's configuration. When used with HA, the Virtualhost
+ rules automatically apply to all nodes participating within the HA group.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <para><emphasis>ACLFile</emphasis> - an older provider that references an externally provided
+ ACL file (or data url). This provider is deprecated.</para>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section role="h3" xml:id="Java-Broker-Security-AccessControlProviders-ACLRules">
+ <title>
+ ACL Rules
+ </title>
+ <para>
+ An ACL rule-set is an ordered list of ACL rules.</para>
+ <para>An ACL rule comrprises matching criteria that determine if a rule will fire for a given action and a decision
+ outcome. If the rule matches the rule makes an access decision outcome. Decision outcomes are final: no regard is given
+ to rules that appear later once a decision is made.
+ </para>
+ <para>Matching criteria is composed of an ACL object type (e.g. QUEUE), an ACL action (e.g. UPDATE) and other
+ properties that further refine if a match is made. These properties restrict the match based on criteria such
+ as name or IP address.
+ </para>
+ <para>Let's look at some examples.</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>
+ As dicussed, ACL rule-set is considered in 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 action
+ 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>
+ If a rule-set fails to make a decision, the result is configurable. By default, the RulesBased provider defers
+ the decision allowing another provider further up the hierarchy to make a decision (i.e. allowing the VirtualHost
+ control point to delegate to the Broker). In the case of the ACLFile provider, by default, its rule-sets implicit
+ have a rule denying all operations to all users. It is as if the rule-set ends with
+ <literal>ACL DENY ALL ALL</literal>. If no access control provider makes a decision the default is to
+ deny the action.
+ </para>
+ <para>
+ When writing a new ACL, a useful approach is to begin with an rule-set containing only
+ <programlisting>ACL DENY-LOG ALL ALL</programlisting> at the Broker control point which will cause the Broker to
+ deny all operations with details of the denial logged. 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.
+ </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 abstractions and apply them consistently across the whole system.
+ </para>
+ </section>
+ <section role="h4" xml:id="Java-Broker-Security-AccessControlProviders-Syntax">
+ <title>
+ Syntax
+ </title>
+
+ <para>
+ ACL rules follow this syntax:
+ </para>
+ <programlisting>
+ ACL {permission} {<group-name>|<user-name>|ALL} {action|ALL} [object|ALL] [property="<property-value>"]
+ </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 xml:id="table-Java-Broker-Security-AccessControlProviders-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 xml:id="table-Java-Broker-Security-AccessControlProviders-Syntax_actions">
+ <title>List of ACL actions</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry><para>Action</para></entry>
+ <entry><para>Description</para></entry>
+ <entry><para>Supported object types</para></entry>
+ <entry><para>Supported properties</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry> <command>CONSUME</command> </entry>
+ <entry> <para> Applied when subscriptions are created </para> </entry>
+ <entry><para>QUEUE</para></entry>
+ <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
+ </row>
+ <row>
+ <entry> <command>PUBLISH</command> </entry>
+ <entry> <para> Applied on a per message basis on publish message transfers</para> </entry>
+ <entry><para>EXCHANGE</para></entry>
+ <entry><para>name, routingkey, virtualhost_name</para></entry>
+ </row>
+ <row>
+ <entry> <command>CREATE</command> </entry>
+ <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry>
+ <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
+ <entry><para>see properties on the corresponding object type</para></entry>
+ </row>
+ <row>
+ <entry> <command>ACCESS</command> </entry>
+ <entry> <para> Applied when a connection is made for messaging or management</para> </entry>
+ <entry><para>VIRTUALHOST, MANAGEMENT</para></entry>
+ <entry><para>name (for VIRTUALHOST only)</para></entry>
+ </row>
+ <row>
+ <entry> <command>BIND</command> </entry>
+ <entry> <para> Applied when queues are bound to exchanges</para> </entry>
+ <entry><para>EXCHANGE</para></entry>
+ <entry><para>name, routingKey, queue_name, virtualhost_name, temporary, durable</para></entry>
+ </row>
+ <row>
+ <entry> <command>UNBIND</command> </entry>
+ <entry> <para> Applied when queues are unbound from exchanges</para> </entry>
+ <entry><para>EXCHANGE</para></entry>
+ <entry><para>name, routingKey, queue_name, virtualhost_name, temporary, durable</para></entry>
+ </row>
+ <row>
+ <entry> <command>DELETE</command> </entry>
+ <entry> <para> Applied when objects are deleted </para> </entry>
+ <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
+ <entry><para>see properties on the corresponding object type</para></entry>
+ </row>
+ <row>
+ <entry> <command>PURGE</command> </entry> <entry>
+ <para>Applied when the contents of a queue is purged</para> </entry>
+ <entry><para>QUEUE</para></entry>
+ <entry><para> </para></entry>
+ </row>
+ <row>
+ <entry> <command>UPDATE</command> </entry>
+ <entry> <para> Applied when an object is updated </para> </entry>
+ <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
+ <entry><para>see EXCHANGE and QUEUE properties</para></entry>
+ </row>
+ <row>
+ <entry> <command>CONFIGURE</command> </entry>
+ <entry> <para> Applied when a Broker/Port/Authentication Provider/Access Control Provider/BrokerLogger is created/update/deleted.</para> </entry>
+ <entry><para>BROKER</para></entry>
+ <entry><para> </para></entry>
+ </row>
+ <row>
+ <entry><command>ACCESS_LOGS</command> </entry>
+ <entry><para>Allows/denies the specific user to download log file(s).</para> </entry>
+ <entry><para>BROKER, VIRTUALHOST</para></entry>
+ <entry><para>name (for VIRTUALHOST only)</para></entry>
+ </row>
+ <row>
+ <entry><command>SHUTDOWN</command> </entry>
+ <entry><para>Allows/denies the specific user to shutdown the Broker.</para> </entry>
+ <entry><para>BROKER</para></entry>
+ <entry><para/></entry>
+ </row>
+ <row>
+ <entry><command>INVOKE</command> </entry>
+ <entry><para>Allows/denies the specific user to invoke the named operation.</para> </entry>
+ <entry><para>BROKER, VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry>
+ <entry><para>method_name, name and virtualhost_name</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table xml:id="table-Java-Broker-Security-AccessControlProviders-Syntax_objects">
+ <title>List of ACL objects</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry><para>Object type</para></entry>
+ <entry><para>Description</para></entry>
+ <entry><para>Supported actions</para></entry>
+ <entry><para>Supported properties</para></entry>
+ <entry><para>Allowed in Virtualhost ACLs?</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry> <command>VIRTUALHOSTNODE</command> </entry>
+ <entry> <para>A virtualhostnode or remote replication node</para> </entry>
+ <entry><para>ALL, CREATE, UPDATE, DELETE, INVOKE</para> </entry>
+ <entry><para>name</para> </entry>
+ <entry><para>No</para> </entry>
+ </row>
+ <row>
+ <entry> <command>VIRTUALHOST</command> </entry>
+ <entry> <para>A virtualhost</para> </entry>
+ <entry><para>ALL, CREATE, UPDATE, DELETE, ACCESS, ACCESS_LOGS, INVOKE</para> </entry>
+ <entry><para>name</para> </entry>
+ <entry><para>No</para> </entry>
+ </row>
+ <row>
+ <entry> <command>QUEUE</command> </entry>
+ <entry> <para>A queue </para> </entry>
+ <entry><para>ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE, INVOKE</para></entry>
+ <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
+ <entry><para>Yes</para> </entry>
+ </row>
+ <row>
+ <entry> <command>EXCHANGE</command> </entry>
+ <entry><para>An exchange</para></entry>
+ <entry><para>ALL, ACCESS, CREATE, DELETE, BIND, UNBIND, PUBLISH, UPDATE, INVOKE</para></entry>
+ <entry><para>name, autodelete, temporary, durable, type, virtualhost_name, queue_name(only for BIND and UNBIND), routingkey(only for BIND and UNBIND, PUBLISH)</para></entry>
+ <entry><para>Yes</para> </entry>
+ </row>
+ <row>
+ <entry> <command>USER</command> </entry>
+ <entry> <para>A user</para> </entry>
+ <entry><para>ALL, CREATE, DELETE, UPDATE, INVOKE</para></entry>
+ <entry><para>name</para></entry>
+ <entry><para>No</para> </entry>
+ </row>
+ <row>
+ <entry> <command>GROUP</command> </entry>
+ <entry> <para>A group</para> </entry>
+ <entry><para>ALL, CREATE, DELETE, UPDATE, INVOKE</para></entry>
+ <entry><para>name</para></entry>
+ <entry><para>No</para> </entry>
+ </row>
+ <row>
+ <entry> <command>BROKER</command> </entry>
+ <entry> <para>The broker</para> </entry>
+ <entry><para>ALL, CONFIGURE, ACCESS_LOGS, INVOKE</para></entry>
+ <entry><para/></entry>
+ <entry><para>No</para> </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table xml:id="table-Java-Broker-Security-AccessControlProviders-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 or exchange 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>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, or fanout</para> </entry>
+ </row>
+ <row>
+ <entry> <command>alternate</command> </entry>
+ <entry> <para> String. Name of the alternate exchange </para> </entry>
+ </row>
+ <row>
+ <entry> <command>queue_name</command> </entry>
+ <entry> <para> String. Name of the queue (used only when the object is EXCHANGE for BIND and UNBIND actions)</para> </entry>
+ </row>
+ <row>
+ <entry> <command>component</command> </entry>
+ <entry> <para> String. component name</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4632">RFC 4632</link>)
+ or wildcards (e.g. 192.169.1.*).
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html">Networking
+ Properties</link> 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>
+ </entry>
+ </row>
+ <row>
+ <entry><command>virtualhost_name</command></entry>
+ <entry>
+ <para>
+ String. A name of virtual host to which the rule is applied.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><command>method_name</command></entry>
+ <entry>
+ <para>
+ String. The name of the method. A trailing wildcard (*) is permitted. Used with INVOKE ACL action.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><command>attribute_names</command></entry>
+ <entry>
+ <para>
+ Specifies attribute name criteria. Used by UPDATE ACL actions only. Rules with this criteria will match
+ if and only if the set of attributes being updated Comma separated list of attribute names . This criteria
+ will match if all attributes included within the update appear in the set described by
+ <literal>attribute_names</literal>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section role="h4" xml:id="Java-Broker-Security-AccessControlProviders-WorkedExamples">
+ <title>
+ Worked Examples
+ </title>
+ <para>
+ Here are some example ACLs illustrating common use cases.
+ </para>
+ <section role="h4" xml:id="Java-Broker-Security-AccessControlProviders-WorkedExample1">
+ <title>
+ Worked example 1 - Management rights
+ </title>
+ <para>
+ Suppose you wish to permission two users: a user <literal>operator</literal> must be able to perform all
+ Management operations, and a user 'readonly' must be enable to perform only read-only actions. Neither
+ <literal>operator</literal> nor <literal>readonly</literal> should be allowed to connect clients for
+ messaging.
+ </para>
+ <example>
+ <title>Worked example 1 - Management rights</title>
+ <programlisting><![CDATA[
+ # Deny operator/readonly permission to connect for messaging.
+ ACL DENY-LOG operator ACCESS VIRTUALHOST
+ ACL DENY-LOG readonly ACCESS VIRTUALHOST
+ # Give operator permission to perfom all actions
+ ACL ALLOW operator ALL ALL
+ # Give readonly access permission to virtualhost. (Read permission for all objects implicit)
+ ACL ALLOW readonly ACCESS MANAGEMENT
+ ...
+ ... rules for other users
+ ...]]>
+ </programlisting>
+
+ </example>
+ </section>
+ <section role="h4" xml:id="Java-Broker-Security-AccessControlProviders-WorkedExample2">
+ <title>
+ Worked example 2 - Simple Messaging
+ </title>
+ <para>
+ Suppose you wish to permission a system for application messaging. User <literal>publisher</literal>
+ needs permission to publish to <literal>appqueue</literal> and consumer needs permission to consume
+ from the same queue object. We also want <literal>operator</literal> to be able to inspect messages
+ and delete messages in case of the need to intervene. This example assumes that the queue exists on
+ the Broker.
+ </para>
+ <para>
+ We use this ACL to illustrate separate Broker and Virtualhost access control providers.
+ </para>
+ <para>
+ The following ACL rules are given to the Broker.
+ </para>
+ <example>
+ <title>Worked example 2 - Simple Messaging - Broker ACL rules</title>
+ <programlisting><![CDATA[
+# This gives the operate permission to delete messages on all queues on all virtualhost
+ACL ALLOW operator ACCESS MANAGEMENT
+ACL ALLOW operator INVOKE QUEUE method_name="deleteMessages"
+ACL ALLOW operator INVOKE QUEUE method_name="getMessage*"]]>
+ </programlisting>
+ </example>
+ <para>
+ And the following ACL rule-set is applied to the Virtualhost. The default outcome of the
+ Access Control Provider must be <literal>DEFERED</literal>.
+ </para>
+ <example>
+ <title>Worked example 2 - Simple Messaging - Virtualhost ACL rules</title>
+ <programlisting><![CDATA[
+# Allow client and server to connect to the virtual host.
+ACL ALLOW publisher ACCESS VIRTUALHOST
+ACL ALLOW consumer ACCESS VIRTUALHOST
+
+ACL ALLOW publisher PUBLISH EXCHANGE name="" routingKey="appqueue"
+ACL ALLOW consumer CONSUME QUEUE name="appqueue"
+# In some addressing configurations, the Qpid JMS AMQP 0-x client, will declare the queue as a side effect of creating the consumer.
+# The following line allows for this. For the Qpid JMS AMQP 1.0 client, this is not required.
+ACL ALLOW consumer CREATE QUEUE name="appqueue"]]>
+ </programlisting>
+ </example>
+ </section>
+ <section role="h4" xml:id="Java-Broker-Security-AccessControlProviders-WorkedExample3">
+ <title>
+ Worked example 3 - 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>
+ <example>
+ <title>Worked example 3 - firewall-like access control</title>
+ <programlisting><![CDATA[
+ ################
+ # 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.*"]]>
+ </programlisting>
+ </example>
+ </section>
+ </section>
+</section>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-External.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-External.xml b/doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-External.xml
index fc17044..19463e2 100644
--- a/doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-External.xml
+++ b/doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-External.xml
@@ -40,6 +40,6 @@
be configured. If attribute "Use the full DN as the Username" is set to "true" the full DN is
used as an authenticated principal name. If attribute "Use the full DN as the Username" is set
to "false" the user name CN part is used as the authenticated principal name. Setting the
- field to "false" is particular useful when <link linkend="Java-Broker-Security-ACLs">ACL</link> is required, as at the moment, ACL does not support commas in the user name.
+ field to "false" is particular useful when <link linkend="Java-Broker-Security-AccessControlProviders">ACL</link> is required, as at the moment, ACL does not support commas in the user name.
</para>
</section>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/f61b8b90/doc/java-broker/src/docbkx/security/Java-Broker-Security-Group-Providers.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/security/Java-Broker-Security-Group-Providers.xml b/doc/java-broker/src/docbkx/security/Java-Broker-Security-Group-Providers.xml
index 09c3653..5fc9731 100644
--- a/doc/java-broker/src/docbkx/security/Java-Broker-Security-Group-Providers.xml
+++ b/doc/java-broker/src/docbkx/security/Java-Broker-Security-Group-Providers.xml
@@ -23,7 +23,7 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Security-Group-Providers">
<title>Group Providers</title>
<para>
- The Apache Qpid Broker for Java utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-ACLs">ACLs</link>.
+ The Apache Qpid Broker for Java utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-AccessControlProviders">ACLs</link>.
Following authentication by a given <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link>,
the configured Group Providers are consulted allowing the assignment of GroupPrincipals for a given authenticated user. Any number of
Group Providers can be added into the Broker. All of them will be checked for the presence of the groups for a given authenticated user.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org