When a user attempts to connect to the broker, the broker authenticates the user by inspecting the name and password provided. The broker grants the connection if the name and password match those in a broker-specific user repository that each broker is configured to consult.
You are responsible for maintaining a list of users, their groups, and their passwords in a user repository. You can use a different user repository for each broker instance. This section explains how you create, populate, and manage that repository.
The repository can be one of the following types:
A flat-file repository that is shipped with Message QueueTM
This type of user repository is very easy to use. You can populate and manage the repository using the User Manager utility (imqusermgr). To enable authentication, you populate the user repository with each user’s name and password and the name of the user’s group.
For more information on setting up and managing the user repository, see Using a Flat-File User Repository
An LDAP server
This could be an existing or new LDAP directory server that uses the LDAP v2 or v3 protocol. It is not as easy to use as the flat-file repository, but it is more scalable, and therefore better for production environments.
If you are using an LDAP user repository, you use the tools provided by the LDAP vendor to populate and manage the user repository. For more information, see Using an LDAP Server for a User Repository.
Message Queue provides a flat-file user repository and a command line tool, the User Manager utility (imqusermgr), that you can use to populate and manage the flat-file user repository. The following sections describe the flat-file user repository and how you use the User Manager utility to populate and manage that repository.
The flat-file user repository is instance-specific. A default user repository (named passwd) is automatically created for each broker instance that you start. This user repository is placed in a directory identified by the name of the broker instance with which the repository is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):
…/instances/instanceName/etc/passwd
The repository is created with two entries. Each row of Table 7–1 shows an entry.
Table 7–1 Initial Entries in User Repository
User Name |
Password |
Group |
State |
---|---|---|---|
admin |
admin |
admin |
active |
guest |
guest |
anonymous |
active |
These initial entries allow the Message Queue broker to be used immediately after installation without intervention by the administrator:
The initial guest user entry allows clients to connect to a broker instance using the default guest user name and password.
The initial admin user entry lets you use imqcmd commands to administer a broker instance using the default admin user name and password. You should update this initial entry to change the password (see Changing the Default Administrator Password).
The following sections explain how you populate and manage a flat-file user repository.
The Message Queue User Manager utility (imqusermgr) lets you edit or populate a flat-file user repository. This section introduces the User Manager utility. Subsequent sections explain how you use the imqusermgr subcommands to accomplish specific tasks.
For full reference information about the imqusermgr command, see Chapter 13, Command Line Reference
Before using the User Manager, keep the following things in mind:
If a broker-specific user repository does not yet exist, you must start up the corresponding broker instance to create it.
The imqusermgr command has to be run on the host where the broker is installed.
You must have appropriate permissions to write to the repository,: namely, on Solaris and Linux, you must be the root user or the user who first created the broker instance.
Examples in the following sections assume the default broker instance.
The imqusermgr command has the subcommands add, delete, list, and update.
The add subcommand adds a user and associated password to the specified (or default) broker instance repository, and optionally specifies the user’s group. The subcommand syntax is as follows:
add [-i instanceName] -u userName -p passwd [-g group] [ -s]
The delete subcommand deletes the specified user from the specified (or default) broker instance repository. The subcommand syntax is as follows:
delete [-i instanceName] -u userName [ -s] [-f]
The list subcommand displays information about the specified user or all users in the specified (or default) broker instance repository. The subcommand syntax is as follows:
list [ -i instanceName] [-u userName]
The update subcommand updates the password and/or state of the specified user in the specified (or default) broker instance repository. The subcommand syntax is as follows:
update [ -i instanceName] -u userName -p passwd [ -a state] [-s] [ -f]
update [-i instanceName] -u userName -a state [-p passwd] [-s] [-f]
Table 7–2 lists the options to the imqusermgr command.
Table 7–2 imqusermgr Options
Option |
Description |
---|---|
-a activeState |
Specifies (true/false) whether the user’s state should be active. A value of true means that the state is active. This is the default. |
-f |
Performs action without user confirmation. |
-h |
Displays usage help. Nothing else on the command line is executed. |
-i instanceName |
Specifies the broker instance name to which the command applies. If not specified, the default instance name, imqbroker, is assumed. |
-p passwd |
Specifies the user’s password. |
-g group |
Specifies the user group. Valid values are admin, user, anonymous. |
-s |
Sets silent mode. |
-u userName |
Specifies the user name. |
-v |
Displays version information. Nothing else on the command line is executed. |
When adding a user entry to the user repository for a broker instance, you can specify one of three predefined groups: admin, user, or anonymous. If no group is specified, the default group user is assigned. Groups should be assigned as follows:
admin group. For broker administrators. Users who are assigned this group can, by default, configure, administer, and manage the broker. You can assign more than one user to the admin group.
user group. For normal (non-administration) Message Queue client users. Most client users are in the user group. By default, users in this group can produce messages to all topics and queues, consume messages from all topics and queues, and browse messages in any queue.
anonymous group. For Message Queue clients that do not want a user name that is known to the broker, possibly because the client application does not know of a real user name to use. This account is analogous to the anonymous account present in most FTP servers. You can assign only one user at a time to the anonymous group. You should restrict the access privileges of this group as compared to the user group or you should remove users from the group at deployment time.
To change a user’s group, you must delete the user entry and then add another entry for the user, specifying the new group.
You cannot rename or delete these system-created groups, or create new groups. However, you can specify access rules that define the operations that the members of that group can perform. For more information, see User Authorization: The Access Control Properties File.
When you add a user to a repository, the user’s state is active by default. To make the user inactive, you must use the update command. For example, the following command makes the user JoeD inactive:
imqusermgr update -u JoeD -a false
Entries for users that have been rendered inactive are retained in the repository; however, inactive users cannot open new connections. If a user is inactive and you add another user who has the same name, the operation will fail. You must delete the inactive user entry or change the new user’s name or use a different name for the new user. This prevents you from adding duplicate user names.
User names and passwords must follow these guidelines:
A user name cannot contain an asterisk (*), comma (,), colon (:), or a new-line or carriage-return character.
A user name or password must be at least one character long.
If a user name or password contains a space, the entire name or password must be enclosed in quotation marks.
There is no limit on the length of passwords or user names, except for command shell restrictions on the maximum number of characters that can be entered on a command line.
Use the add subcommand to add a user to a repository. For example, the following command adds the user Katharine with the password sesame to the default broker instance user repository.
imqusermgr add -u Katharine -p sesame -g user
Use the delete subcommand to delete a user from a repository. For example, the following command deletes the user, Bob:
imqusermgr delete -u Bob
Use the update subcommand to change a user’s password or state. For example, the following command changes Katharine’s password to aladdin:
imqusermgr update -u Katharine -p aladdin
To list information about one user or all users, use the list command. The following command shows information about the user named isa:
imqusermgr list -u isa
% imqusermgr list -u isa User repository for broker instance: imqbroker ---------------------------------- User Name Group Active State ---------------------------------- isa admin true |
The following command lists information about all users:
imqusermgr list
% imqusermgr list User repository for broker instance: imqbroker -------------------------------------- User Name Group Active State -------------------------------------- admin admin true guest anonymous true isa admin true testuser1 user true testuser2 user true testuser3 user true testuser4 user false testuser5 user false |
For the sake of security, you should change the default password of admin to one that is known only to you. The following command changes the default administrator password for the mybroker broker instance from admin to grandpoobah.
imqusermgr update mybroker -u admin -p grandpoobah
You can quickly confirm that this change is in effect by running any of the command line tools when the broker instance is running. For example, the following command will prompt you for a password:
imqcmd list svc mybroker -u admin
Entering the new password (grandpoobah) should work; the old password should fail.
After changing the password, you should supply the new password any time you use any of the Message Queue administration tools, including the Administration Console.
To use an LDAP server for a user repository, you perform the following tasks:
Editing the instance configuration file
Setting up access control for administrators
To have a broker use a directory server, you set the values for certain properties in the broker instance configuration file, config.properties. These properties enable the broker instance to query the LDAP server for information about users and groups whenever a user attempts to connect to the broker instance or perform messaging operations.
The instance configuration file is located in a directory under the broker instance directory. The path has the following format:
…/instances/instanceName /props/config.properties
For information about the operating system-specific location of instance directories, see Appendix A, Platform-Specific Locations of Message QueueTM Data
Specify that you are using an LDAP user repository by setting the following property:
imq.authentication.basic.user_repository=ldap |
Set the imq.authentication.type property to determine whether a password should be passed from client to broker in base-64 (basic ) or MD5 (digest) encoding. When using an LDAP directory server for a user repository, you must set the authentication type to basic . For example,
imq.authentication.type=basic |
You must also set the broker properties that control LDAP access. These properties are stored in a broker’s instance configuration file. The properties are discussed under Security Services and summarized under Security Properties.
Message Queue uses JNDI APIs to communicate with the LDAP directory server. Consult JNDI documentation for more information on syntax and on terms referenced in these properties. Message Queue uses a Sun JNDI LDAP provider and uses simple authentication.
Message Queue supports LDAP authentication failover: you can specify a list of LDAP directory servers for which authentication will be attempted (see the reference information for the imq.user.repos.ldap.server property).
See the broker’s config.properties file for a sample of how to set properties related to LDAP user-repository.
If necessary, you need to edit the users/groups and rules in the access control properties file. For more information about the use of access control property files, see User Authorization: The Access Control Properties File.
If you want the broker to communicate with the LDAP directory server over SSL during connection authentication and group searches, you need to activate SSL in the LDAP server and then set the following properties in the broker configuration file:
Specify the port used by the LDAP server for SSL communications. For example:
imq.user_repository.ldap.server=myhost:7878 |
Set the broker property imq.user_repository.ldap.ssl.enabled to true.
When employing multiple LDAP directory servers, use ldap:// to specify each additional directory server. For example:
imq.user_repository.ldap.server= myHost:7878 ldap:// otherHost:7878 …
Separate each additional directory server with a space. All directory servers in the list must use the same values for other LDAP-related properties.
To create administrative users, you use the access control properties 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 QueueTM 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] …]