Skip to content

Authentication Swiftlet

Overview

The Authentication Swiftlet manages user authentication and authorization within the SwiftMQ router. It controls access to queues and topics, enforces resource limits per user, and supports fine-grained permissions through groups and grants. This Swiftlet is responsible for validating user credentials, restricting host access, and applying resource usage limits to ensure secure and controlled messaging operations.

Features

User Authentication and Password Management

The Authentication Swiftlet authenticates users based on configured credentials. Each user is defined with a username and password, and can be assigned to a group and a resource limit group. Passwords can be stored in plain text or encrypted form. If password encryption is enabled (via the system property swiftmq.auth.encrypted.passwords), the master password must be supplied through the SWIFTMQ_MASTER_PASSWORD environment variable. The Swiftlet supports an anonymous user for unauthenticated access, but this can be disabled by configuration.

Encrypted Password Support

When the system property swiftmq.auth.encrypted.passwords is set to true, user passwords must be encrypted. The master password for decryption is provided via the SWIFTMQ_MASTER_PASSWORD environment variable. If this variable is not set when encryption is enabled, the Swiftlet will fail to start.

Host Access Control

Each user can have a host access list, specifying allowed hostnames or address patterns (using SQL-LIKE % wildcards). If the list is empty, access is allowed from any host. If specified, only matching hosts are permitted for login.

Configuration Example:

<swiftlet name="sys$authentication">
  <users>
    <user name="alice" password="secret" group="admin" resource-limit-group="default">
      <host-access-list>
        <host-access-list name="192.168.1.%"/>
      </host-access-list>
    </user>
  </users>
</swiftlet>

Group-Based Access Control

Authorization is managed through groups, which define sets of permissions (grants) for queues and topics. Each user is assigned to a group, which determines their allowed operations. Groups can specify which queues and topics users can send to, receive from, browse, publish, or subscribe to. There is always a special public group, which acts as a fallback for permissions not explicitly granted in a user's group.

Queue Grants

Queue grants control whether users in a group can send to, receive from, or browse specific queues. Each grant can be set independently for each queue. If a user's group does not grant access to a queue, the Swiftlet checks the public group for fallback permissions.

Topic Grants

Topic grants control whether users in a group can publish to, subscribe to, or create durable subscribers for specific topics. As with queues, if a user's group does not grant access, the public group is checked for fallback permissions.

Configuration Example:

<swiftlet name="sys$authentication">
  <groups>
    <group name="admin">
      <queue-grants>
        <queue-grant name="orders" send-grant="true" receive-grant="true" browse-grant="true"/>
      </queue-grants>
      <topic-grants>
        <topic-grant name="news" publish-grant="true" subscribe-grant="true" durable-grant="true"/>
      </topic-grants>
    </group>
  </groups>
</swiftlet>

Resource Limit Enforcement

Resource limits restrict the number of connections, sessions, temporary queues, producers, and consumers that a user can create. Resource limits are defined in resource limit groups, and each user is assigned to one such group. The Swiftlet enforces these limits at runtime, preventing users from exceeding their allocated resources. There is always a public resource limit group as a fallback.

Resource Limit Group Properties

Each resource limit group defines maximum values for connections (max-connections), sessions per connection (max-sessions), temporary queues per connection (max-tempqueues), producers per connection (max-producers), and consumers per connection (max-consumers). A value of -1 for max-connections means unlimited connections.

Configuration Example:

<swiftlet name="sys$authentication">
  <resource-limit-groups>
    <resource-limit-group name="default" max-connections="10" max-sessions="20" max-tempqueues="5" max-producers="10" max-consumers="10"/>
  </resource-limit-groups>
</swiftlet>

Authentication Modes and Delegation

Authentication can be enabled or disabled globally using the authentication-enabled property. When enabled, the Swiftlet can operate in a special 'password check only' mode, where only password validation is performed and resource grants are not enforced. Additionally, the Swiftlet supports authentication delegates for topics, allowing external modules to participate in topic authorization decisions.

Password Check Only Mode

When password-check-only is set to true, the Swiftlet only checks user credentials but does not enforce group or resource grants. This is useful for scenarios where external authorization is handled elsewhere.

Topic Authentication Delegates

External modules can register as authentication delegates to participate in topic send/receive/durable authorization. If any delegate grants access, the operation is allowed regardless of group grants.

Configuration Example:

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

Configuration Guide

Restricting a User to a Specific Queue and Host

Use this scenario to allow a user to send and receive messages only on a specific queue and only from a specific host or subnet.

  1. Define a group with queue grants for the allowed queue.
  2. Create a user assigned to this group.
  3. Specify the allowed host pattern in the user's host access list.
<swiftlet name="sys$authentication">
  <groups>
    <group name="restricted">
      <queue-grants>
        <queue-grant name="orders" send-grant="true" receive-grant="true" browse-grant="false"/>
      </queue-grants>
      <topic-grants/>
    </group>
  </groups>
  <users>
    <user name="bob" password="bobpass" group="restricted" resource-limit-group="public">
      <host-access-list>
        <host-access-list name="10.0.0.%"/>
      </host-access-list>
    </user>
  </users>
</swiftlet>

Enabling Authentication and Setting Resource Limits

Enable authentication for the router and set specific resource limits for all users.

  1. Set the authentication-enabled attribute to true on the Authentication Swiftlet.
  2. Define a resource limit group with desired limits.
  3. Assign users to this resource limit group.
<swiftlet name="sys$authentication" authentication-enabled="true">
  <resource-limit-groups>
    <resource-limit-group name="limited" max-connections="5" max-sessions="10" max-tempqueues="2" max-producers="5" max-consumers="5"/>
  </resource-limit-groups>
  <users>
    <user name="carol" password="carolpass" group="public" resource-limit-group="limited"/>
  </users>
</swiftlet>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$authentication">.

<swiftlet name="sys$authentication"> Properties

These properties are attributes of the <swiftlet name="sys$authentication"> entity.

Parameter Type Default Mandatory Reboot Required Description
authentication-enabled Boolean false No No Enabes/Disables Authentication
password-check-only Boolean false No No If authentication is enabled, performs password checks only but not resource grants 
<swiftlet name="sys$authentication" authentication-enabled="false" password-check-only="false"/>

<groups> in <swiftlet name="sys$authentication">

Authentication Group Definitions

Each <group> entry is identified by its name attribute (the Group).

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

<queue-grants> in <groups>

Queue Grant Definitions

Each <queue-grant> entry is identified by its name attribute (the Queue Grant).

Parameter Type Default Mandatory Reboot Required Description
receive-grant Boolean true No No Grant to create a QueueReceiver on this Queue
send-grant Boolean true No No Grant to create a QueueSender on this Queue
browse-grant Boolean true No No Grant to create a QueueBrowser on this Queue 
<swiftlet name="sys$authentication">
  <groups>
    <group name="...">
      <queue-grants>
        <queue-grant name="..."/>
      </queue-grants>
    </group>
  </groups>
</swiftlet>

<topic-grants> in <groups>

Topic Grant Definitions

Each <topic-grant> entry is identified by its name attribute (the Topic Grant).

Parameter Type Default Mandatory Reboot Required Description
subscribe-grant Boolean true No No Grant to subscribe for this Topic
publish-grant Boolean true No No Grant to publish to this Topic
durable-grant Boolean true No No Grant to create a Durable Subscriber on this Topic 
<swiftlet name="sys$authentication">
  <groups>
    <group name="...">
      <topic-grants>
        <topic-grant name="..."/>
      </topic-grants>
    </group>
  </groups>
</swiftlet>

<resource-limit-groups> in <swiftlet name="sys$authentication">

Resource Limit Group Definitions

Each <resource-limit-group> entry is identified by its name attribute (the Resource Limit Group).

Parameter Type Default Mandatory Reboot Required Description
max-connections Integer -1 Yes No Maximum Connections
max-tempqueues Integer 50 Yes No Maximum temp. Queues/Connection (min: 1)
max-sessions Integer 50 Yes No Maximum Sessions/Connection (min: 1)
max-producers Integer 50 Yes No Maximum Producers/Connection (min: 1)
max-consumers Integer 50 Yes No Maximum Consumers/Connection (min: 1) 
<swiftlet name="sys$authentication">
  <resource-limit-groups>
    <resource-limit-group name="..." max-connections="..." max-tempqueues="..." max-sessions="..." max-producers="..." max-consumers="..."/>
  </resource-limit-groups>
</swiftlet>

<users> in <swiftlet name="sys$authentication">

User Definitions

Each <user> entry is identified by its name attribute (the User).

Parameter Type Default Mandatory Reboot Required Description
password String — No No Password
group String public Yes No Authentication Group
resource-limit-group String public Yes No Resource Limit Group 
<swiftlet name="sys$authentication">
  <users>
    <user name="..." group="..." resource-limit-group="..."/>
  </users>
</swiftlet>

<host-access-list> in <users>

Host Access List Definitions

Each <host-access-list> entry is identified by its name attribute (the Host Access List).

<swiftlet name="sys$authentication">
  <users>
    <user name="...">
      <host-access-list>
        <host-access-list name="..."/>
      </host-access-list>
    </user>
  </users>
</swiftlet>