User Authentication

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).
See Using a Flat-File User Repository.

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.
See Using an LDAP User Repository.

An external authentication mechanism plugged into Message Queue by
means of the Java Authentication and Authorization Service (JAAS)
API. See Using JAAS-Based Authentication.

Using a Flat-File User Repository

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:

User Groups and Status

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:

admin

For broker administrators. By default, users in this group
are granted the access privileges needed to configure, administer, and manage
message brokers.

user

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.

anonymous

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

Using the User Manager Utility

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.

User Manager Preliminaries

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.

Subcommands and General Options

Table 9–2 lists the subcommands
of the imqusermgr command. For full reference information
about these subcommands, see Table 16–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

Option

Description

-f

Perform action without user confirmation

-s

Silent mode (no output displayed)

-v

Display version information [Any other options specified on the command line are ignored. ]

-h

Display usage help

Displaying the Product Version

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.

Displaying Help

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.

Adding a User to the Repository

The subcommand imqusermgradd adds
an entry to the user repository, consisting of a user name and password:

imqusermgr add [-ibrokerName]
-uuserName-ppassword
[-ggroup]

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

Deleting a User From the Repository

The subcommand imqusermgrdelete deletes
a user entry from the repository:

imqusermgr delete [-ibrokerName]
-uuserName

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

Changing a User’s Password

You can use the subcommand imqusermgrupdate to
change a user’s password:

imqusermgr update [-ibrokerName]
-uuserName-ppassword

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

Note –

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.

Activating or Deactivating a User

The imqusermgrupdate subcommand
can also be used to change a user’s active status:

imqusermgr update [-ibrokerName]
-uuserName-aactiveStatus

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 imqusermgrupdate 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:

Using an LDAP User Repository

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 17–9 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

The imq.user_repository.ldap.userformat property,
if set to a value of dn, specifies that the login username
for authentication be in DN username format (for example: uid=mquser,ou=People,dc=red,dc=sun,dc=com). In this case, the broker extracts the value of the imq.user.repository.lpdap.uidatr attribute from the DN username, and uses this value as the user
name in access control operations (see User Authorization).

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.

For example, to create administrative users, you use the access control
file to specify those users and groups in the LDAP directory that can create ADMIN connections.

Any user or group that can create an ADMIN connection
can issue administrative commands.

To Set Up an Administrative User

The following procedure makes use of a broker's access control file,
which is described in User Authorization.

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.

To grant Message Queue administrator privileges to groups, enter
the group names as follows:

connection.ADMIN.allow.group=groupName[[,groupName2] …]

The groups must be defined in the LDAP directory.

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:

For complete information about the JAAS API, see the Java™ Authentication and Authorization
Service (JAAS) Reference Guide at the URL

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.

The JAAS client is an application wishing to perform authentication
using a JAAS-compliant authentication service. The JAAS
client communicates with the authentication 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
information needed for authentication.

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 an external security
service that provides the logic.

The JAAS configuration file is a text file that the JAAS client
uses to locate the login module(s) to be used.

Figure 9–2 JAAS Elements

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 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, Distribution-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

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.)

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.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 MessageTypeERROR,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 created in Step 1 and specify the
location of this file.

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

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

Set the broker configuration 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).

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.