The JAAS certificate authentication plug-in must be used in combination with an SSL/TLS protocol (for example, ssl: or https:) and the clients must be configured with their own certificate. In this scenario, authentication is actually performed during the SSL/TLS handshake, not directly by the JAAS certificate authentication plug-in. The role of the plug-in is as follows:

The simplest way to make the login configuration available to JAAS is to add the directory containing the file, login.config, to your CLASSPATH.

Alternatively, you can set the java.security.auth.login.config system property at the command line, setting it to the pathname of the login configuration file (for example, edit the bin/activemq script, adding an option of the form, -Djava.security.auth.login.config=Value to the Java command line). If you are working on the Windows platform, note that the pathname of the login configuration file must use forward slashes, /, in place of backslashes, \.

The following CertLogin login entry shows how to configure JAAS certificate authentication in the login.config file:

CertLogin {
    org.apache.activemq.jaas.TextFileCertificateLoginModule required
        debug=true
        org.apache.activemq.jaas.textfiledn.user="users.properties"
        org.apache.activemq.jaas.textfiledn.group="groups.properties";
};

In the context of the certificate authentication plug-in, the users.properties file consists of a list of properties of the form, UserName=StringifiedSubjectDN. For example, to define the users, system, user, and guest, you could create a file like the following:

system=CN=system,O=Progress,C=US
user=CN=humble user,O=Progress,C=US
guest=CN=anon,O=Progress,C=DE

Each username is mapped to a subject DN, encoded as a string (where the string encoding is specified by RFC 2253). For example, the system username is mapped to the CN=system,O=Progress,C=US subject DN. When performing authentication, the plug-in extracts the subject DN from the received certificate, converts it to the standard string format, and compares it with the subject DNs in the users.properties file by testing for string equality. Consequently, you must be careful to ensure that the subject DNs appearing in the users.properties file are an exact match for the subject DNs extracted from the user certificates.

	Note
	Technically, there is some residual ambiguity in the DN string format. For example, the domainComponent attribute could be represented in a string either as the string, DC, or as the OID, 0.9.2342.19200300.100.1.25. Normally, you do not need to worry about this ambiguity. But it could potentially be a problem, if you changed the underlying implementation of the Java security layer.

The easiest way to obtain the subject DNs from the user certificates is by invoking the keytool utility to print the certificate contents. To print the contents of a certificate in a keystore, perform the following steps:

The groups.properties file consists of a list of properties of the form, Group=UserList, where UserList is a comma-separated list of users. For example, to define the groups, admins, users, and guests, you could create a file like the following:

admins=system
users=system,user
guests=guest

To enable the JAAS certificate authentication plug-in, add the jaasCertificateAuthenticationPlugin element to the list of plug-ins in the broker configuration file, as shown:

<beans>
  <broker ...>
    ...
    <plugins>
      <jaasCertificateAuthenticationPlugin configuration="CertLogin" />
    </plugins>
    ...
  </broker>
</beans>

The configuration attribute specifies the label of a login entry from the login configuration file (for example, see Example 3.4). In the preceding example, the CertLogin login entry is selected.