Skip to content

Commit 2229d1d

Browse files
AndrburAndrbur
authored
script for sync users between keycloak group and Synapse DB (#1) (#1)
* script for sync users between keycloak group and Synapse DB (#1) * added github action for build and bush image (#2) * script for sync users between keycloak group and Synapse DB * added github action for build and bush image
1 parent 03ee786 commit 2229d1d

6 files changed

Lines changed: 413 additions & 1 deletion

File tree

‎.github/workflows/build-docker-image.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Docker Image
2+
3+
on:
4+
push:
5+
tags:
6+
- '*'
7+
8+
jobs:
9+
docker:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout Repository
13+
uses: actions/checkout@v3
14+
15+
- name: Generate Docker Metadata
16+
id: meta
17+
uses: docker/metadata-action@v4
18+
with:
19+
images: ghcr.io/${{ github.repository }}
20+
tags: |
21+
type=ref,event=tag
22+
type=semver,pattern={{version}}
23+
type=semver,pattern={{major}}.{{minor}}
24+
flavor: latest=true
25+
26+
- name: Setup Docker Buildx
27+
uses: docker/setup-buildx-action@v2
28+
29+
- name: Login to GitHub Container Registry
30+
uses: docker/login-action@v2
31+
with:
32+
registry: ghcr.io
33+
username: ${{ github.actor }}
34+
password: ${{ secrets.GITHUB_TOKEN }}
35+
36+
- name: Build and Push Docker Image
37+
uses: docker/build-push-action@v3
38+
env:
39+
DOCKER_BUILDKIT: 1
40+
with:
41+
context: .
42+
file: Dockerfile
43+
push: true
44+
tags: ${{ steps.meta.outputs.tags }}
45+
labels: ${{ steps.meta.outputs.labels }}

‎Dockerfile‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
FROM ghcr.io/element-hq/matrix-authentication-service:1.10.0 AS mas-cli
2+
3+
FROM debian:bookworm-slim
4+
5+
RUN apt update && \
6+
apt install curl jq -y
7+
8+
WORKDIR /opt/sync
9+
10+
COPY --chmod=755 keycloak_matrix_sync.sh .
11+
#COPY keycloak_matrix_sync.conf .
12+
#COPY mas-config.yaml .
13+
14+
COPY --from=mas-cli /usr/local/bin/mas-cli /usr/local/bin/mas-cli

‎README.md‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,92 @@
1-
# matrix-keycloak-sync
1+
# matrix-keycloak-sync
2+
3+
A script that synchronizes users from a Keycloak group with user accounts in a Matrix chat (Synapse).
4+
5+
---
6+
7+
## Overview
8+
9+
The script fetches the list of users from a specific Keycloak group and compares them against the user state (enabled/disabled) in the Matrix/Synapse database. User activation and deactivation in Matrix is controlled by Keycloak group membership.
10+
11+
---
12+
13+
## User Sync Logic
14+
15+
| User in Keycloak group | User in Synapse DB | Action |
16+
|---|---|---|
17+
| ✅ Yes | ✅ Yes (active) | No action needed |
18+
| ✅ Yes | ✅ Yes (disabled) | **Activate** via `mas-cli` |
19+
| ✅ Yes | ❌ No | **Skip** — will be created on first login |
20+
| ❌ No | ✅ Yes (active) | **Disable** via `mas-cli` |
21+
| ❌ No | ✅ Yes (disabled) | No action needed |
22+
23+
> **Note:** If a user is present in the Keycloak group but does not yet exist in the Synapse database, they are skipped during this sync run. The user account will be automatically created in Synapse upon their first login via Keycloak SSO.
24+
25+
---
26+
27+
## Components
28+
29+
### Keycloak
30+
- Source of truth for user access.
31+
- Users added to a designated group are considered **active** in Matrix.
32+
- Users removed from the group will be **disabled** in Matrix on the next sync run.
33+
34+
### Synapse API
35+
- Used **read-only** to fetch the current list of users and their `deactivated` status.
36+
- Requires an admin token (see [Authentication](#authentication) below).
37+
38+
### mas-cli (Matrix Authentication Service CLI)
39+
- Used to **activate and deactivate** users.
40+
- Requires a `mas-cli.yaml` config file.
41+
- Communicates **directly with the database** — bypasses Synapse API for write operations.
42+
43+
> **Why mas-cli instead of Synapse API for writes?**
44+
> Disabling a user directly in the Synapse database (without going through MAS) is insufficient — MAS will still allow the user to log in even if the `is_disabled = true` flag is set in the Synapse DB. All deactivation must go through `mas-cli` to be effective.
45+
46+
---
47+
48+
## Authentication
49+
50+
### Synapse Admin Token
51+
52+
Generate an admin-scoped token via `mas-cli`. It is recommended to create a **dedicated non-admin Matrix user** for management purposes and grant it admin privileges via token only:
53+
54+
```bash
55+
mas-cli manage issue-compatibility-token \
56+
--yes-i-want-to-grant-synapse-admin-privileges \
57+
<your_matrix_username_for_managing_users>
58+
```
59+
60+
---
61+
62+
## Configuration
63+
64+
### `mas-cli.yaml`
65+
66+
Required for `mas-cli` to connect to the database. Example path: `/etc/mas-cli/mas-cli.yaml`.
67+
68+
### Environment variables / config for the script
69+
70+
| Variable | Description |
71+
|---|---|
72+
| `KC_URL` | Base URL of the Keycloak instance |
73+
| `KC_REALM` | Keycloak realm name |
74+
| `KC_GROUP_NAME` | Name or ID of the group to sync |
75+
| `KC_CLIENT_ID` | Client ID |
76+
| `KC_ADMIN_USER` | User in keycloak in master realm (with restriction permission in specific realm for getting user list)|
77+
| `KC_ADMIN_PASS` | User pass in keycloak in master realm |
78+
| `MATRIX_URL` | Base URL of the Synapse homeserver |
79+
| `MATRIX_ADMIN_TOKEN` | Admin token for Synapse API |
80+
| `MATRIX_SERVER_NAME` | Matrix server name |
81+
82+
---
83+
84+
## Alternative: MAS Admin API
85+
86+
It is also possible to manage users via the [MAS Admin API](https://matrix-org.github.io/matrix-authentication-service/topics/admin-api.html#enabling-the-api) instead of `mas-cli`. However, this approach has additional overhead:
87+
88+
- The API must be explicitly enabled in MAS configuration.
89+
- A separate API token must be generated (not the one generated via the MAS CLI).
90+
- The API endpoint is **exposed publicly by default** and requires additional hardening.
91+
92+
For these reasons, using `mas-cli` directly is the recommended approach for this script.

‎keycloak_matrix_sync.conf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#Examples of environments vars
2+
3+
KC_URL="https://keycloak.domain.com"
4+
KC_REALM="<KeyCloak_Realm_name>"
5+
KC_CLIENT_ID="admin-cli" # Default client in master realm for connect ot KK via kk_user
6+
KC_ADMIN_USER="matrix-groups-viewer" # Created user in master realm
7+
KC_ADMIN_PASS="<KeyCloak user pass>"
8+
KC_GROUP_NAME="matrix-users" # Keycloak group from which users will be synchronized with the chat
9+
10+
MATRIX_URL="https://matrix.domain.com" # URL Matrix homeserver
11+
MATRIX_ADMIN_TOKEN="<Matrix_generated_token_via_mas>" # Access token Matrix-
12+
MATRIX_SERVER_NAME="matrix.domain.com" # Matrix server name
13+
14+
#In script hardcoded as false
15+
#DRY_RUN=true

0 commit comments

Comments
 (0)