diff options
| author | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:00:55 +0000 |
|---|---|---|
| committer | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:00:55 +0000 |
| commit | b15e32a943ae269c1c7dae4b2084e2ad87f3940d (patch) | |
| tree | 8b3206ffa501d186fee43b3cc3ab3ef924b53e3b /qpid/doc/book/src/java-broker/security | |
| parent | 0a0baee45ebcff44635907d457c4ff6810b09c87 (diff) | |
| download | qpid-python-b15e32a943ae269c1c7dae4b2084e2ad87f3940d.tar.gz | |
QPID-6481: Move java broker docbook into java source tree
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1673703 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/doc/book/src/java-broker/security')
14 files changed, 0 insertions, 1313 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 deleted file mode 100644 index 95d718df29..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-ACLs.xml +++ /dev/null @@ -1,646 +0,0 @@ -<?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 deleted file mode 100644 index 9c727ebc78..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Anonymous.xml +++ /dev/null @@ -1,30 +0,0 @@ -<?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 deleted file mode 100644 index 14319c68eb..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Base64MD5PasswordFile.xml +++ /dev/null @@ -1,43 +0,0 @@ -<?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 deleted file mode 100644 index 70f0d199ba..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-External.xml +++ /dev/null @@ -1,50 +0,0 @@ -<?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 deleted file mode 100644 index fbac55f2e2..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Kerberos.xml +++ /dev/null @@ -1,64 +0,0 @@ -<?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 deleted file mode 100644 index 81b36f4692..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml +++ /dev/null @@ -1,99 +0,0 @@ -<?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 deleted file mode 100644 index 04d8e2e84d..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5.xml +++ /dev/null @@ -1,35 +0,0 @@ -<?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 deleted file mode 100644 index 28b9507f06..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-MD5PasswordFile.xml +++ /dev/null @@ -1,42 +0,0 @@ -<?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> 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 deleted file mode 100644 index 92b8685e93..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-Plain.xml +++ /dev/null @@ -1,34 +0,0 @@ -<?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 deleted file mode 100644 index 8d4fa54a1c..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-PlainPasswordFile.xml +++ /dev/null @@ -1,47 +0,0 @@ -<?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 deleted file mode 100644 index 46d0269564..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-ScramSha.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?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 deleted file mode 100644 index b5546ffebf..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers.xml +++ /dev/null @@ -1,51 +0,0 @@ -<?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 deleted file mode 100644 index 2924f2859c..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml +++ /dev/null @@ -1,74 +0,0 @@ -<?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 deleted file mode 100644 index ac106b195f..0000000000 --- a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Group-Providers.xml +++ /dev/null @@ -1,62 +0,0 @@ -<?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> |