{"id":21676166,"url":"https://github.com/sapucc/inviterbot","last_synced_at":"2025-04-12T05:07:50.051Z","repository":{"id":53839502,"uuid":"521606314","full_name":"SAPUCC/inviterbot","owner":"SAPUCC","description":"A maubot plugin to sync users from Azure AD and LDAP into matrix rooms","archived":false,"fork":false,"pushed_at":"2023-11-27T08:00:35.000Z","size":83,"stargazers_count":10,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T11:48:48.919Z","etag":null,"topics":["azuread","ldap","matrix","maubot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SAPUCC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-08-05T11:06:25.000Z","updated_at":"2025-03-28T18:43:50.000Z","dependencies_parsed_at":"2023-11-27T08:47:53.308Z","dependency_job_id":null,"html_url":"https://github.com/SAPUCC/inviterbot","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAPUCC%2Finviterbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAPUCC%2Finviterbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAPUCC%2Finviterbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAPUCC%2Finviterbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SAPUCC","download_url":"https://codeload.github.com/SAPUCC/inviterbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519543,"owners_count":21117761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azuread","ldap","matrix","maubot"],"created_at":"2024-11-25T14:12:26.830Z","updated_at":"2025-04-12T05:07:50.011Z","avatar_url":"https://github.com/SAPUCC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub release (latest by date)](https://img.shields.io/github/v/release/SAPUCC/inviterbot)\n\n# Maubot Inviterbot for Azure AD and LDAP\nA [maubot](https://github.com/maubot) plugin that syncs user-groups from an identity management like Microsoft Azure Active Directory or LDAP to [Matrix](https://matrix.org/) rooms.\nThis way you can create managed rooms where users are automatically invited or kicked depending on their membership in a specific user-group. Permission-levels like \"Standard\" or \"Moderator\" as well as room permissions are also managed by the bot.\n\nYou might be also interested in this project, which is quite similiar: \u003chttps://github.com/davidmehren/maubot-ldap-inviter\u003e\n\n### Features\n- Automatic sync of user groups from an identity management like LDAP or Microsoft Azure Active Directory to members of matrix rooms.\n- Set permissions and roles for all managed matrix room\n- Management room for debugging and manual syncing\n\n![Inviter-Bot1](https://user-images.githubusercontent.com/8049779/187029596-8534d5ab-64ac-4352-9d69-66300dc416d3.png)\n\n## Installation\nThis is a plugin for the Maubot bot system which is required for the bot to run.\n\nIt is also required to install the following additional dependencies to your maubot server environment. You can install them all with `pip install -r requirements.txt`:\n- azure-identity\n- msgraph-core\n- ldap3\n\nOtherwise use this Dockerfile to have the requirements already installed:\n````\nFROM dock.mau.dev/maubot/maubot\nRUN apk add gcc\nRUN pip install --upgrade pip\nRUN pip install azure-identity msgraph-core ldap3\n````\n\nExample `docker-compose.yml` for setting up the Maubot server:\n````yaml\nversion: \"3.6\"\n\nservices:\n  postgres:\n    image: postgres:13.2\n    restart: always\n    expose:\n      - 5432\n    volumes:\n      - ./pgdata:/var/lib/postgresql/data\n    environment:\n      - POSTGRES_PASSWORD=\n      - POSTGRES_USER=postgres\n\n  maubot:\n    build:\n      dockerfile: ./Dockerfile\n      context: .\n    container_name: maubot\n    image: dock.mau.dev/maubot/maubot\n    restart: unless-stopped\n    volumes:\n    - ./logs/:/var/log/maubot\n    - ./data:/data\n    ports:\n      - 29316:29316\n    depends_on:\n      - postgres\n````\n\nIn your Maubot server Web-UI do the following:\n- Load the *.mbp file from releases into your Maubot Manager (can also be generated from source with `mbc build`)\n- Create client and instance in Maubot Manager\n\n### Log levels\nThe log levels are very verbose per default. This can lead to many log messages especially from the microsoft azure library.\nYou may update the `config.yaml` to use INFO instead of debug.\n\n````yaml\n[...]\n# Python logging configuration.\n#\n# See section 16.7.2 of the Python documentation for more info:\n# https://docs.python.org/3.6/library/logging.config.html#configuration-dictionary-schema\nlogging:\n    version: 1\n    formatters:\n        colored:\n            (): maubot.lib.color_log.ColorFormatter\n            format: \"[%(asctime)s] [%(levelname)s@%(name)s] %(message)s\"\n        normal:\n            format: \"[%(asctime)s] [%(levelname)s@%(name)s] %(message)s\"\n    handlers:\n        file:\n            class: logging.handlers.RotatingFileHandler\n            formatter: normal\n            filename: ./maubot.log\n            maxBytes: 10485760\n            backupCount: 10\n        console:\n            class: logging.StreamHandler\n            formatter: colored\n    loggers:\n        maubot:\n            level: INFO\n        mau:\n            level: INFO\n        aiohttp:\n            level: INFO\n        azure.identity._internal.get_token_mixin:\n            level: INFO\n        urllib3.connectionpool:\n            level: INFO\n        msal.application:\n            level: INFO\n        msal.telemetry:\n            level: INFO\n    root:\n        level: DEBUG\n        handlers: [file, console]\n````\n\n\n## Setup\nOne bot instance can only manage on identity provider at a time.\n### Azure Active Directory\n#### API setup\nFollow the steps decribed [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-daemon-app-registration).\n- Create a Daemon App Registration\n- Create a Client Secret\n- Ensure that proper application permissions are given to the app registration. Don't forget to grant your admin consent.\n  - `Group.Read.All`\n  - `User.Read.All`\n\n#### Example user-group structure\nCreate user-groups in your Azure AD like shown below. The users are fetched recursively, so you can put user-groups in user-groups.\n````\nChat\n├─ MTRX #example:matrix.example.com\n│  ├─ User-Group 1\n│  │  ├─ User A (Owner)\n│  │  ├─ User B\n│  ├─ User Group 2\n│  │  ├─ User A\n│  │  ├─ User C\n│  │  ├─ User D\n├─ MTRX #example2:matrix.example.com\n│  ├─ User Group 3\n│  │  ├─ User C (Owner)\n│  │  ├─ User E\n````\n\n![Inviter-Bot2](https://user-images.githubusercontent.com/8049779/187029651-8f4b81ce-1ae7-4c19-865b-6445e86941eb.png)\n\n### LDAP\n#### Setup\n- Create an LDAP bind account (read only)\n\n#### Example user-group structure\nCreate user-groups in your LDAP like shown below. The `xxx` is used as a replacement for `{@, :}`, because these symbols are not allowed in LDAP.\n````\nxxxexamplexxxmatrix.example.com\n├─ User-Group 1\n│  ├─ User A\n│  ├─ User B\n├─ User Group 2\n│  ├─ User A\n│  ├─ User C\n│  ├─ User D\nxxxexamplexxxmatrix.example.com_owners\n├─ User A\nxxxexample2xxxmatrix.example.com\n├─ User Group 3\n│  ├─ User C\n│  ├─ User E\nxxxexample2xxxmatrix.example.com_owners\n├─ User C\n````\n\n### Configuration\nConfigure the Inviterbot in the configuration on the Maubot server.\n\n## Usage\n### How to manage a matrix room\n1. Create a user group in your linked Identity Provider as described above.\n2. Syncs are performed automatically every 30 minutes\n\n### How to manage a space\nThe bot can not create spaces on his own. Spaces that should be managed by the bot have to be created beforehand via Element.\n1. Create a space\n2. Invite the bot and give him Admin permission\n3. Make the space public\n4. Create an alias\n5. Make it private again\n6. Create a user group in your linked Identity Provider\n\n### How to add external users to a managed room\n#### Option 1: Two InviterBots in one room (fully managed)\nEach bot only manages users from his homeserver. If the external users are managed by a bot on their homeserver, \ntheir bot can manage them in this room too. This would result in the following setup:\n\nSome Room\n- `@user1:homeserverA` is managed by bot A\n- `@user2:homeserverA` is managed by bot A\n- `@user3:homeserverB` is managed by bot B\n- `@bot:homeserverA`   is a bot and admin and manages User 1 and User 2\n- `@bot:homeserverB`   is a bot and admin and manages User 3\n\nTo achieve this\n1. Make sure, that a user-group corresponding to the room-alias is defined in the identity providers of both bots\n2. Invite the second bot to the room and give him admin permission\n   (e.g. via `!invite-admin \u003croom-alias\u003e \u003cuser\u003e`)\n3. The second bot will now begin to sync the state of his idp to the room.\n\n#### Option 2: Manually invite external users (partly unmanaged)\nThis is useful, if only a very small amount of external users should participate in a room. \n\nSome Room\n- `@user1:homeserverA` is managed by bot A\n- `@user2:homeserverA` is managed by bot A\n- `@user3:homeserverB` is not managed\n- `@bot:homeserverA`   is a bot and admin and manages User 1 and User 2\n\nTo achieve this\n1. Use `!invite-member \u003croom-alias\u003e \u003cuser\u003e` to invite an external user to the room that is managed by your bot.\n2. Your bot will ignore this external user. If you want to kick him, this has to be done manually via `!kick-member \u003croom-alias\u003e \u003cuser\u003e`\n\n### Commands\nCommands can only be sent to the bot in a specific administration room.\n- Create admin room\n- Invite bot\n- Configure admin room in bot-configuration on the Maubot server\n\nUse `!inviter` to list available commands.\n\n* `!idp` - list rooms and members defined in the linked IdP\n* `!joined` - list joined rooms\n* `!managed` - list managed rooms\n* `!sync [dry]` - trigger manual sync\n* `!unmanage \u003croom-alias\u003e \u003cnew admin\u003e` - unmanage room\n* `!invite-member \u003croom-alias\u003e \u003cuser\u003e` - manually add an external member as unmanaged standard user\n* `!kick-member \u003croom-alias\u003e \u003cuser\u003e` - manually kick an unmanaged, external member\n* `!invite-admin \u003croom-alias\u003e \u003cuser\u003e` - manually add an external member as admin (Be aware that admins can not be removed. They have to leave by their own.)\n\n## Code and contributing\nWe would love to see your contribution to this project. Please refer to `CONTRIBUTING.md` for further details.\n\n### Used libraries/modules\n- [ldap3](https://github.com/cannatag/ldap3)\n- [azure-identity]() - [docs](https://docs.microsoft.com/en-us/python/api/azure-identity/?view=azure-python)\n- [msgraph-core](https://github.com/microsoftgraph/msgraph-sdk-python-core)\n- [maubot](https://github.com/maubot/maubot)\n- [mautrix-python](https://github.com/mautrix/python)\n\n### Tips for development\n- Use the [ms graph explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) to get known to the graph API\n- Read the [Microsoft Graph REST API reference](https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0)\n- Read the [Matrix Client-Server API spec](https://spec.matrix.org/latest/client-server-api/)\n\n### File structure\n````\n├── README.md\n├── base-config.yaml    # Sample config that is loaded to the bot-instance on first start\n├── inviter\n│ ├── bot.py    # Main bot class with all command related functions\n│ ├── bot_helper.py   # Static helper-functions\n│ ├── config.py       # Maubot Config class that defines how to react on config updates\n│ ├── enum.py         # Holds globally defined power-level definitions\n│ ├── ldap_connector.py       # Everything related to the LDAP connection\n│ ├── matrix_utils.py         # Everything directly related to the matrix Client-Server API\n│ ├── ms_graph_connector.py   # Everything related to the MS graph API connection for Azure Active Directory\n│ └── room_structure.py       # Data classes for room structure\n└──  maubot.yaml      # Informations about the plugin\n````\n\n### CI\nThe release is created automatically via GitHub Actions. The workflow also includes building a .mbp plugin file and attaching it to the release. It is triggered only on main. To create a new release,\n  1. Update the version in the maubot.yaml file\n  2. Create a new git tag: `git tag -a v0.0.1 -m \"my version 0.0.1\"`\n  3. Push the new tag to github and see the workflow to his job: `git push --follow-tags`\n\n## Docs\nFor now, please refer to the docstrings in the code.\n\n## License\nThis project is licensed under GPLv3. See `LICENSE` for the license text and `COPYRIGHT.md` for the general copyright notice.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapucc%2Finviterbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsapucc%2Finviterbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapucc%2Finviterbot/lists"}