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 en 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 are 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
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 of this group.
There are 2 predefined
users, admin with 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.
To 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 host name is checked against this list. The 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 51th 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 it 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 download 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 chose one and keep it secret.
In the bin folder then execute either ./encrypt.sh or encrypt.bat.
The following example uses master password topsecret and encrypts
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 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 disk.
Configuration
The configuration of the Authentication Swiftlet is defined within the element
<swiftlet name="sys$authentication" .../>
of the router's configuration file. One can use the SwiftMQ Exlorer or CLI for configuration as well. They both save into that 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 |