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 | 337 |
1 files changed, 173 insertions, 164 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 538d08d8e9..817c8f2621 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,113 +26,136 @@ <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> - - <para> - The Authentication Providers can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-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> + + <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> - 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> 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> <section id="Java-Broker-Security-LDAP-Provider"> - <title>Simple LDAP Authentication Provider</title> - - <para> - SimpleLDAPAuthenticationProvider 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="SSL-Truststore-ClientCertificate">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> - In order to protect the security of the user's password, when using LDAP authentication, you must: - <itemizedlist> - <listitem><para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during - transmission to the Broker.</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> + <title>Simple LDAP Authentication Provider</title> + + <para> SimpleLDAPAuthenticationProvider 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> - <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> - 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 url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security authentication</ulink> - is used so the Directory receives the password in the clear. - </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, JMX, and HTTP ports to protect the password during + transmission to the Broker.</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. 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> 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 + 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> <section id="Java-Broker-Security-Kerberos-Provider"> - <title>Kerberos</title> + <title>Kerberos</title> - <para> - Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections. - </para> + <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> + <para> Configuration of kerberos is done through system properties (there doesn't seem to be a + way around this unfortunately). </para> - <programlisting> + <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> + <para>Where qpid.conf would look something like this:</para> - <programlisting><![CDATA[ + <programlisting><![CDATA[ com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true @@ -145,109 +168,95 @@ com.sun.security.jgss.accept { 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> 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> 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> + <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> <section id="Java-Broker-Security-External-Provider"> <title>External (SSL Client Certificates)</title> - <para> - When <link linkend="SSL-Truststore-ClientCertificate"> 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> 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 ports, in conjunction with <link linkend="SSL-Truststore-ClientCertificate">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> - - <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> + <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically + only be used on the AMQP 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> + + <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> </section> <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 fields on creation. - </para> + <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> </section> <section id="Java-Broker-Security-PlainPasswordFile-Provider"> <title>Plain Password File</title> - <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> + <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> <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> - <programlisting> + <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> + <programlisting> # password file format # <user name>: <user password> guest:guest </programlisting> - </section> + </section> </section> <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> + <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> </section> </section> - |