Skip to main content

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.

  1. Create a config.yml (see Minimal config below).

  2. 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_attribute must 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_admin is 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 in admin_user_ids or authentik_group_pks_granting_bot_admin, or set admin_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*.yml is gitignored (only config.example.yml is 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

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)

Source distribution for onbot 0.1.0
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)

Table of built distributions (wheels) for onbot 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page