From bb9160e892017cd58a14b9eb0ebd282e787229d5 Mon Sep 17 00:00:00 2001 From: Robert Gemmell Date: Sun, 4 Nov 2012 21:03:36 +0000 Subject: QPID-4420: add documentation for SSL and the Anonymous + External AuthenticationManagers along with some general cleanup and expanded testing git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1405636 13f79535-47bb-0310-9956-ffa450edef68 --- ...va-Broker-Security-Authentication-Providers.xml | 247 ++++++++++++++------- .../src/java-broker/Java-Broker-Security-SSL.xml | 81 ++++++- 2 files changed, 252 insertions(+), 76 deletions(-) (limited to 'qpid/doc/book/src') 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 58360dc722..96b6f99185 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,55 +26,22 @@ 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". 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, that manager will be used on all ports (including JMX). Where - more than one authentication manager is configured the configuration must define which - manager is the "default", and (if required) the mapping of non-default authentication - managers to other ports. - - - The following configuration sets up three authentication managers, using a password file as - the default (e.g. for the JMX port), Kerberos on port 5672 and Anonymous on 5673. + with its own "authentication manager". Each of these are outlined below, along with details + of using more than one at a time. - - Configuring different authentication schemes on different ports - - - - org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase - - - passwordFile - ${conf}/passwd - - - - - sib - - PrincipalDatabaseAuthenticationManager - - - 5672 - KerberosAuthenticationManager - - - 5673 - AnonymousAuthenticationManager - - -]]> - - +
+ Password File + + TODO + + +
-
Password File
-
LDAP +
+ LDAP - Configuring a LDAP authentication + Configuring LDAP authentication @@ -82,8 +49,8 @@ dc=example\,dc=com (uid={0}) -]]> - + ... +]]> @@ -111,9 +78,10 @@ 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. -
-
Kerberos + +
+ Kerberos Kereberos Authentication is configured using the <kerberos-auth-manager> element within @@ -128,30 +96,30 @@ - Configuring a Kerberos authentication + Configuring Kerberos authentication - - - org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase - - - passwordFile - ${conf}/passwd - - - - - - PrincipalDatabaseAuthenticationManager - - - 5672 - KerberosAuthenticationManager - - -]]> - + + + org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase + + + passwordFile + ${conf}/passwd + + + + + + PrincipalDatabaseAuthenticationManager + + + 5672 + KerberosAuthenticationManager + + + ... +]]> @@ -177,8 +145,7 @@ com.sun.security.jgss.accept { kdc="kerberos.example.com" keyTab="/path/to/keytab-file" principal="/"; -};]]> - +};]]> Where realm, kdc, keyTab and principal should obviously be set correctly for the environment @@ -191,7 +158,137 @@ com.sun.security.jgss.accept { Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working.
-
SSL Client Certificates
-
Anonymous
+ +
+ External (SSL Client Certificates) + + + When requiring SSL Client Certificates be + presented the ExternalAuthenticationManager 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. + + + + 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. + + + + Note: The ExternalAuthenticationManager should typically only be used on the + AMQP ports, in conjunction with SSL client certificate + authentication. 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 + include another Authentication Manager for use on non-AMQP ports, + 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. + + + + Configuring external authentication (SSL client auth) + + + + org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase + + + passwordFile + ${conf}/passwd + + + + + + PrincipalDatabaseAuthenticationManager + + + 5672 + ExternalAuthenticationManager + + + ... +]]> + + +
+ +
+ Anonymous + + + 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. + + + + Configuring anonymous authentication + + + + ... +]]> + + + + When referencing it from the default-auth-manager or port-mapping sections, its name is + AnonymousAuthenticationManager. + +
+ +
+ Configuring multiple Authentication Providers + + 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. + + + 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). + + + + Configuring multiple (per-port) authentication schemes + + + + org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase + + + passwordFile + ${conf}/passwd + + + + + + sib + + + PrincipalDatabaseAuthenticationManager + + + 5672 + KerberosAuthenticationManager + + + 5673 + AnonymousAuthenticationManager + + + ... +]]> + +
+
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml index 8e95caf1c3..541f6cf5d9 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml @@ -21,6 +21,85 @@ -->
-SSL + SSL + + This section will show how to use SSL to enable secure + connections between an AMQP message client and the broker. + +
+ Keystore Configuration + + The broker configuration file (config.xml) needs to be updated to include the required SSL keystore + configuration, an example of which can be found below. + + + + Configuring an SSL Keystore + + ... + + true + 5671 + false + /path/to/keystore.ks + keystorepass + alias + + ... +]]> + + + + The certAlias element is an optional way of specifying which certificate the broker should use + if the keystore contains multiple entries. + + + + The sslOnly element controls whether the broker will only bind + the configured SSL port(s) or will also bind the non-SSL port(s). Setting sslOnly to true will + disable the non-SSL ports. + +
+ +
+ Truststore / Client Certificate Authentication + + The SSL trustore and related Client Certificate Authentication behaviour can be configured with + additional configuration as shown in the example below, in which the broker requires client + certificate authentication. + + + + Configuring an SSL Truststore and client auth + + ... + + ... + /path/to/truststore.ks + truststorepass + true + false + ... + + ... +]]> + + + + The needClientAuth and wantClientAuth elements allow control of whether the client must present an + SSL certificate. Only one of these elements is needed but both may be used at the same time. + A socket's client authentication setting is one of three states: required (needClientAuth = true), + requested (wantClientAuth = true), or none desired (both false, the default). If both elements are + set to true, needClientAuth takes precedence. + + + + When using Client Certificate Authentication it may be desirable to use the External Authentication + Manager, for details see + + +
-- cgit v1.2.1