JDBC Authentication Swiftlet

Overview

The JDBC Authentication Swiftlet provides user authentication and authorization for SwiftMQ routers by integrating with an external relational database via JDBC. It retrieves user credentials, group memberships, resource grants, and resource limits from configurable SQL queries, enabling centralized and dynamic management of access control. The Swiftlet supports caching and robust connection retry mechanisms for high availability.

Features

JDBC-Based Authentication and Authorization

This Swiftlet authenticates users and authorizes their actions by querying a relational database using JDBC. User credentials, group assignments, queue and topic permissions, and resource limits are all managed externally in the database. The Swiftlet executes configurable SQL statements to retrieve this information, enabling centralized, dynamic, and scalable access control.

Authentication involves verifying user credentials (username and password) against the database. Authorization checks are performed for each operation (such as sending/receiving messages, browsing queues, or creating durable subscriptions) by evaluating group-based grants for queues and topics. Resource limits (such as maximum connections, sessions, or temporary queues) are enforced per user based on their associated resource limit group.

Configurable SQL Statements

All SQL queries used for authentication and authorization are fully configurable via the Swiftlet's configuration. This includes queries for user lookup, host access list, queue grants, topic grants, and resource limit groups. The configuration supports a schema prefix variable, allowing easy adaptation to different database schemas.

Host Access Control

Each user may have a host access list, defined as predicates (with % wildcards) that restrict which client hosts are allowed to authenticate as that user. If no host predicates are defined, all hosts are allowed.

Queue and Topic Resource Grants

Group-based grants determine which queues and topics a user can access, and with what permissions (send, receive, browse for queues; publish, subscribe, create durable for topics). These grants are retrieved from the database and enforced for each operation.

Resource Limit Enforcement

Resource limits (such as maximum connections, sessions, temporary queues, producers, and consumers) are enforced per user based on their assigned resource limit group, as defined in the database.

Configuration Example:

<swiftlet name="sys$authentication" authentication-enabled="true">
  <jdbc-connection driver-classname="com.mysql.cj.jdbc.Driver" url="jdbc:mysql://localhost:3306/swiftmq_auth" username="swiftmq" password="secret"/>
  <statements schema-prefix="auth_"/>
  <cache enabled="true" expiration="60000"/>
</swiftlet>

Connection Management and Retry

The Swiftlet manages the lifecycle of the JDBC connection, including automatic reconnection and retry logic in case of failures. Connection parameters such as driver class name, JDBC URL, credentials, retry interval, and maximum retries are configurable. If the database connection is lost, the Swiftlet will attempt to reconnect according to the configured retry policy, ensuring high availability for authentication services.

Configuration Example:

<swiftlet name="sys$authentication">
  <jdbc-connection retry-interval="5000" retry-max="20"/>
</swiftlet>

Authentication and Authorization Caching

To improve performance and reduce database load, the Swiftlet supports caching of user, group, and resource limit group information. The cache can be enabled or disabled, and the expiration time for cached entries is configurable. When enabled, authentication and authorization data is cached for the specified duration, after which entries are refreshed from the database. Disabling the cache forces all checks to query the database directly.

Configuration Example:

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

Configuration Guide

Enable JDBC Authentication with Custom SQL and Caching

Use this scenario to enable JDBC-based authentication, specify a schema prefix for your database tables, and set a custom cache expiration time for authentication data.

1. Set authentication-enabled to true to activate authentication.
2. Configure the JDBC connection parameters (driver-classname, url, username, password).
3. Set the schema-prefix property under statements to match your database schema.
4. Adjust the cache expiration as needed.

<swiftlet name="sys$authentication" authentication-enabled="true">
  <jdbc-connection driver-classname="org.postgresql.Driver" url="jdbc:postgresql://dbhost:5432/swiftmq" username="swiftuser" password="swiftpass"/>
  <statements schema-prefix="prod_"/>
  <cache expiration="120000"/>
</swiftlet>

Disable Authentication (Allow All Connections)

Use this scenario to disable authentication, allowing all clients to connect without credential checks. This is typically used for development or testing environments.

1. Set authentication-enabled to false.

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

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>