Users attempting to connect to a Message Queue message broker must provide a user name and password for authentication. The broker will grant the connection only if the name and password match those in a broker-specific user repository listing the authorized users and their passwords. Each broker instance can have its own user repository, which you as an administrator are responsible for maintaining. This section tells how to create, populate, and manage the user repository.
Message Queue can support any of three types of authentication mechanism:
A flat-file repository that is shipped with Message Queue. This type of repository is very easy to populate and manage, using the Message Queue User Manager utility (imqusermgr).
A Lightweight Directory Access Protocol (LDAP) server. This could be a new or existing LDAP directory server using the LDAP v2 or v3 protocol. You use the tools provided by the LDAP vendor to populate and manage the user repository. This type of repository is not as easy to use as the flat-file repository, but it is more scalable and therefore better for production environments.
An external authentication mechanism plugged into Message Queue by means of the Java Authentication and Authorization Service (JAAS) API.
See Using a Flat-File User Repository, Using an LDAP User Repository, and Using JAAS-Based Authentication for information on these three types of authentication mechanism.
Message Queue provides a built-in flat-file user repository and a command line tool, the User Manager utility (imqusermgr), for populating and managing it. Each broker has its own flat-file user repository, created automatically when you start the broker. The user repository resides in a file named passwd, in a directory identified by the name of the broker instance with which the repository is associated:
…/instances/instanceName/etc/passwd
(See Appendix A, Platform-Specific Locations of Message Queue Data for the exact location of the instances directory, depending on your operating system platform.)
Each user in the repository can be assigned to a user group, which defines the default access privileges granted to all of its members. You can then specify authorization rules to further restrict these access privileges for specific users, as described in User Authorization. A user’s group is assigned when the user entry is first created, and cannot be changed thereafter. The only way to reassign a user to a different group is to delete the original user entry and add another entry specifying the new group.
The flat-file user repository provides three predefined groups:
For broker administrators. By default, users in this group are granted the access privileges needed to configure, administer, and manage message brokers.
For normal (non-administrative) client users. Newly created user entries are assigned to this group unless otherwise specified. By default, users in this group can connect to all Message Queue connection services of type NORMAL, produce messages to or consume messages from all physical destinations, and browse messages in any queue.
For Message Queue clients that do not wish to use a user name known to the broker (for instance, because they do not know of a real user name to use). This group is analogous to the anonymous account provided by most FTPservers. No more than one user at a time can be assigned to this group. You should restrict the access privileges of this group in comparison to the user group, or remove users from the group at deployment time.
You cannot rename or delete these predefined groups or create new ones.
In addition to its group, each user entry in the repository has a user status: either active or inactive. New user entries added to the repository are marked active by default. Changing a user’s status to inactive rescinds all of that user’s access privileges, making the user unable to open new broker connections. Such inactive entries are retained in the user repository, however, and can be reactivated at a later time. If you attempt to add a new user with the same name as an inactive user already in the repository, the operation will fail; you must either delete the inactive user entry or give the new user a different name.
To allow the broker to be used immediately after installation without further intervention by the administrator, the flat-file user repository is created with two initial entries, summarized in Table 9–1:
The admin entry (user name and password admin/admin) enables you to administer the broker with Command utility (imqcmd) commands. Immediately on installation, you should update this initial entry to change its password (see Changing a User’s Password).
The guest entry allows clients to connect to the broker using a default user name and password (guest/guest).
You can then proceed to add any additional user entries you need for individual users of your message service.
Table 9–1 Initial Entries in Flat-File User Repository
User Name |
Password |
Group |
Status |
---|---|---|---|
admin |
admin |
admin |
Active |
guest |
guest |
anonymous |
Active |
The Message Queue User Manager utility (imqusermgr) enables you to populate or edit a flat-file user repository. SeeUser Manager Utility for general reference information about the syntax, subcommands, and options of the imqusermgr command.
Before using the User Manager, keep the following things in mind:
The imqusermgr command must be run on the host where the broker is installed.
If a broker-specific user repository does not yet exist, you must start up the corresponding broker instance to create it.
You must have appropriate permissions to write to the repository; in particular, on Solaris and Linux platforms, you must be logged in as the root user or the user who first created the broker instance.
Table 9–2 lists the subcommands of the imqusermgr command. For full reference information about these subcommands, see Table 13–15.
Table 9–2 User Manager Subcommands
Subcommand |
Description |
---|---|
add |
Add user and password to repository |
delete |
Delete user from repository |
update |
Set user’s password or active status (or both) |
list |
Display user information |
The general options listed in Table 9–3 apply to all subcommands of the imqusermgr command.
Table 9–3 General User Manager Options
To display the Message Queue product version, use the -v option. For example:
imqusermgr -v
If you enter an imqusermgr command line containing the -v option in addition to a subcommand or other options, the User Manager utility processes only the -v option. All other items on the command line are ignored.
To display help on the imqusermgr command, use the -h option, and do not use a subcommand. You cannot get help about specific subcommands.
For example, the following command displays help about imqusermgr:
imqusermgr -h
If you enter an imqusermgr command line containing the -h option in addition to a subcommand or other options, the Command utility processes only the -h option. All other items on the command line are ignored.
The subcommand imqusermgr add adds an entry to the user repository, consisting of a user name and password:
imqusermgr add [-i brokerName] -u userName -p password [-g group]
The -u and -p options specify the user name and password, respectively, for the new entry. These must conform to the following conventions:
All user names and passwords must be at least one character long. Their maximum length is limited only by command shell restrictions on the maximum number of characters that can be entered on a command line.
A user name cannot contain an asterisk (*), a comma (,), a colon (:), or a new-line or carriage-return character.
If a user name or password contains a space, the entire name or password must be enclosed in quotation marks (" ").
The optional -g option specifies the group (admin, user, or anonymous) to which the new user belongs; if no group is specified, the user is assigned to the user group by default. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.
For example, the following command creates a user entry on broker imqbroker for a user named AliBaba, with password Sesame, in the admin group:
imqusermgr add -u AliBaba -p Sesame -g admin
The subcommand imqusermgr delete deletes a user entry from the repository:
imqusermgr delete [-i brokerName] -u userName
The -u option specifies the user name of the entry to be deleted. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.
For example, the following command deletes the user named AliBaba from the user repository on broker imqbroker:
imqusermgr delete -u AliBaba
You can use the subcommand imqusermgr update to change a user’s password:
imqusermgr update [-i brokerName] -u userName -p password
The -u identifies the user; -p specifies the new password. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.
For example, the following command changes the password for user AliBaba to Shazam on broker imqbroker:
imqusermgr update -u AliBaba -p Shazam
For the sake of security, you should change the password of the admin user from its initial default value (admin) to one that is known only to you. The following command changes the default administrator password for broker mybroker to veeblefetzer:
imqusermgr update -i mybroker -u admin -p veeblefetzer
You can quickly confirm that this change is in effect by running any of the command line tools when the broker is running. For example, the following command will prompt you for a password:
imqcmd list svc mybroker -u admin
Entering the new password (veeblefetzer) should work; the old password should fail.
After changing the password, you should supply the new password whenever you use any of the Message Queue administration tools, including the Administration Console.
The imqusermgr update subcommand can also be used to change a user’s active status:
imqusermgr update [-i brokerName] -u userName -a activeStatus
The -u identifies the user; -a is a boolean value specifying the user’s new status as active (true) or inactive (false). If the broker name (-i option) is omitted, the default broker imqbroker is assumed.
For example, the following command sets user AliBaba’s status to inactive on broker imqbroker:
imqusermgr update -u AliBaba -a false
This renders AliBabe unable to open new broker connections.
You can combine the -p (password) and -a (active status) options in the same imqusermgr update command. The options may appear in either order: for example, both of the following commands activate the user entry for AliBaba and set the password to plugh:
imqusermgr update -u AliBaba -p plugh -a true imqusermgr update -u AliBaba -a true -p plugh
The imqusermgr list command displays information about a user in the user repository:
imqusermgr list [-i brokerName] [-u userName]
The command
imqusermgr list -u AliBaba
displays information about user AliBabe, as shown in Example 9–1.
|
If you omit the -u option
imqusermgr list
the command lists information about all users in the repository, as in Example 9–2.
|
You configure a broker to use an LDAP directory server by setting the values for certain configuration properties in the broker’s instance configuration file (config.properties). These properties enable the broker instance to query the LDAP server for information about users and groups when a user attempts to connect to the broker or perform messaging operations.
The imq.authentication.basic.user_repository property specifies the kind of user authentication the broker is to use. By default, this property is set to file, for a flat-file user repository. For LDAP authentication, set it to ldap instead:
imq.authentication.basic.user_repository=ldap
The imq.authentication.type property controls the type of encoding used when passing a password between client and broker. By default, this property is set to digest, denoting MD5 encoding, the form used by flat-file user repositories. For LDAP authentication, set it to basic instead:
imq.authentication.type=basic
This denotes base-64 encoding, the form used by LDAP user repositories.
The following properties control various aspects of LDAP access. See Table 14–8 for more detailed information:
imq.user_repository.ldap.server |
imq.user_repository.ldap.principal |
imq.user_repository.ldap.password |
imq.user_repository.ldap.propertyName |
imq.user_repository.ldap.base |
imq.user_repository.ldap.uidattr |
imq.user_repository.ldap.usrfilter |
imq.user_repository.ldap.grpsearch |
imq.user_repository.ldap.grpbase |
imq.user_repository.ldap.gidattr |
imq.user_repository.ldap.memattr |
imq.user_repository.ldap.grpfilter |
imq.user_repository.ldap.timeout |
imq.user_repository.ldap.ssl.enabled |
If you want the broker to use a secure, encrypted SSL (Secure Socket Layer) connection for communicating with the LDAP server, set the broker’s imq.user_repository.ldap.ssl.enabled property to true
imq.user_repository.ldap.ssl.enabled=true
and the imq.user_repository.ldap.server property to the port used by the LDAP server for SSL communication: for example,
imq.user_repository.ldap.server=myhost:7878
You will also need to activate SSL communication in the LDAP server.
In addition, you may need to edit the user and group names in the broker’s access control file to match those defined in the LDAP user repository; see User Authorization for more information.
To create administrative users, you use the access control file to specify users and groups that can create ADMIN connections. These users and groups must be predefined in the LDAP directory.
Any user or group who can create an ADMIN connection can issue administrative commands.
Enable the use of the access control file by setting the broker property imq.accesscontrol.enabled to true, which is the default value.
The imq.accesscontrol.enabled property enables use of the access control file.
Open the access control file, accesscontrol.properties. The location for the file is listed in Appendix A, Platform-Specific Locations of Message Queue Data
The file contains an entry such as the following:
service connection access control##################################connection.NORMAL.allow.user=*connection.ADMIN.allow.group=admin
The entries listed are examples. Note that the admin group exists in the file-based user repository but does not exist by default in the LDAP directory. You must substitute the name of a group that is defined in the LDAP directory, to which you want to grant Message Queue administrator privileges.
To grant Message Queue administrator privileges to users, enter the user names as follows:
connection.ADMIN.allow.user= userName[[,userName2] …]
To grant Message Queue administrator privileges to groups, enter the group names as follows:
connection.ADMIN.allow.group= groupName[[,groupName2] …]
The Java Authentication and Authorization Service (JAAS) APIallows 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:
For complete information about the JAAS API, see the Java™ Authentication and Authorization Service (JAAS) Reference Guide at the URL
For information about writing a JAAS login module, see the Java™ Authentication and Authorization Service (JAAS) LoginModule Developer’s Guide at
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.
You can use Java Management Extensions (JMX) clients to manage the broker if you are using JAAS-based authentication, but you must manually set up JAAS support (by setting JAAS-related broker properties) before starting the broker. You cannot use the JMX API to change those properties.
Figure 9–1 shows the basic elements of JAAS: a JAAS client, a JAAS-compliant authentication service, and a JAAS configuration file.
The JAAS client is an application wishing to perform authentication using a JAAS-compliant authentication service. It communicates with this service using one or more login modules and is responsible for providing a callback handler that the login module can call to obtain the user name, password, and other relevant information.
The JAAS-compliant authentication service consists of one or more login modules along with logic to perform the needed authentication. The login module (LoginModule) may include the authentication logic itself, or it may use a private protocol or API to communicate with another module that provides the logic.
The JAAS configuration file is a text file that the JAAS client uses to locate the login module(s) for communicating with the authentication service.
Figure 9–2 shows how JAAS is used by the Message Queue broker. It shows a more complex implementation of the JAAS model shown in Figure 9–1.
As in the simpler case, the authentication service layer is separate from the broker. The authentication service consists of one or more login modules, along with additional authentication modules if needed. The login modules run in the same Java virtual machine as the broker. The Message Queue 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 to the login modules. The configuration file specifies the order in which the modules are to be used and some conditions for their use. When the broker starts up, JAAS locates the configuration file by consulting either the Java system property java.security.auth.login.config or the Java security properties file. It 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 modules will be used for authentication. As the figure shows, it is possible for the broker to use more than one login module. (The relation between the configuration file, the login module, and the broker is shown in Figure 9–3.)
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 this 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 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.
This section illustrates how the JAAS client, the login modules, and the JAAS configuration file are related and then describes the process required to set up JAAS-compliant authentication. The next figure shows the relation between the configuration file, the login module, and the broker.
As shown in the figure, the JAAS configuration file, MyJAASCFile.config contains references to several login modules, grouped in an entry point. The JAAS locates the configuration file by consulting the Java system property java.security.auth.login.config or the Java security properties file. The broker then determines which login modules to use by consulting the broker property imq.user_repository.jaas.name, which specifies the desired entry in the configuration file. The classes for those modules are found in the lib/ext directory.
To set up JAAS support for Message Queue, you must complete the following steps. (In a development environment all these steps might be done by the developer. In a production environment, the administrator would take over some of these tasks.)
Create one or more login module classes that implement the authentication service. The JAAS callback types that the broker supports are listed below.
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.
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.
The broker uses this callback to pass the value of imq.authentication.type to the authentication service when the TextInputCallback.getPrompt() is imq.authentication.type. Right now, the only possible value for this field is basic. This indicates Base-64 password encoding.
The broker uses this callback to pass to the authentication service the password specified by the Message Queue client when the connection was requested.
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.
Create a JAAS configuration file with entries that reference the login module classes and specify the location of this file to the Message Queue administrator. (The file can be located remotely, and its location can be specified with a URL.)
Note the name of the entry (that references the login implementation classes) in the JAAS configuration file.
Archive the classes that implement the login modules to a jar file, and place the jar file in the Message Queue lib/ext directory.
Configure the broker properties that relate to JAAS support. These are described in Table 9–4.
Set the following system property (to specify the location of the JAAS configuration file) when starting the broker.
java.security.auth.login.config=JAAS_Config_File_Location
For example, you can specify the configuration file 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.accesscontrol.type |
Set to file. |
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.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 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. |