Sun Java System Message Queue 4.3 Administration Guide

Using JAAS-Based Authentication

The Java Authentication and Authorization Service (JAAS) API allows you to plug an external authentication mechanism into Message Queue. This section describes the information that the Message Queue message broker makes available to a JAAS-compliant authentication service and explains how to configure the broker to use such a service. The following sources provide further information on JAAS:

JAAS is a core API in Java 2 Standard Edition (J2SE), and is therefore an integral part of Message Queue’s runtime environment. It defines an abstraction layer between an application and an authentication mechanism, allowing the desired mechanism to be plugged in with no change to application code. In the case of the Message Queue service, the abstraction layer lies between the broker (application) and an authentication provider. By setting a few broker properties, it is possible to plug in any JAAS-compliant authentication service and to upgrade this service with no disruption or change to broker code.


Note –

You cannot use the Java Management Extensions (JMX) API to change JAAS-related broker properties. However, once JAAS-based authentication is configured, JMX client applications (like other clients) can be authenticated using this mechanism.


Elements of JAAS

Figure 9–2 shows the basic elements of JAAS: a JAAS client, a JAAS-compliant authentication service, and a JAAS configuration file.

Figure 9–2 JAAS Elements

This figure shows the elements required for JAAS-compliant
authentication. The text that introduces the figure explains its contents.

JAAS and Message Queue

Figure 9–3 shows how JAAS is used by the Message Queue broker. It shows a more complex implementation of the JAAS model shown in Figure 9–2.

Figure 9–3 How Message Queue Uses JAAS

The figure shows how JAAS-compliant authentication is
used with Message Queue. The text that follows the figure explains its contents.

The authentication service layer, consisting of one or more login modules (if needed) and corresponding authentication logic, is separate from the broker. The login modules run in the same Java virtual machine as the broker. The broker is represented to the login module as a login context, and communicates with the login module by means of a callback handler that is part of the broker runtime code.

The authentication service also supplies a JAAS configuration file containing entries that reference the login modules. The configuration file specifies the order in which the login modules (if more than one) are to be used and any conditions for their use. When the broker starts up, it locates the configuration file by consulting either the Java system property java.security.auth.login.config or the Java security properties file. The broker then selects an entry in the JAAS configuration file according to the value of the broker property imq.user_repository.jaas.name. That entry specifies which login module(s) will be used for authentication. The classes for the login modules are found in the Message Queue external resource files directory, whose location depends on the operating system platform you are using; see Appendix A, Platform-Specific Locations of Message Queue Data for details.

The relation between the configuration file, the login module, and the broker is shown in the following figure. Figure 9–4.

Figure 9–4 Setting Up JAAS Support

This figure shows the relationship between JAAS-related
files. The text preceding the figure explains its content.

The fact that the broker uses a JAAS plug-in authentication service remains completely transparent to the Message Queue client. The client continues to connect to the broker as it did before, passing a user name and password. In turn, the broker uses a callback handler to pass login information to the authentication service, and the service uses the information to authenticate the user and return the results. If authentication succeeds, the broker grants the connection; if it fails, the client runtime returns a JMS security exception that the client must handle.

After the Message Queue client is authenticated, if there is further authorization to be done, the broker proceeds as it normally would, consulting the access control file to determine whether the authenticated client is authorized to perform the actions it undertakes: accessing a destination, consuming a message, browsing a queue, and so on.

Setting up JAAS-Compliant Authentication

Setting up JAAS-compliant authentication involves setting broker and system properties to select this type of authentication, to specify the location of the configuration file, and to specify the entries to the login modules that are going to be used.

To set up JAAS support for Message Queue, you perform the following general steps. (These steps assume you are creating your own authentication service.)

  1. Create one or more login module classes that implement the authentication service. The JAAS callback types that the broker supports are listed below.

    javax.security.auth.callback.LanguageCallback

    The broker uses this callback to pass the authentication service the locale in which the broker is running. This value can be used for localization.

    javax.security.auth.callback.NameCallback

    The broker uses this callback to pass to the authentication service the user name specified by the Message Queue client when the connection was requested.

    javax.security.auth.callback.TextInputCallback

    The broker uses this callback to pass the value of the following information to the login module (authentication service) when requested through the TextInputCallback.getPrompt() with the following strings:

    • imq.authentication.type: The broker authentication type in effect at runtime

    • imq.accesscontrol.type: The broker access control type in effect at runtime

    • imq.authentication.clientip: The client IP address (null if unavailable)

    • imq.servicename: The name of the connection service (jms, ssljms, admin, or ssladmin) being used by the client

    • imq.servicetype: The type of the connection service (NORMAL or ADMIN) being used by the client

    javax.security.auth.callback.PasswordCallback

    The broker uses this callback to pass to the authentication service the password specified by the Message Queue client when the connection was requested.

    javax.security.auth.callback.TextOutputCallback

    The broker handles this callback to provide logging service to the authentication service by logging the text output to the broker's log file. The callback's MessageType ERROR, INFORMATION, WARNING are mapped to the broker logging levels ERROR, INFO, WARNING respectively.

  2. Create a JAAS configuration file with entries that reference the login module classes created in Step 1 and specify the location of this file.

  3. Note the name of the entry in the JAAS configuration file (that references the login module implementation classes).

  4. Archive the classes that implement the login modules to a jar file, and place the jar file in the Message Queue lib/ext directory.

  5. Set the broker configuration properties that relate to JAAS support. These are described in Table 9–4.

  6. Set the following system property (to specify the location of the JAAS configuration file).

    java.security.auth.login.config=JAAS_Config_File_Location

    For example, you can specify the location when you start the broker.

    imqbrokerd -Djava.security.auth.login.config=JAAS_Config_File_Location

    There are other ways to specify the location of the JAAS configuration file. For additional information, please see

    http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html

The following table lists the broker properties that need to be set to set up JAAS support.

Table 9–4 Broker Properties for JAAS Support

Property 

Description 

imq.authentication.type

Set to basic to indicate Base-64 password encoding. This is the only permissible value for JAAS authentication.

imq.authentication.basic.user_repository

Set to jaas to specify JAAS authentication.

imq.user_repository.jaas.name

Set to the name of the desired entry (in the JAAS configuration file) that references the login modules you want to use as the authentication mechanism. This is the name you noted in Step 3. 

imq.user_repository.jaas.userPrincipalClass

This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s) that the broker uses to extract the Principal name to represent the user entity in the Message Queue access control file. If, it is not specified, the user name passed from the Message Queue client when a connection was requested is used instead.

imq.user_repository.jaas.groupPrincipalClass

This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s) that the broker uses to extract the Principal name to represent the group entity in the Message Queue access control file. If, it is not specified, the group rules, if any, in the Message Queue access control file are ignored.