JDBC Authentication Swiftlet

Overview

The JDBC Authentication Swiftlet provides authentication and authorization for SwiftMQ routers by integrating with an external relational database via JDBC. It manages user credentials, group memberships, resource grants, and resource limits, enforcing access control for queues and topics based on database-driven policies. This Swiftlet supports caching for improved performance and offers configurable retry mechanisms for database connectivity.

Features

JDBC-Based Authentication and Authorization

This Swiftlet authenticates users and authorizes operations by querying a relational database using configurable SQL statements. User credentials, group memberships, queue and topic grants, and resource limits are all retrieved from the database. The JDBC connection parameters (driver, URL, credentials) and SQL statements are fully configurable, allowing integration with a wide range of database schemas.

Authentication is enabled or disabled via the authentication-enabled property. When enabled, all client connections, queue/topic operations, and resource limits are enforced according to the database contents. The Swiftlet supports dynamic reloading of cache and retry logic for robust operation.

User Authentication

User credentials are validated by querying the database for the user's password using the SQL statement defined in user-select. Host-based access control is enforced by retrieving allowed host patterns from the database using hostaccesslist-select. Host predicates support SQL-LIKE wildcards (%).

Group and Resource Grants

Each user is associated with a group (from the authgroupname field). Queue and topic access rights are determined by group-based grants, queried using queuegrants-select and topicgrants-select. These grants specify permissions for browsing, sending, receiving (queues), and subscribing, publishing, durable creation (topics).

Resource Limit Enforcement

Resource limits (such as maximum connections, sessions, temporary queues, producers, and consumers) are enforced per user via resource limit groups, retrieved using resourcelimitgroups-select. The Swiftlet tracks connection counts and denies new connections if limits are exceeded.

Caching of Authentication Data

To reduce database load and improve performance, user, group, and resource limit data are cached in memory. The cache can be enabled or disabled via the enabled property under the cache entity. Cached entries expire after a configurable interval (expiration), after which they are refreshed from the database. Cache settings can be changed at runtime and take effect immediately.

JDBC Connection Management and Retry

The Swiftlet manages its JDBC connection with configurable retry logic. If the database becomes unavailable, it will attempt to reconnect up to retry-max times, waiting retry-interval milliseconds between attempts. These parameters are set under the jdbc-connection entity.

Configuration Example:

<swiftlet name="sys$authentication" authentication-enabled="true">
  <jdbc-connection driver-classname="com.mysql.cj.jdbc.Driver" url="jdbc:mysql://dbhost/swiftmq" username="swiftuser" password="secret" retry-interval="2000" retry-max="5"/>
  <statements schema-prefix="prod_"/>
  <cache enabled="true" expiration="60000"/>
</swiftlet>

Configuration Guide

Enable JDBC Authentication with Custom SQL and Caching

Use this scenario when you want to enforce authentication and authorization against a custom database schema, with caching enabled for performance.

1. Set authentication-enabled to true to activate authentication.
2. Configure the JDBC connection parameters (driver-classname, url, username, password) to match your database.
3. Optionally, set the schema-prefix and override SQL statements under the statements entity to match your schema.
4. Enable caching and set the desired expiration interval under the cache entity.

<swiftlet name="sys$authentication" authentication-enabled="true">
  <jdbc-connection driver-classname="org.postgresql.Driver" url="jdbc:postgresql://localhost/swiftmq" username="swift" password="mypassword"/>
  <statements schema-prefix="myapp_"/>
  <cache enabled="true" expiration="120000"/>
</swiftlet>

Disable Authentication (Allow All Connections)

Use this scenario for development or testing when authentication and authorization are not required.

1. Set authentication-enabled to false (the default).
2. No further configuration is needed; all connections and operations are permitted.

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

Configure JDBC Connection Retry Behavior

Use this scenario to control how the Swiftlet handles temporary database outages by adjusting retry parameters.

1. Set retry-interval to the desired wait time between connection attempts (in milliseconds).
2. Set retry-max to the maximum number of retry attempts before giving up.

<swiftlet name="sys$authentication">
  <jdbc-connection retry-interval="5000" retry-max="20"/>
</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

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

<jdbc-connection> Entity

JDBC Connection

This is a fixed child entity of <swiftlet name="sys$authentication">.

Parameter	Type	Default	Mandatory	Reboot Required	Description
driver-classname	String	—	Yes	Yes	Name of the JDBC Driver Class
url	String	—	Yes	Yes	JDBC URL
username	String	—	No	Yes	JDBC Username
password	String	—	No	Yes	JDBC Password
retry-interval	Long	1000	No	No	Retry Interval (0 disables retry)
retry-max	Integer	10	No	No	Maximum Retries (min: 1)

<swiftlet name="sys$authentication">
  <jdbc-connection driver-classname="..." url="..." username="..." password="..." retry-interval="..." retry-max="..."/>
</swiftlet>

<statements> Entity

SQL Statements

This is a fixed child entity of <swiftlet name="sys$authentication">.

Parameter	Type	Default	Mandatory	Reboot Required	Description
schema-prefix	String	—	No	Yes	Schema Prefix for Tables
user-select	String	select password,authgroupname,rlgroupname from ${schema-prefix}users where username = ?	No	Yes	Select a single User
hostaccesslist-select	String	select hostnamepredicate from ${schema-prefix}hostaccesslists where username = ?	No	Yes	Select Host Access List of a User
queuegrants-select	String	select queuename,browsegrant,sendgrant,receivegrant from ${schema-prefix}queuegrants where authgroupname = ?	No	Yes	Select Queue Grants of a Group
topicgrants-select	String	select topicname,subscribegrant,publishgrant,durablegrant from ${schema-prefix}topicgrants where authgroupname = ?	No	Yes	Select Topic Grants of a Group
resourcelimitgroups-select	String	select maxconnections,maxsessions,maxtempqueues,maxproducers,maxconsumers from ${schema-prefix}resourcelimitgroups where rlgroupname = ?	No	Yes	Select a Resource Limit Group

<swiftlet name="sys$authentication">
  <statements schema-prefix="..." user-select="..." hostaccesslist-select="..." queuegrants-select="..." topicgrants-select="..." resourcelimitgroups-select="..."/>
</swiftlet>

<cache> Entity

Cache

This is a fixed child entity of <swiftlet name="sys$authentication">.

Parameter	Type	Default	Mandatory	Reboot Required	Description
enabled	Boolean	true	No	No	Enabes/Disables Caching
expiration	Long	300000	No	No	A cached Entity expires after this time (ms) (min: 1000)

<swiftlet name="sys$authentication">
  <cache enabled="..." expiration="..."/>
</swiftlet>