Skip to content

Relational Database for Authentication and Authorization¤

  • amqtt.contrib.auth_db.UserAuthDBPlugin (authentication) verify a client's ability to connect to broker
  • amqtt.contrib.auth_db.TopicAuthDBPlugin (authorization) determine a client's access to topics

Relational database access is supported using SQLAlchemy so MySQL, MariaDB, Postgres and SQLite support is available.

For ease of use, the user_mgr command-line utility to add, remove, update and list clients. And the topic_mgr command-line utility to add client access to subscribe, publish and receive messages on topics.

Authentication Configuration¤

Config dataclass ¤

Configuration for DB authentication.

connection instance-attribute ¤
connection: str

SQLAlchemy connection string for the asyncio version of the database connector:

  • mysql+aiomysql://user:password@host:port/dbname
  • postgresql+asyncpg://user:password@host:port/dbname
  • sqlite+aiosqlite:///dbfilename.db
hash_schemes class-attribute instance-attribute ¤
hash_schemes: list[str] = [
    "argon2",
    "bcrypt",
    "pbkdf2_sha256",
    "scrypt",
]

list of hash schemes to use for passwords

sync_schema class-attribute instance-attribute ¤
sync_schema: bool = False

Use SQLAlchemy to create / update the database schema.

Authorization Configuration¤

Config dataclass ¤

Configuration for DB topic filtering.

connection instance-attribute ¤
connection: str

SQLAlchemy connection string for the asyncio version of the database connector:

  • mysql+aiomysql://user:password@host:port/dbname
  • postgresql+asyncpg://user:password@host:port/dbname
  • sqlite+aiosqlite:///dbfilename.db
sync_schema class-attribute instance-attribute ¤
sync_schema: bool = False

Use SQLAlchemy to create / update the database schema.

CLI¤

user_mgr¤

Command line interface to list, create, remove and add clients.

Passwords are not allowed to be passed via the command line for security reasons. You will be prompted for database password (if applicable) and the client id's password.

If you need to create users programmatically, see amqtt.contrib.auth_db.managers.UserManager which provides the underlying functionality to this command line interface.

Usage:

console $ user_mgr [OPTIONS] COMMAND [ARGS]...

Options:

  • -d, --db [mariadb|mysql|postgresql|sqlite]: db type [required]
  • -u, --username TEXT: db username
  • -p, --port INTEGER: database port (defaults to db type)
  • -h, --host TEXT: database host [default: localhost]
  • -f, --file TEXT: database file name (sqlite only) [default: auth.db]
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • sync: Create the table and schema for username...
  • list: List all Client IDs (in alphabetical order).
  • add: Create a new user with a client id and...
  • rm: Remove a client from the authentication...
  • pwd: Update a user's password (prompted).

user_mgr sync¤

Create the table and schema for username and hashed password.

Non-destructive if run multiple times. To clear the whole table, need to drop it manually.

Usage:

console $ user_mgr sync [OPTIONS]

Options:

  • --help: Show this message and exit.

user_mgr list¤

List all Client IDs (in alphabetical order). Will also display the hashed passwords.

Usage:

console $ user_mgr list [OPTIONS]

Options:

  • --help: Show this message and exit.

user_mgr add¤

Create a new user with a client id and password (prompted).

Usage:

console $ user_mgr add [OPTIONS]

Options:

  • -c, --client-id TEXT: id for the new client [required]
  • --help: Show this message and exit.

user_mgr rm¤

Remove a client from the authentication database.

Usage:

console $ user_mgr rm [OPTIONS]

Options:

  • -c, --client-id TEXT: id for the client to remove [required]
  • --help: Show this message and exit.

user_mgr pwd¤

Update a user's password (prompted).

Usage:

console $ user_mgr pwd [OPTIONS]

Options:

  • -c, --client-id TEXT: id for the new client [required]
  • --help: Show this message and exit.

topic_mgr¤

Command line interface to add / remove topic authorization.

Passwords are not allowed to be passed via the command line for security reasons. You will be prompted for database password (if applicable).

If you need to create users programmatically, see amqtt.contrib.auth_db.managers.TopicManager which provides the underlying functionality to this command line interface.

Usage:

console $ topic_mgr [OPTIONS] COMMAND [ARGS]...

Options:

  • -d, --db [mariadb|mysql|postgresql|sqlite]: db type [required]
  • -u, --username TEXT: db username
  • -p, --port INTEGER: database port (defaults to db type)
  • -h, --host TEXT: database host [default: localhost]
  • -f, --file TEXT: database file name (sqlite only) [default: auth.db]
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • sync: Create the table and schema for username...
  • list: List all Client IDs (in alphabetical order).
  • add: Create a new user with a client id and...
  • rm: Remove a client from the authentication...

topic_mgr sync¤

Create the table and schema for username and topic lists for subscribe, publish or receive.

Non-destructive if run multiple times. To clear the whole table, need to drop it manually.

Usage:

console $ topic_mgr sync [OPTIONS]

Options:

  • --help: Show this message and exit.

topic_mgr list¤

List all Client IDs (in alphabetical order). Will also display the hashed passwords.

Usage:

console $ topic_mgr list [OPTIONS]

Options:

  • --help: Show this message and exit.

topic_mgr add¤

Create a new user with a client id and password (prompted).

Usage:

console $ topic_mgr add [OPTIONS] TOPIC

Arguments:

  • TOPIC: list of topics [required]

Options:

  • -c, --client-id TEXT: id for the client [required]
  • -a, --action [subscribe|publish|receive]: action for topic to allow [required]
  • --help: Show this message and exit.

topic_mgr rm¤

Remove a client from the authentication database.

Usage:

console $ topic_mgr rm [OPTIONS] TOPIC

Arguments:

  • TOPIC: list of topics [required]

Options:

  • -c, --client-id TEXT: id for the client to remove [required]
  • -a, --action [subscribe|publish|receive]: action for topic to allow [required]
  • --help: Show this message and exit.