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']

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.

Implementation does not include any password validation.

Use NIST or other password guidelines when calling functions that set or update passwords.

Usage:

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

Options:

  • -d, --db : db type [required]
  • -u, --username : db username
  • -p, --port : database port (defaults to db type)
  • -h, --host : database host [default: localhost]
  • -f, --file : 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 : 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 : 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 : 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 : db type [required]
  • -u, --username : db username
  • -p, --port : database port (defaults to db type)
  • -h, --host : database host [default: localhost]
  • -f, --file : 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 : id for the client [required]
  • -a, --action : 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 : id for the client to remove [required]
  • -a, --action : action for topic to allow [required]
  • --help: Show this message and exit.

Managers¤

UserManager ¤

UserManager(connection: str)

Interface to create, retrieve, update, validate, and delete users.

Hashes passwords using passlib.context.CryptContext.

Implementation does not include any password validation.

Use NIST or other password guidelines when calling functions that set or update passwords.

Methods:

close async ¤
close() -> None

Dispose the database engine.

create_user_auth async ¤
create_user_auth(
    username: str, plain_password: str
) -> UserAuth | None

Create a new user.

db_sync async ¤
db_sync() -> None

Sync the database schema.

delete_user_auth async ¤
delete_user_auth(username: str) -> UserAuth | None

Delete a user.

get_user_auth async ¤
get_user_auth(username: str) -> UserAuth | None

Retrieve a user by username.

Use UserAuth.verify_password to verify password match.

list_user_auths async ¤
list_user_auths() -> Iterator[UserAuth]

Return list of all clients.

update_user_auth_password async ¤
update_user_auth_password(
    username: str, plain_password: str
) -> UserAuth | None

Change a user's password.

verify_user_auth_password async ¤
verify_user_auth_password(
    username: str, plain_password: str
) -> bool

Verify a user's password and persist any password hash upgrade.