Skip to content
A simple keycloak adapter for Matrix Synapse allowing to login into Matrix using Keycloak as an identity provider.
Java Dockerfile
Branch: master
Clone or download

README.md

quality-gate code-smells bugs

pipeline status

Synapse Keycloak Adapter

A simple keycloak adapter for Matrix Synapse allowing to login into Matrix using Keycloak as an identity provider.

Disclaimer

WORK IN PROGRESS : THIS IS STILL NOT COMPLETELY FUNCTIONAL

We cannot guaranty this is 100% secure, we are still learning and doing this for fun. Enjoy!

Prerequisites

To use this adapter you need to have a running Keycloak Instance.

Go to the Official Keycloak Documentation to learn how to do that.

The easiest way to set up a Keycloak Instance is to use Docker Compose (More info here).

Getting started

Adapter only

If you only need the adapter you can run only this part :

With docker :

Run the following command after having replaced the environment variables with your own values :

docker run -e \

hoohoot/synapse-keycloak-adaper

With docker compose :

  1. Edit docker-compose-adapter-only.yml and edit the variables following your needs

  2. Start the adapter : docker-compose -f docker-compose-adapter-only.yml up -d

Complete setup

TODO

Configuration

Variable Status Description
SYNAPSE_HOST mandatory hostname of your Synapse instance (eg. matrix.example.org)
KEYCLOAK_CLIENT_ID mandatory The client ID of the client you've configured in Keycloak
KEYCLOAK_CLIENT_SECRET mandatory The client secret of the client you've configured in Keycloak
KEYCLOAK_SEARCH_USER mandatory The username of the keycloak user dedicated to searching user.
KEYCLOAK_SEARCH_PASSWORD mandatory The password of the keycloak user dedicated to searching users.
REALM optional (default value : master) The name of your Keycloak Realm
SSL_ACTIVE optional (default value: true) Activate or not HTTPS for requests
SERVER_PORT optional (default value: 8080) The port the VertX server will listen on
USER_AGENT optional (default value: synapse-adapter) The user agent used for requests

Configuration

Variable Status Description
SYNAPSE_HOST mandatory hostname of your Synapse instance (eg. matrix.example.org)
KEYCLOAK_CLIENT_ID mandatory The client ID of the client you've configured in Keycloak
KEYCLOAK_CLIENT_SECRET mandatory The client secret of the client you've configured in Keycloak
KEYCLOAK_SEARCH_USER mandatory The username of the keycloak user dedicated to searching user.
KEYCLOAK_SEARCH_PASSWORD mandatory The password of the keycloak user dedicated to searching users.
REALM optional (default value : master) The name of your Keycloak Realm
SSL_ACTIVE optional (default value: true) Activate or not HTTPS for requests
SERVER_PORT optional (default value: 8080) The port the VertX server will listen on
USER_AGENT optional (default value: synapse-adapter) The user agent used for requests

Upgrade

In order to upgrade to the last version, just run the next two commands :

docker-compose pull
docker-compose up -d

Development

  1. Set the following environment variables
SYNAPSE_HOST=matrix.example.org
KEYCLOAK_HOST=keycloak.example.org
KEYCLOAK_CLIENT_BASIC=${base64(client-id:client-secret)}
REALM=my-keycloak-realm;
KEYCLOAK_SEARCH_USERNAME=admin;
KEYCLOAK_SEARCH_PASSWORD=password
  1. Package the application:
mvn clean install
  1. Run the fat jar :
java -jar target/keycloak-synapse-adapter-${version}-SNAPSHOT-fat.jar -conf src/conf/config.json

Ressources

We use the following projects :

You can’t perform that action at this time.