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 | 306 |
1 files changed, 117 insertions, 189 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 0974441ae5..8b91a6f33d 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,135 +26,102 @@ <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 manager". Each of these are outlined below, along with details - of <link linkend="MultipleAuthProviders"> using more than one at a time</link>. + with its own "authentication provider". Any number of Authentication Providers can be configured + on the Broker at the same time. </para> - <section> - <title>Password File</title> - <para> - TODO - </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> - </section> + <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> - <section id="LDAPAuthManager"> - <title>LDAP</title> + <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. + </important> + + <section id="Java-Broker-Security-LDAP-Provider"> + <title>Simple LDAP Authentication Provider</title> <para> - LDAP authentication can be configured using the <simple-ldap-auth-manager> element - within the <security> section. An example of how to configure this is shown below. - Please note this example also configures an unused <pd-auth-manager> to use an empty - password file, this is a workaround for an issue relating to registration of security providers. + SimpleLDAPAuthenticationProvider authenticate the connections by searching for a user unique distinguished name + in the pre-configured LDAP search directory and performing LDAP bind using the found DN and password after that. + On creation of SimpleLDAPAuthenticationProvider the following mandatory fields are required to specify: + <itemizedlist> + <listitem><para><emphasis>LDAP server URL</emphasis> is an URL of LDAP server, for example, ldaps://example.com:636</para></listitem> + <listitem><para><emphasis>Search context</emphasis> is a LDAP directory name to search for users entries, for example, "dc=users,dc=example,dc=com"</para></listitem> + <listitem><para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by provided user name, for example, (uid={0})</para></listitem> + </itemizedlist> + Additionally, the following optional fields can be specified: + <itemizedlist> + <listitem><para><emphasis>LDAP context factory</emphasis> is fully qualified class name for the JNDI LDAP context factory.</para></listitem> + <listitem><para><emphasis>LDAP authentication URL</emphasis>is an URL of LDAP server for performing "ldap bind" + if a different LDAP URL is required for performing an authentication.</para></listitem> + </itemizedlist> </para> <para> <emphasis>NOTE: When using LDAP authentication, you must also use SSL on the brokers AMQP messaging and JMX/HTTP management ports in order to protect passwords during transmission to the broker.</emphasis> </para> - <example> - <title>Configuring LDAP authentication</title> - <programlisting><![CDATA[ -<security> - <default-auth-manager>SimpleLDAPAuthenticationManager</default-auth-manager> - <simple-ldap-auth-manager> - <provider-url>ldaps://example.com:636/</provider-url> - <search-context>dc=example\,dc=com</search-context> - <search-filter>(uid={0})</search-filter> - </simple-ldap-auth-manager> - - <!-- Unused pd-auth-manager, a workaround to register the necessary security providers --> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/emptyPasswdFile</value> - </attribute> - </attributes> - </principal-database> - <pd-auth-manager> - ... -</security>]]></programlisting> - </example> <para> - The authentication manager first connects to the ldap server anonymously and searches for the + The Authentication Provider first connects to the ldap server anonymously and searches for the ldap entity which is identified by the username provided over SASL. Essentially the - authentication manager calls - DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) - with the values of search-context and search-filter as the first two arguments, and the username - as the only element in the array which is the third argument. + authentication manager calls DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) + with the values of <emphasis>Search context</emphasis> and <emphasis>Search filter</emphasis> as the first two arguments, + and the username as the only element in the array which is the third argument. </para> <para> - If the search returns a name from the LDAP server, the AuthenticationManager then attempts to - login to the ldap server with the given name and the password. + If the search returns a name from the LDAP server, the Authentication Provider then attempts to + login to the LDAP server with the given name and the password. </para> <para> If the URL to open for authentication is different to that for the search, then the - authentication url can be overridden using <provider-auth-url> in addition to providing a - <provider-url>. Note that the URL used for authentication should use ldaps:// since + authentication url can be overridden using <LDAP authentication URL> in addition to providing a + <LDAP server URL>. Note that the URL used for authentication should use ldaps:// since passwords will be being sent over it. </para> <para> By default com.sun.jndi.ldap.LdapCtxFactory is used to create the context, however this can be - overridden by specifying <ldap-context-factory> in the configuration. + overridden by specifying <LDAP context factory> in the configuration. </para> </section> - <section> + <section id="Java-Broker-Security-Kerberos-Provider"> <title>Kerberos</title> <para> - Kereberos Authentication is configured using the <kerberos-auth-manager> element within - the <security> section. When referencing from the default-auth-manager or port-mapping - sections, its name is KerberosAuthenticationManager. + Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections. </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 Manager - configuration, and use this for other ports: - </para> - - <example> - <title>Configuring Kerberos authentication</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <kerberos-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>KerberosAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> - - <para> Configuration of kerberos is done through system properties (there doesn't seem to be a way around this unfortunately). </para> <programlisting> - export QPID_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf + export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf ${QPID_HOME}/bin/qpid-server </programlisting> @@ -183,138 +150,99 @@ com.sun.security.jgss.accept { 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> - <section id="ExternalAuthManager"> + <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 ExternalAuthenticationManager can be used, such that the user is authenticated based on + 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> - The ExternalAuthenticationManager may be enabled by adding an empty <external-auth-manager> element to - the <security> section, as shown below. When referencing it from the default-auth-manager or port-mapping - sections, its name is ExternalAuthenticationManager. - </para> - - <para> - <emphasis role="bold">Note:</emphasis> The ExternalAuthenticationManager should typically only be used on the + <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 successfull with the given username. As such you should - <link linkend="MultipleAuthProviders">include another Authentication Manager for use on non-AMQP ports</link>, - as is done in the example below. 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. + 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> - <example> - <title>Configuring external authentication (SSL client auth)</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <external-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>ExternalAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> - + <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="AnonymousAuthManager"> + <section id="Java-Broker-Security-Anonymous-Provider"> <title>Anonymous</title> <para> - The AnonymousAuthenticationManager will allow users to connect with or without credentials and result - in their identification on the broker as the user ANONYMOUS. It may be enabled by adding an empty - anonymous-auth-manager element to the security configuration section, as shown below. + 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> - <example> - <title>Configuring anonymous authentication</title> - - <programlisting><![CDATA[ -<security> - <anonymous-auth-manager/> - ... -</security>]]></programlisting> - </example> + </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> - When referencing it from the default-auth-manager or port-mapping sections, its name is - AnonymousAuthenticationManager. + 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> +# password file format +# <user name>: <user password> +guest:guest + </programlisting> + </section> </section> - <section id="MultipleAuthProviders"> - <title>Configuring multiple Authentication Providers</title> + <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider"> + <title>Base64MD5 Password File</title> <para> - Different managers may be used on different ports. Each manager has its own configuration element, - the presence of which within the <security> section denotes the use of that authentication - provider. Where only one such manager is configured, it will be used on all ports (including JMX - and HTTP). Where more than one authentication manager is configured the configuration must define - which is the "default", and (if required) the mapping of non-default authentication managers to - other ports. + 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> - The following configuration sets up three authentication managers, using a password file as the - default (e.g. for the JMX and HTTP ports), Kerberos on port 5672 (the regular AMQP port) and Anonymous - on port 5673 (e.g a second AMQP port the broker could have been configured with). + 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> - - <example> - <title>Configuring multiple (per-port) authentication schemes</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <kerberos-auth-manager> - <auth-name>sib</auth-name> - </kerberos-auth-manager> - <anonymous-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>KerberosAuthenticationManager</auth-manager> - </port-mapping> - <port-mapping> - <port>5673</port> - <auth-manager>AnonymousAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> </section> - </section> |