Chapter 8. Secure Your Connections and Resources

Procedure 8.1. Configure SASL using a Local Password File

1. Add new users to the database by using the saslpasswd2 command. The User ID for authentication and ACL authorization uses the form user-id@domain.
   Ensure that the correct realm has been set for the broker. This can be done by editing the configuration file or using the -u option. The default realm for the broker is QPID.

   # saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u QPID new_user_name

2. Existing user accounts can be listed by using the -f option:

   # sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
   

   Note

   The user database at /var/lib/qpidd/qpidd.sasldb is readable only by the qpidd user. If you start the broker from a user other than the qpidd user, you will need to either modify the configuration file, or turn authentication off.

   Note also that this file must be readable by the qpidd user. If you delete and recreate this file, make sure the qpidd user has read permissions, or authentication attempts will fail.
3. To switch authentication on or off, use the auth yes|no option when you start the broker:

   # /usr/sbin/qpidd --auth yes
   
   # /usr/sbin/qpidd --auth no
   

   You can also set authentication to be on or off by adding the appropriate line to to the /etc/qpid/qpidd.conf configuration file:

   auth=no
   
   auth=yes
   

   The SASL configuration file is in /etc/sasl2/qpidd.conf for Red Hat Enterprise Linux.

1. To start using the ACL, specify the path and filename using the --acl-file command. The filename should have a .acl extension:

   $ qpidd --acl-file ./aclfilename.acl

2. Optionally, you can limit the number of active connections per user with the --connection-limit-per-user and --connection-limit-per-ip commands. These limits can only be enforced if the --acl-file command is specified.
3. You can now view the file with the cat command and edit it in your preferred text editor. If the path and filename is not found, qpidd will fail to start.

1. Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client:

   $ sudo yum install cyrus-sasl-gssapi krb5-workstation
   

2. Change the mech_list line in /etc/sasl2/qpidd.conf to:

   mech_list: GSSAPI

3. Add the following lines to /etc/qpid/qpidd.conf:

   auth=yes
   realm=QPID

4. Register the Qpid broker in the Kerberos database.
   Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format primary/instance@REALM. For a broker, the primary is qpidd, the instance is the fully qualified domain name, and the REALM is the Kerberos domain realm. By default, this realm is QPID, but a different realm can be specified in qpid.conf per the following example.

   realm=EXAMPLE.COM

   For instance, if the fully qualified domain name is dublduck.example.com and the Kerberos domain realm is EXAMPLE.COM, then the principal name is qpidd/dublduck.example.com@EXAMPLE.COM.

   FDQN=`hostname --fqdn`
   REALM="EXAMPLE.COM"
   kadmin -r $REALM  -q "addprinc -randkey -clearpolicy qpidd/$FQDN"

   Now create a Kerberos keytab file for the broker. The broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access:

   QPIDD_GROUP="qpidd"
   kadmin -r $REALM  -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM"
   chmod g+r /etc/qpidd.keytab
   chgrp $QPIDD_GROUP /etc/qpidd.keytab
   

   The default location for the keytab file is /etc/krb5.keytab. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file as the following example shows.

   export KRB5_KTNAME=/etc/qpidd.keytab

   If this is correctly configured, you can now enable Kerberos support on the broker by setting the auth and realm options in /etc/qpid/qpidd.conf:

   CDATA[# /etc/qpid/qpidd.conf
   auth=yes
   realm=EXAMPLE.COM

   Restart the broker to activate these settings.
5. Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed:

   $ kinit user@REALM.COM

6. Additional configuration for Java JMS clients

   Java JMS clients require a few additional steps.
   1. The Java JVM must be run with the following arguments:

      -Djavax.security.auth.useSubjectCredsOnly=false

      Forces the SASL GSSAPI client to obtain the Kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.

      -Djava.security.auth.login.config=myjas.conf

      Specifies the jass configuration file. Here is a sample JASS configuration file:

      com.sun.security.jgss.initiate {
          com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
      };

      -Dsun.security.krb5.debug=true

      Enables detailed debug info for troubleshooting

   2. The client Connection URL must specify the following Kerberos-specific broker properties:
      • sasl_mechs must be set to GSSAPI.
      • sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/
      • sasl_server must be set to the host for the SASL server, e.g. sasl.com.
      Here is a sample connection URL for a Kerberos connection:

      amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''