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.

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==
CODE

Store this encrypted password in the routerconfig.xml:

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

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
CODE

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
CODE

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" .../>
XML

of the router's configuration file.

Attributes of Element "swiftlet"

Definition

Attribute

Type

Mandatory

Description

authentication-enabled

java.lang.Boolean

No

Enabes/Disables Authentication

password-check-only

java.lang.Boolean

No

If authentication is enabled, performs password checks only but not resource grants

Values

Attribute

Values

authentication-enabled

Default: false

password-check-only

Default: false

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

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

Definition

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this Group

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

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this Queue Grant

receive-grant

java.lang.Boolean

No

Grant to create a QueueReceiver on this Queue

send-grant

java.lang.Boolean

No

Grant to create a QueueSender on this Queue

browse-grant

java.lang.Boolean

No

Grant to create a QueueBrowser on this Queue

Values

Attribute

Values

receive-grant

Default: true

send-grant

Default: true

browse-grant

Default: true

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

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this Topic Grant

subscribe-grant

java.lang.Boolean

No

Grant to subscribe for this Topic

publish-grant

java.lang.Boolean

No

Grant to publish to this Topic

durable-grant

java.lang.Boolean

No

Grant to create a Durable Subscriber on this Topic

Values

Attribute

Values

subscribe-grant

Default: true

publish-grant

Default: true

durable-grant

Default: true

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

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this Resource Limit Group

max-connections

java.lang.Integer

Yes

Maximum Connections

max-tempqueues

java.lang.Integer

Yes

Maximum temp. Queues/Connection

max-sessions

java.lang.Integer

Yes

Maximum Sessions/Connection

max-producers

java.lang.Integer

Yes

Maximum Producers/Connection

max-consumers

java.lang.Integer

Yes

Maximum Consumers/Connection

Values

Attribute

Values

max-connections

Default: -1

max-tempqueues

Min: 1
Default: 50

max-sessions

Min: 1
Default: 50

max-producers

Min: 1
Default: 50

max-consumers

Min: 1
Default: 50

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

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

Definition

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this User

password

java.lang.String

No

Password

group

java.lang.String

Yes

Authentication Group

resource-limit-group

java.lang.String

Yes

Resource Limit Group

Values

Attribute

Values

password

group

Default: public

resource-limit-group

Default: public

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

Attribute

Type

Mandatory

Description

name

java.lang.String

Yes

Name of this Host Access List