Keycloak and Discord role synchronisation bot

This bot synchronises Keycloak groups with Discord roles in the fastest and most minimal way possible.

Stale Pure Nim score 23/100 · last commit 2025-09-01 · 1 stars · tests present · no docs generated

Summary

Latest Version	Unknown
License	Unknown
CI Status	Failing
Stars	1
Forks	0
Open Issues	0
Last Commit	2025-09-01
Downloads	0
Last Indexed	2026-09-06 07:36

Installation

nimble install Keycloak and Discord role synchronisation bot

choosenim install Keycloak and Discord role synchronisation bot

git clone https://gitlab.com/warsaw-revamped-oss/kc-discord-role-sync

OS Compatibility

Platform	Linux	macOS	Windows	FreeBSD	OpenBSD	NetBSD	Android	iOS	WASM	Embedded
Keycloak and Discord role synchronisation bot	✓	✓	✓	-	-	-	-	-	-	-

Source

Repository	https://gitlab.com/warsaw-revamped-oss/kc-discord-role-sync
Homepage	https://gitlab.com/warsaw-revamped-oss/kc-discord-role-sync
Registry Source	gitlab

README

Discord <-> Keycloak role sync bot

This bot synchronises Keycloak groups to Discord roles, making Keycloak the source of truth for permissions, in the fastest and most minimal way possible.

Building

This is a pure cargo project, see the Cargo book.
TL;DR: cargo build --release to build a release binary, cargo run to run a development build.

Bot configuration

The bot is configured using environment variables (see src/config.rs).
It will also load environment variables from a .env file placed in the working directory.

The following options are available:

Variable	Required	Example value	Description
`BOT_TOKEN`	☑	`abcdefg.xyz`	Discord bot token. Create one on Discord. The bot will need at least "Manage roles" permissions and should be placed at the top of the role hierarchy.
`KEYCLOAK_HOST`	☑	`https://id.domain.com`	Base URL of your Keycloak instance
`KEYCLOAK_REALM`	☑	`myrealm`	Name of the Keycloak realm you want to sync with
`KEYCLOAK_USERNAME`	☑	`discord-bot`	Username to use for authentication with the Keycloak admin API. Needs permissions to view groups and users in your realm.
`KEYCLOAK_PASSWORD`	☑	`secretsauce`	Password for the Keycloak user.
`GUILDS`	☑	`public:469622292818728980;internal:722972618198698275`	A mapping of Discord server alias (chosen by you) to guild ID that the bot should synchronise.
`IGNORE_ROLES`	☐	`469611687274341632,906205960183752476`	A list of Discord role IDs to always ignore during synchronisation. If a Discord member has these roles, they will be kept intact.
`SYNC_INTERVAL`	☐	`300` (Default)	How often the synchronisation should take place, in seconds.
`RUST_LOG`	☐	`INFO` (Default)	Log level. See Level.

Usage with Keycloak

Your Keycloak instance needs to run the Discord identity provider and your users have to connect their Discord accounts in the federated identity section of their account settings.

On each Keycloak group that you want to associate with a Discord role, add an Attribute in the following format:

Key	Value
`discord_id_{guild_alias}_{optional_postfix}`	`{role_id}`

with guild_tag being the alias for the Discord guild you configured with the GUILDS environment variable, and role_id being a Discord role ID on that Discord guild.
optional_postfix can be appended for de-duplication purposes (so you can define more than one role per Keycloak group) and is not used by the bot.

Example:

Key	Value
`discord_id_public`	`1004848059395612823`
`discord_id_public_2ndrole`	`1004848059395423231`

Attributes applied to a parent group will be passed down and given to any member in any subgroup of that parent group too.

Running

Simply run the built executable with the previously mentioned environment variables defined. You can also create a .env file in the working directory which will be read by the bot.

Warning: The bot will remove all roles from all users that are not defined through Keycloak.
If you are unsure about your configuration, it is advisable to run the bot with the --dry-run flag first, which will skip making any changes.