Skip to content

Authentication Swiftlet

Overview

The Authentication Swiftlet manages user authentication and authorization within the SwiftMQ router. It controls user logins, password verification, resource access (queues and topics), and enforces resource limits per user or group. The Swiftlet supports flexible group-based access control, resource limit groups, and optional password encryption for enhanced security.

Features

User Authentication and Password Management

The Authentication Swiftlet verifies user credentials during connection establishment. Each user is defined with a password, which can be optionally encrypted using a master password set via the SWIFTMQ_MASTER_PASSWORD environment variable. If encrypted passwords are enabled (via the swiftmq.auth.encrypted.passwords system property), the master password must be provided at startup. The Swiftlet supports an anonymous user for unauthenticated access, but this can be disabled for security. Passwords can be updated dynamically, and changes take effect immediately.

Encrypted Passwords

When the swiftmq.auth.encrypted.passwords system property is set to true, user passwords must be stored in encrypted form. The master password for decryption is supplied via the SWIFTMQ_MASTER_PASSWORD environment variable. If the master password is not set, the Swiftlet will refuse to start when encrypted passwords are enabled.

Configuration Example:

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

Group-Based Access Control

Users are assigned to authentication groups, which define their access rights to queues and topics. Each group specifies a set of queue and topic grants, controlling whether members can send, receive, browse, publish, subscribe, or create durable subscriptions on specific resources. The system always ensures the existence of a public group, which can be used to define default grants for unauthenticated or fallback access. Resource grants can be dynamically added or removed, and changes are applied in real-time.

Queue Grants

Queue grants specify, per group, whether users can create QueueSender, QueueReceiver, or QueueBrowser objects on a given queue. Each grant is defined for a specific queue and can independently allow or deny send, receive, and browse operations.

Topic Grants

Topic grants specify, per group, whether users can publish, subscribe, or create durable subscribers on a given topic. Each grant is defined for a specific topic and can independently allow or deny publish, subscribe, and durable subscription operations.

Configuration Example:

<swiftlet name="sys$authentication">
  <groups>
    <group name="admins">
      <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 Groups

Resource limit groups define operational limits for users, such as the maximum number of connections, sessions, temporary queues, producers, and consumers allowed per user. Each user is assigned to a resource limit group, and these limits are enforced at runtime. The public resource limit group is always present to provide default limits for unauthenticated or fallback users.

Dynamic Enforcement

Limits are checked whenever a user attempts to create a new connection, session, producer, consumer, or temporary queue. If a limit is exceeded, the operation is denied and an exception is raised.

Configuration Example:

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

Host Access Control

Each user can have a host access list, specifying which client hostnames are permitted to authenticate as that user. Host access entries use SQL-LIKE predicates, with % as a wildcard, to match incoming hostnames. If a user's host access list is empty, all hosts are permitted. Host access lists can be updated dynamically.

Configuration Example:

<swiftlet name="sys$authentication">
  <users>
    <user name="alice" password="secret" group="admins" resource-limit-group="standard">
      <host-access-list>
        <host-access-list name="client1.example.com"/>
        <host-access-list name="10.%.%.%"/>
      </host-access-list>
    </user>
  </users>
</swiftlet>

Authentication Modes and Delegation

Authentication can be globally enabled or disabled via the authentication-enabled property. When enabled, the Swiftlet can operate in 'password check only' mode, where only password verification is performed and resource grants are not enforced. The Swiftlet also supports pluggable authentication delegates for topic access, allowing external modules to override or extend topic authorization logic.

Password Check Only Mode

When password-check-only is set to true, the Swiftlet verifies user passwords but does not enforce queue or topic resource grants. This mode is useful for environments where only authentication is required, and all users should have unrestricted resource access.

Authentication Delegates

External modules can register AuthenticationDelegate implementations to provide custom authorization logic for topic send, receive, and durable subscription operations. If any delegate grants access, the operation is permitted regardless of group/topic grants.

Configuration Example:

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

Configuration Guide

Enable Authentication with Custom Groups and Limits

Use this scenario to enforce authentication, define custom user groups with specific queue/topic access, and set operational limits for users.

  1. Set authentication-enabled to true on the sys$authentication Swiftlet.
  2. Define groups with appropriate queue and topic grants.
  3. Define resource-limit-groups with desired limits.
  4. Create users, assigning each to a group and resource limit group.
<swiftlet name="sys$authentication" authentication-enabled="true">
  <groups>
    <group name="operators">
      <queue-grants>
        <queue-grant name="orders" send-grant="true" receive-grant="false" browse-grant="true"/>
      </queue-grants>
      <topic-grants>
        <topic-grant name="alerts" publish-grant="false" subscribe-grant="true" durable-grant="false"/>
      </topic-grants>
    </group>
  </groups>
  <resource-limit-groups>
    <resource-limit-group name="ops-limits" max-connections="2" max-sessions="5" max-tempqueues="2" max-producers="5" max-consumers="5"/>
  </resource-limit-groups>
  <users>
    <user name="bob" password="pw123" group="operators" resource-limit-group="ops-limits"/>
  </users>
</swiftlet>

Restrict User Logins by Hostname

Apply this scenario to limit which client hosts can authenticate as a given user, enhancing security by restricting access to known hosts.

  1. Edit the user's host-access-list to include only allowed hostnames or patterns.
  2. Leave the list empty to allow all hosts.
<swiftlet name="sys$authentication">
  <users>
    <user name="carol" password="pw456" group="public" resource-limit-group="public">
      <host-access-list>
        <host-access-list name="192.168.1.%"/>
      </host-access-list>
    </user>
  </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>