diff options
| author | Keith Wall <kwall@apache.org> | 2014-10-30 23:37:03 +0000 |
|---|---|---|
| committer | Keith Wall <kwall@apache.org> | 2014-10-30 23:37:03 +0000 |
| commit | 24d10be23d2368868c56e0053030972e6b15e275 (patch) | |
| tree | 297cb75a42e905c4ba1ba3599517e7961b74aa69 /qpid/doc/book/src/java-broker/security | |
| parent | d67392a88b4889247ff60e2773055cc41981ade7 (diff) | |
| download | qpid-python-24d10be23d2368868c56e0053030972e6b15e275.tar.gz | |
QPID-6108: [Java Documentation] Refactor security/auth providers section into separate files to allow for convenient re-purposing of the document
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1635639 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/doc/book/src/java-broker/security')
14 files changed, 1296 insertions, 0 deletions
diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-ACLs.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-ACLs.xml new file mode 100644 index 0000000000..95d718df29 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-ACLs.xml @@ -0,0 +1,646 @@ +<?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, 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" 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" 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 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="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, immediate, 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 to the specific user an operation to download broker log file(s) over REST interfaces</para> </entry> + <entry><para>BROKER</para></entry> + <entry><para> </para></entry> + </row> + </tbody> + </tgroup> + </table> + <table 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</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</para> </entry> + <entry><para>name</para> </entry> + </row> + <row> + <entry> <command>MANAGEMENT </command> </entry> + <entry> <para>Management - for web and JMX</para> </entry> + <entry><para>ALL, ACCESS</para> </entry> + <entry><para> </para></entry> + </row> + <row> + <entry> <command>QUEUE</command> </entry> + <entry> <para>A queue </para> </entry> + <entry><para>ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE</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</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</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</para></entry> + <entry><para>name</para></entry> + </row> + <row> + <entry> <command>METHOD</command> </entry> + <entry> <para>Management or agent or broker method</para> </entry> + <entry><para>ALL, ACCESS, UPDATE</para></entry> + <entry><para>name, component, virtualhost_name</para></entry> + </row> + <row> + <entry> <command>BROKER</command> </entry> + <entry> <para>The broker</para> </entry> + <entry><para>ALL, CONFIGURE, ACCESS_LOGS</para></entry> + <entry><para> </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>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</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> + </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> + </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>immediate</command></entry> + <entry> + <para> + Boolean. A property can be used to restrict PUBLISH action to publishing only messages with given immediate flag. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <table id="table-Java-Broker-Security-ACLs-Syntax_javacomponents"> + <title>List of ACL JMX Components</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> <command>UserManagement</command> </entry> + <entry> <para>User maintenance; create/delete/view users, change passwords etc</para> </entry> + </row> + <row> + <entry> <command>ConfigurationManagement</command> </entry> + <entry> <para>Dynamically reload configuration from disk.</para> </entry> + </row> + <row> + <entry> <command>LoggingManagement</command> </entry> + <entry> <para>Dynamically control Qpid logging level</para> </entry> + </row> + <row> + <entry> <command>ServerInformation</command> </entry> + <entry> <para>Read-only information regarding the Qpid: version number etc</para> </entry> + </row> + <row> + <entry> <command>VirtualHost.Queue</command> </entry> + <entry> <para>Queue maintenance; 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 maintenace; 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 maintenance 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 role="h4" id="Java-Broker-Security-ACLs-WorkedExample5"> + <title> + Worked example 5 - REST management ACL example + </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 webadmins group to change broker model +# this rule allows adding/removing/editing of Broker level objects: +# Broker, Group Provider, Authentication Provider, Port, Access Control Provider etc +ACL ALLOW-LOG webadmins CONFIGURE BROKER + +# allow to the users from webadmins group to perform +# create/update/delete on virtualhost node and children +ACL ALLOW-LOG webadmins CREATE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins UPDATE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins DELETE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins CREATE VIRTUALHOST +ACL ALLOW-LOG webadmins UPDATE VIRTUALHOST +ACL ALLOW-LOG webadmins DELETE VIRTUALHOST +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 + +# allow to the users from webadmins group to create/update/delete groups on Group Providers +ACL ALLOW-LOG webadmins CREATE GROUP +ACL ALLOW-LOG webadmins DELETE GROUP +ACL ALLOW-LOG webadmins UPDATE GROUP + +# allow to the users from webadmins group to create/update/delete users for Authentication Providers +ACL ALLOW-LOG webadmins CREATE USER +ACL ALLOW-LOG webadmins DELETE USER +ACL ALLOW-LOG webadmins UPDATE USER + +# allow to the users from webadmins group to move, copy, delete messagaes, and clear the queue +# using REST management interfaces +ACL ALLOW-LOG webadmins UPDATE METHOD + +# 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" + +ACL DENY-LOG all all + </programlisting> + </section> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Anonymous.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Anonymous.xml new file mode 100644 index 0000000000..9c727ebc78 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Anonymous.xml @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-Anonymous-Provider"> + <title>Anonymous</title> + + <para> The Anonymous Authentication Provider will allow users to connect with or without + credentials and result in their identification on the broker as the user ANONYMOUS. This + Provider does not require specification of any additional attributes on creation. </para> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Base64MD5PasswordFile.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Base64MD5PasswordFile.xml new file mode 100644 index 0000000000..14319c68eb --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Base64MD5PasswordFile.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-Base64MD5PasswordFile-Provider"> + <title>Base64MD5 Password File <emphasis>(Deprecated)</emphasis></title> + <para><emphasis>This provider is deprecated and will be removed in a future release. The + <link linkend="Java-Broker-Security-MD5-Provider">MD5</link> provider should be used + instead.</emphasis></para> + <para> Base64MD5PasswordFile Provider uses local file to store and manage user credentials + similar to PlainPasswordFile but instead of storing a password the MD5 password digest encoded + with Base64 encoding is stored in the file. When creating an authentication provider the path + to the file needs to be specified. If specified file does not exist an empty file is created + automatically on Authentication Provider creation. On Base64MD5PasswordFile Provider deletion + the password file is deleted as well.</para> + <para>For this provider user credentials can be added, removed or changed using + Management.</para> + <section> + <title>Base64MD5 File Format</title> + <para> The user credentials are stored on the single file line as user name and user password + pairs separated by colon character. The password is stored MD5 digest/Base64 encoded. This + file must not be modified externally whilst the Broker is running.</para> + </section> +</section>
\ No newline at end of file diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-External.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-External.xml new file mode 100644 index 0000000000..70f0d199ba --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-External.xml @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-External-Provider"> + <title>External (SSL Client Certificates)</title> + + <para> When <link linkend="Java-Broker-Management-Managing-Truststores"> requiring SSL Client + Certificates</link> be presented the External Authentication Provider can be used, such that + the user is authenticated based on trust of their certificate alone, and the X500Principal + from the SSL session is then used as the username for the connection, instead of also + requiring the user to present a valid username and password. </para> + + <para> + <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically + only be used on the AMQP/HTTP ports, in conjunction with <link + linkend="Java-Broker-Management-Managing-Ports">SSL client certificate + authentication</link>. It is not intended for other uses such as the JMX management port and + will treat any non-sasl authentication processes on these ports as successful with the given + username. As such you should configure another Authentication Provider for use on JMX + ports.</para> + + <para>On creation of External Provider the use of full DN or username CN as a principal name can + 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. + </para> +</section> + diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Kerberos.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Kerberos.xml new file mode 100644 index 0000000000..fbac55f2e2 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Kerberos.xml @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-Kerberos-Provider"> + <title>Kerberos</title> + + <para> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the + connections. </para> + + <para> Configuration of kerberos is done through system properties (there doesn't seem to be a + way around this unfortunately). </para> + + <programlisting> + export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf + ${QPID_HOME}/bin/qpid-server + </programlisting> + + <para>Where qpid.conf would look something like this:</para> + + <programlisting><![CDATA[ +com.sun.security.jgss.accept { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + storeKey=true + doNotPrompt=true + realm="EXAMPLE.COM" + useSubjectCredsOnly=false + kdc="kerberos.example.com" + keyTab="/path/to/keytab-file" + principal="<name>/<host>"; +};]]></programlisting> + + <para> Where realm, kdc, keyTab and principal should obviously be set correctly for the + environment where you are running (see the existing documentation for the C++ broker about + creating a keytab file). </para> + + <para> Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength + Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working. </para> + + <para> Since Kerberos support only works where SASL authentication is available (e.g. not for + JMX authentication) you may wish to also include an alternative Authentication Provider + configuration, and use this for JMX and HTTP ports. </para> + +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml new file mode 100644 index 0000000000..81b36f4692 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml @@ -0,0 +1,99 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ +<!ENTITY % entities SYSTEM "../commonEntities.xml"> +%entities; +]> +<!-- + + 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-LDAP-Provider"> + <title>Simple LDAP</title> + + <para> The Simple LDAP authenticates connections against a Directory (LDAP). </para> + <para> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: <itemizedlist> + <listitem> + <para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example, + <literal>ldaps://example.com:636</literal></para> + </listitem> + <listitem> + <para><emphasis>Search context</emphasis> is the distinguished name of the search base + object. It defines the location from which the search for users begins, for example, + <literal>dc=users,dc=example,dc=com</literal></para> + </listitem> + <listitem> + <para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by + provided user name, for example, <literal>(uid={0})</literal></para> + </listitem> + </itemizedlist> Additionally, the following optional fields can be specified: <itemizedlist> + <listitem> + <para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the + JNDI LDAP context factory. This class must implement the <ulink + url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html" + >InitialContextFactory</ulink> interface and produce instances of <ulink + url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. If + not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is + used.</para> + </listitem> + <listitem> + <para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for + performing "ldap bind". If not specified, the <emphasis>LDAP server URL</emphasis> will + be used for both searches and authentications.</para> + </listitem> + <listitem> + <para><emphasis>Truststore name</emphasis> is a name of <link + linkend="Java-Broker-Management-Managing-Truststores-Attributes">configured + truststore</link>. Use this if connecting to a Directory over SSL (i.e. ldaps://) + which is protected by a certificate signed by a private CA (or utilising a self-signed + certificate).</para> + </listitem> + </itemizedlist> + </para> + + <important> + <para>In order to protect the security of the user's password, when using LDAP authentication, + you must: </para> + <itemizedlist> + <listitem> + <para>Use SSL on the broker's AMQP, HTTP and JMX ports to protect the password during + transmission to the Broker. The Broker enforces this restriction automatically on AMQP + and HTTP ports.</para> + </listitem> + <listitem> + <para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password + during transmission from the Broker to the Directory.</para> + </listitem> + </itemizedlist> + </important> + + <para> The LDAP Authentication Provider works in the following manner. If not in <literal>bind + without search</literal> mode, it first connects to the Directory and searches for the ldap + entity which is identified by the username. The search begins at the distinguished name + identified by <literal>Search Context</literal> and uses the username as a filter. The search + scope is sub-tree meaning the search will include the base object and the subtree extending + beneath it. </para> + + <para> If the search returns a match, or is configured in <literal>bind without search</literal> + mode, the Authentication Provider then attempts to bind to the LDAP server with the given name + and the password. Note that <ulink + url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security + authentication</ulink> is used so the Directory receives the password in the clear. </para> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5.xml new file mode 100644 index 0000000000..04d8e2e84d --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5.xml @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-MD5-Provider"> + <title>MD5 Provider</title> + + <para> MD5 Provider uses the Broker configuration itself to store the database of + users (unlike the <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider" + >Base64MD5 Password File</link>, there is no separate password file). Rather than store the + unencrypted user password (as the Plain provider does) it instead stores the MD5 password + digest. This can be further encrypted using the + facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption" + />.</para> + <para>For this provider user credentials can be added, removed or changed using + Management.</para> +</section>
\ No newline at end of file diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5PasswordFile.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5PasswordFile.xml new file mode 100644 index 0000000000..30190a4e60 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5PasswordFile.xml @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://docbook.org/xml/4.5/docbookx.dtd" +[ <!ENTITY % xinclude SYSTEM "internal/xinclude.mod"> +%xinclude; +]> +<book> + <bookinfo> + <title>Book with XInclude Template Title</title> + <author> + <firstname>Author First Name</firstname> + <surname>Author Last Name</surname> + </author> + </bookinfo> + <part> + <title>First Part </title> + <chapter> + <title>Chapter Title</title> + <sect1> + <title>Section1 Title</title> + <para>Text</para> + </sect1> + </chapter> + </part> +</book> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Plain.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Plain.xml new file mode 100644 index 0000000000..92b8685e93 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Plain.xml @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-Plain-Provider"> + <title>Plain</title> + <para>The Plain Provider uses the Broker configuration itself to store the database of users + (unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider" + >PlainPasswordFile</link>, there is no separate password file). As the name suggests, + the user data (including password) is not hashed in any way. In order to provide encryption, + the facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"/> + must be used.</para> + <para>For this provider user credentials can be added, removed or changed using + Management.</para> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-PlainPasswordFile.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-PlainPasswordFile.xml new file mode 100644 index 0000000000..8d4fa54a1c --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-PlainPasswordFile.xml @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-PlainPasswordFile-Provider"> + <title>Plain Password File <emphasis>(Deprecated)</emphasis></title> + <para><emphasis>This provider is deprecated and will be removed in a future release. The <link + linkend="Java-Broker-Security-Plain-Provider">Plain</link> provider should be used + instead.</emphasis></para> + <para> The PlainPasswordFile Provider uses local file to store and manage user credentials. When + creating an authentication provider the path to the file needs to be specified. If specified + file does not exist an empty file is created automatically on Authentication Provider + creation. On Provider deletion the password file is deleted as well.</para> + <para>For this provider user credentials can be added, removed or changed using + Management.</para> + + <section> + <title>Plain Password File Format</title> + <para> The user credentials are stored on the single file line as user name and user + password pairs separated by colon character. This file must not be modified externally + whilst the Broker is running.</para> + <programlisting> +# password file format +# <user name>: <user password> +guest:guest + </programlisting> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-ScramSha.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-ScramSha.xml new file mode 100644 index 0000000000..46d0269564 --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-ScramSha.xml @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-ScramSha-Providers"> + <title>SCRAM SHA</title> + <para>The SCRAM SHA Providers uses the Broker configuration itself to store the database of + users. The users' + passwords are stored as salted SHA digested password. This can be further encrypted using the + facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption" + />.</para> + <para>There are two variants of this provider, SHA1 and SHA256. SHA256 is recommended whenever + possible. SHA1 is provided with compatibility with clients utilising JDK 1.6 (which does not + support SHA256).</para> + <para>For these providers user credentials can be added, removed or changed using + Management.</para> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers.xml new file mode 100644 index 0000000000..b5546ffebf --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + 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-Authentication-Providers"> + <title>Authentication Providers</title> + + <para> In order to successfully establish a connection to the Java Broker, the connection must be + authenticated. The Java Broker supports a number of different authentication schemes, each with + its own "authentication provider". Any number of Authentication Providers can be configured on + the Broker at the same time. </para> + + <important> + <para> Only unused Authentication Provider can be deleted. For delete requests attempting to + delete Authentication Provider associated with the Ports, the errors will be returned and + delete operations will be aborted. It is possible to change the Authentication Provider on + Port at runtime. However, the Broker restart is required for changes on Port to take effect. + </para> + </important> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-LDAP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-Kerberos.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-External.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-Anonymous.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-ScramSha.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-Plain.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-PlainPasswordFile.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-MD5.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers-Base64MD5PasswordFile.xml"/> + </section> + diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml new file mode 100644 index 0000000000..2924f2859c --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml @@ -0,0 +1,74 @@ +<?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-Configuration-Encryption"> + <title>Configuration Encryption</title> + <para> The Broker is capable of encrypting passwords and other security items stored in the + Broker's configuration. This is means that items such as keystore/truststore passwords, JDBC + passwords, and LDAP passwords can be stored in the configure in a form that is difficult to + read.</para> + <para>The Broker ships with an encryptor implementation called <literal>AESKeyFile</literal>. This + uses a securely generated random key of 256bit<footnote><para>Java Cryptography Extension (JCE) + Unlimited Strength required</para></footnote> to encrypt the secrets stored within a key + file. Of course, the key itself must be guarded carefully, otherwise the passwords encrypted + with it may be compromised. For this reason, the Broker that the file's permissions allow the + file to be read exclusively by the user account used for running the Broker.</para> + <important> + <para>If the keyfile is lost or corrupted, the secrets will be irrecoverable.</para> + </important> + <section id="Java-Broker-Security-Configuration-Encryption-Configuration"> + <title>Configuration</title> + <para>To use <literal>AESKeyFile</literal>, first stop the Broker, then edit the Broker's + configuration file ${QPID_WORK}/config.json. Insert a Broker attribute called + <literal>confidentialConfigurationEncryptionProvider</literal> with value + <literal>AESKeyFile</literal>. On restarting the Broker, it will generate a keyfile in + location <literal>${QPID_WORK}/.keys/</literal>. Any existing passwords contained with the + configuration will be automatically encrypted, as will any new or changed ones in + future.</para> + <example> + <title>Enanbling password encryption</title> + <screen> + { + "id" : "3f183a59-abc3-40ad-8e14-0cac9de2cac4", + "name" : "${broker.name}", + "confidentialConfigurationEncryptionProvider" : "AESKeyFile", + .... + } + </screen> + </example> + <para>Note that passwords stored by the Authentication Providers <link + linkEnd="Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link> and. + <link linkEnd="Java-Broker-Security-Base64MD5PasswordFile-Provider">PlainPasswordFile</link> + with the external password files are <emphasis>not</emphasis> encrypted by the key. Use the + Scram Authentication Managers instead; these make use of the Configuration Encryption when + storing the users' passwords. </para> + </section> + <section id="Java-Broker-Security-Configuration-Encryption-Alternate-Implementations"> + <title>Alternate Implementations</title> + <para>If the <literal>AESKeyFile</literal> encryptor implementation does not meet the needs of + the user, perhaps owing to the security standards of their institution, the + <literal>ConfigurationSecretEncrypter</literal> interface is designed as an extension point. + Users may implement their own implementation of ConfigurationSecretEncrypter perhaps to employ + stronger encryption or delegating the storage of the key to an Enterprise Password Safe.</para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Group-Providers.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Group-Providers.xml new file mode 100644 index 0000000000..ac106b195f --- /dev/null +++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Group-Providers.xml @@ -0,0 +1,62 @@ +<?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-Group-Providers"> + <title>Group Providers</title> + <para> + The Java broker utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-ACLs">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. + </para> + + <section role="h3" id="File-Group-Manager"> + <title>GroupFile Provider</title> + <para> + The <emphasis>GroupFile</emphasis> Provider allows specifying group membership in a flat file on disk. + On adding a new GroupFile Provider the path to the groups file is required to be specified. + If file does not exist an empty file is created automatically. On deletion of GroupFile Provider + the groups file is deleted as well. Only one instance of "GroupFile" Provider per groups file location can be created. + On attempt to create another GroupFile Provider pointing to the same location the error will be displayed and + the creation will be aborted. + </para> + + <section role="h4" id="File-Group-Manager-FileFormat"> + <title>File Format</title> + <para> + The groups file has the following format: + </para> + <programlisting> + # <GroupName>.users = <comma delimited user list> + # For example: + + administrators.users = admin,manager +</programlisting> + <para> + Only users can be added to a group currently, not other groups. Usernames can't contain commas. + </para><para> + Lines starting with a '#' are treated as comments when opening the file, but these are not preserved when the broker updates the file due to changes made through the management interface. + </para> + </section> + </section> +</section> |