Onbot
Onbot keeps a Matrix (Synapse) homeserver in sync with an Authentik identity provider and gives every new user a friendly welcome into the right rooms.
Authentik is the source of truth. Onbot mirrors it into Matrix: each Authentik group becomes a room, group membership becomes room membership, and roles become power levels. When a new user shows up, they get a guided 1:1 welcome message.
Onbot is built for Matrix 2.0. It assumes a Matrix Authentication Service (MAS) deployment with Authentik as the upstream identity provider.
What Onbot does and does not do
Onbot does not create accounts. MAS provisions a Matrix account the first time a user logs in through Authentik. Onbot's job is projection: turn Authentik groups into rooms, group membership into room membership, attributes into power levels, and drive the offboarding lifecycle when a user is disabled.
Quick start with Docker
The published image is dzdde/onbot on Docker Hub. It runs
as a non-root user and needs one thing from you: a config file.
-
Create a
config.yml(see Minimal config below). -
Run it:
docker run --rm \
-v "$PWD/config.yml:/config/config.yml:ro" \
dzdde/onbot:X.Y.Z
Replace X.Y.Z with a released version (see CHANGELOG.md and the
tags); do not run latest for a bot that can kick users
and lock accounts. The image defaults to reading /config/config.yml and running the long-lived
onbot run service. It also ships a built-in HEALTHCHECK.
docker-compose
services:
onbot:
image: dzdde/onbot:X.Y.Z
restart: unless-stopped
volumes:
- ./config.yml:/config/config.yml:ro
More deployment detail (env-only config, CLI commands, healthcheck) lives in docs/deployment.md.
Minimal config
Configuration is a single YAML file. Copy this, fill in the values, save it as config.yml:
synapse_server:
server_name: company.org # your Matrix domain (the part after the ':')
server_url: https://internal.matrix # how the bot reaches Synapse (an internal URL is fine)
bot_user_id: "@welcome-bot:company.org"
bot_access_token: syt_REPLACE_ME # a MAS compatibility token (scripts/provision-bot-account.sh)
authentik_server:
url: https://authentik.company.org/
api_key: REPLACE_ME # an Authentik API token
# Required to enforce offboarding under MAS (omit on non-MAS deployments):
mas_admin:
url: https://auth.company.org # the MAS base URL
client_id: REPLACE_ME # a MAS admin client (in policy.data.admin_clients)
client_secret: REPLACE_ME
sync_authentik_users_with_matrix_rooms:
authentik_username_mapping_attribute: username # MUST agree with MAS's localpart template
# The admin control room is on by default and needs at least one admin (or `enabled: false`):
admin_room:
admin_user_ids: ["@alice:company.org"] # and/or authentik_group_pks_granting_bot_admin
Two settings above are easy to get wrong and worth calling out:
authentik_username_mapping_attributemust match the localpart template MAS uses. Onbot computes each user's MXID from this Authentik attribute. If it disagrees with MAS, the computed MXIDs will not match the real accounts and nobody gets added to rooms.mas_adminis required to actually offboard disabled users. The Synapse admin API cannot end a MAS-issued session, only MAS can. Without this block, offboarding does nothing to live sessions, so on a MAS-backed homeserver without it Onbot refuses to lock or erase anybody and reports that at startup (onboarding and rooms keep working).- The admin control room needs an admin. It is where Onbot reports what needs a human and where
an admin releases paused mass removals with
!confirm <id>. List at least one admin inadmin_user_idsorauthentik_group_pks_granting_bot_admin, or setadmin_room.enabled: false; otherwise Onbot refuses to start.
Every setting can also be supplied via an environment variable (prefix ONBOT_, nest with __),
for example ONBOT_SYNAPSE_SERVER__BOT_ACCESS_TOKEN=syt_….
Never commit a real config.
config*.ymlis gitignored (onlyconfig.example.ymlis tracked) and the image carries no secrets. Provide config at runtime.
For the full picture (bot credential options, the MAS auth topology, and every field), see the docs below.
Turning Authentik groups into rooms
The config above connects the bot. What actually creates rooms is your Authentik groups: which ones are opted in, and what you put in each group's Attributes box (topic, icon, power level, lobby).
docs/authentik-groups.md is the single page for that, written from the Authentik side, with every group attribute Onbot reads, its legal values, and the config field that renames it.
Documentation
- docs/authentik-groups.md is the group-to-room guide: how to opt a group in and every attribute you can set on it in Authentik.
- docs/features.md explains, in plain language, what each Onbot feature does, for both users and admins.
- docs/configuration.md walks through every config block, the bot credential choices, and how to generate the reference.
- docs/CONFIG_REFERENCE.md lists every field, its type, default,
description, and
ONBOT_*env-var name (generated from the model). - docs/deployment.md covers running with Docker and compose, env-only config, the CLI commands, the healthcheck, and upgrading from the legacy bot.
- docs/architecture.md explains the Matrix client to MAS to Authentik auth topology and links the architecture decision records.
- docs/development.md is the setup, build, and release guide for contributors.
- docs/testing.md describes the unit, contract, and integration suites.
- docs/troubleshooting.md is a symptom to cause table for common issues.
- docs/project/GOALS.md captures project intent and docs/project/BATTLE_PLAN.md the build plan.
License
MIT, see LICENSE.
Metadata
Release files for onbot 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| onbot-0.1.0.tar.gz | 245.1 kB | Without provenance | Details for onbot-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| onbot-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for onbot-0.1.0-py3-none-any.whl |
Total release size: 520.4 kB
Release files / onbot-0.1.0.tar.gz
| Download URL | onbot-0.1.0.tar.gz |
|---|---|
| Size | 245.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
335ec8b819dc7eeed7ef835e8559df9fcbd3ba5793fcf3212e4f264f69750659
|
|
BLAKE2b-256 checksum How to use checksums |
95ac38b7898c1a51722ae75a653910e480833ed1ee9dcd8b67aa9f6941731cf2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / onbot-0.1.0-py3-none-any.whl
| Download URL | onbot-0.1.0-py3-none-any.whl |
|---|---|
| Size | 275.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a7a0d405af5325d98b435ef8482cba287ab6248a046b75da7ed503a912e670e0
|
|
BLAKE2b-256 checksum How to use checksums |
d00c8527962987a3e4e653a91740cadcdae6c047f69d483e6c3b78423d7f1b06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for onbot 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.