Authentication Swiftlet

Overview

The Authentication Swiftlet serves as an authentication entity for a router network. SwiftMQ has a local authentication design where each router in a router network has to be a trusted router of the network.

Each router serves as an entry point to the whole network and can authenticate access to every available resource. The authentication takes place by the Authentication Swiftlet of the local router.

It is not possible to restrict the access between routers by asking a remote Authentication Swiftlet about specific grants (that would be too slow). Therefore, if one needs to connect routers that are not completely trusted, he has to use the JMS Bridge Swiftlet to connect these routers.

Authentication Changes since Release 12.2.0

Anonymous Client Access

In previous releases, anonymous clients could always connect to a router, even if authentication was enabled. But they required specific grants on resources (queues, topics) to perform any further action.

This has been changed with this release. Now, anonymous clients are not allowed to log in when authentication is enabled. There is no change for normal JMS connection as you have to specify username and password anyway if authentication is enabled.

However, there is a BREAKING change in JNDI connections. These are internally established over anonymous JMS connections. Since the default public group contains a grant on topic swiftmq.jndi, a JNDI lookup is possible.

This does not work with 12.2.0 anymore. You are now required to add a username and password to the JNDI-URL:

smqp://<username>:<password>@<host>:<port>

So before you upgrade:

• Verify authentication is enabled or disabled (default).

• If enabled, add username and password to the JNDI-URLs of your JMS clients.

A JNDI-URL with username and password works also in prior releases, so you can first change your clients and then do the upgrade.

Password Check Only

Since we now reject anonymous clients when authentication is enabled, we are now able to only perform the authentication by verifying the password and then let the client perform anything without specifying grants for resources. To enable this, add the following attributes to the Authentication Swiftlet configuration:

<swiftlet name="sys$authentication" authentication-enabled="true" password-check-only="true">

Users and Groups

The base of authentication is groups. Each group contains the grants of the resources (queues and topics). There are 2 predefined groups, admin and public. The admin group contains grants of the management queues for the router of the distribution.

The public group contains grants of the topic swiftmq.jndi to enable everybody to perform JNDI lookups. A user is assigned to exactly one group and receives all grants from this group.

There are 2 predefined users, admin with a password secret and anonymous without a password. If a user logs in without a user name (user name is null), the user anonymous will automatically be assigned by the system.

For each user, a host access list can be defined. This list contains entries in form of SQL-Like predicates. If a user logs in, his remote hostname is checked against this list. Access is denied if there is no match.

Authentication can be enabled/disabled as a whole. It is disabled per default.

Resource Limit Groups

Resource limit groups are assigned to users similar to authentication groups. There exists a resource limit group public which is used per default. The sense of this feature is to avoid resource exhaustion due to client programming mistakes like opening many QueueReceivers/TemporaryQueues etc without closing them.

A Resource Limit Group contains maximum values for connections, sessions, temp. queues, producers, and consumers. The limit for maximum connections is per user and the default is -1 (unlimited). The other values are on a per-connection-base and the default is 50/50/50/50. That means a client can create 50 sessions, 50 temp queues (TemporaryQueue/TemporaryTopic), 50 producers (QueueSender/TopicPublisher), and 50 consumers (QueueReceiver/TopicSubscriber) on each connection, being within the default limit. If the client attempts to create the 51st resource, it gets a JMSException with a message that the resource limit is exceeded.

An administrator can define additional resource limit groups with higher/lower maximum values and can assign them to users. Resource limit checks cannot be switched off.

Password Encryption

Per default the Authentication Swiftlet stores user passwords in the routerconfig.xml in clear text format. To change it, follow these instructions.

Encrypt Passwords with Jasypt

The Authentication Swiftlet uses Jasypt internally. To encrypt your passwords, please download it here.

After downloading, you need to unpack it. Got to the installation directory of Jasypt and then to the bin folder. Jasypt requires a master password to encrypt your passwords. Please choose one and keep it a secret. In the bin folder then execute either ./encrypt.sh or encrypt.bat. The following example uses the master password topsecret and encrypts the password secret:

./encrypt.sh input=secret password=topsecret

----ENVIRONMENT-----------------

Runtime: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.60-b23

----ARGUMENTS-------------------

input: secret
password: topsecret

----OUTPUT----------------------

1J0iuTNmbjuD7rzB2QNKMw==

Store this encrypted password in the routerconfig.xml:

<users>
    <user name="admin" group="admin" password="1J0iuTNmbjuD7rzB2QNKMw==">
        <host-access-list/>
    </user>
</users>

If you create a new user via SwiftMQ Explorer or CLI, use the encrypted passwords here too.

Tell the SwiftMQ Router to use encrypted Passwords

This is done by setting the system property swiftmq.auth.encrypted.passwords in the Router's start script to true. With SwiftMQ HA Router this must be done for both instances.

java -server -Xmx1024M -cp ../../jars/swiftmq.jar -Dswiftmq.auth.encrypted.passwords=true \
     com.swiftmq.Router ../../config/routerconfig.xml $1

Start the Router with the Master Password

The Authentication Swiftlet requires the master password which must be supplied via the environment variable SWIFTMQ_MASTER_PASSWORD. To ensure that the master password is not stored on disk, use the following method to start the Router (Unix, bash):

export SWIFTMQ_MASTER_PASSWORD=topsecret
./router &
unset SWIFTMQ_MASTER_PASSWORD

The admin sets the master password, starts the Router, and unsets it. This way, no information is stored on a disk.

Configuration

The configuration of the Authentication Swiftlet is defined within the element

      <swiftlet name="sys$authentication" .../>

of the router's configuration file.

Attributes of Element "swiftlet"

Definition

Values

Element List "groups", Parent Element: "swiftlet"

Authentication Group Definitions. This element list contains zero or more "group" elements with this template definition:

Definition

Element List "queue-grants", Parent Element: "group"

Queue Grant Definitions. This element list contains zero or more "queue-grant" elements with this template definition:

Definition

Values

Element List "topic-grants", Parent Element: "group"

Topic Grant Definitions. This element list contains zero or more "topic-grant" elements with this template definition:

Definition

Values

Element List "resource-limit-groups", Parent Element: "swiftlet"

Resource Limit Group Definitions. This element list contains zero or more "resource-limit-group" elements with this template definition:

Definition

Values

Element List "users", Parent Element: "swiftlet"

User Definitions. This element list contains zero or more "user" elements with this template definition:

Definition

Values

Element List "host-access-list", Parent Element: "user"

Host Access List Definitions. This element list contains zero or more "host-access-list" elements with this template definition:

Definition