diff options
Diffstat (limited to 'qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml')
| -rw-r--r-- | qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml | 124 |
1 files changed, 54 insertions, 70 deletions
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml index 817c8f2621..44faea5999 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml @@ -26,41 +26,12 @@ <section id="Java-Broker-Security-Authentication-Providers"> <title>Authentication Providers</title> - - <para>TODO SCRAM-SHA</para> + <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> - <para> The Authentication 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 Authentication Provider managing operations are available from Web Management - Console: <itemizedlist> - <listitem> - <para>A new Authentication Provider can be added by clicking onto "Add Provider" on the - Broker tab.</para> - </listitem> - <listitem> - <para>An Authentication Provider details can be viewed on the Authentication Provider tab. - The tab is displayed after clicking onto Authentication Provider name in the Broker object - tree or after clicking onto Authentication Provider row in Authentication Providers grid - on the Broker tab.</para> - </listitem> - <listitem> - <para>Editing of Authentication Provider can be performed by clicking on "Edit" button on - Authentication Provider tab.</para> - </listitem> - <listitem> - <para>An existing Authentication Provider can be deleted by clicking on "Delete Provider" - button on Broker tab or "Delete" button on the Authentication Provider tab.</para> - </listitem> - </itemizedlist> The Authentication Provider type and name cannot be changed for existing - providers as editing of name and type is unsupported at the moment. Only provider specific - attributes can be modified in the editing dialog and stored in the broker configuration store. </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 @@ -117,8 +88,9 @@ you must: </para> <itemizedlist> <listitem> - <para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during - transmission to the Broker.</para> + <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 @@ -127,14 +99,16 @@ </itemizedlist> </important> - <para> The LDAP Authentication Provider works in the following manner. It first connects to the - Directory anonymously 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> 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, the Authentication Provider then attempts to bind to the - LDAP server with the given name and the password. Note that <ulink + <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> @@ -192,21 +166,20 @@ com.sun.security.jgss.accept { <para> <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically - only be used on the AMQP ports, in conjunction with <link + 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 non-AMQP - ports. Perhaps the only exception to this would be where the broker is embedded in a container - that is itself externally protecting the HTTP interface and then providing the remote users - name. </para> + 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 field "Use the full DN as the Username" is set to "true" the full DN is used - as an authenticated principal name. If field "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> + 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> <section id="Java-Broker-Security-Anonymous-Provider"> @@ -214,8 +187,23 @@ com.sun.security.jgss.accept { <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 fields on creation. </para> + Provider does not require specification of any additional attributes on creation. </para> + </section> + <section id="Java-Broker-Security-ScramSha-Providers"> + <title>SCRAM SHA Providers</title> + <para>The SCRAM SHA Providers uses the Broker configuration itself to store the database of + users. (Unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider" + >Plain</link> and <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider" + >Base64MD5</link> providers that follow, there is no separate password file). 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 varients 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> <section id="Java-Broker-Security-PlainPasswordFile-Provider"> @@ -223,19 +211,15 @@ com.sun.security.jgss.accept { <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. For this Provider user - credentials can be added, removed or changed using REST management interfaces and web - management console. </para> - <para> On navigating to the Plain Password File Provider tab (by clicking onto provider name - from Broker tree or provider row in providers grid on Broker tab) the list of existing - credentials is displayed on the tab with the buttons "Add User" and "Delete Users" to add new - user credentials and delete the existing user credentials respectively. On clicking into user - name on Users grid the pop-up dialog to change the password is displayed. </para> + creation. On Provider deletion the password file is deleted as well.</para> + <para>For these providers 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. </para> + 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> @@ -247,16 +231,16 @@ guest:guest <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider"> <title>Base64MD5 Password File</title> <para> Base64MD5PasswordFile Provider uses local file to store and manage user credentials - similar to 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. For this Provider user credentials can - be added, removed or changed using REST management interfaces and web management console. </para> - <para> On navigating to the Base64MD5PasswordFile Provider tab (by clicking onto provider name - from Broker tree or provider row in providers grid on Broker tab) the list of existing - credentials is displayed on the tab with the buttons "Add User" and "Delete Users" to add new - user credentials and delete the existing user credentials respectively. On clicking into user - name on Users grid the pop-up dialog to change the password is displayed. </para> + 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> + <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> </section> |