Matrix synapse SSO implementation

Published in

YavarTechWorks

4 min readNov 9, 2023

In this post, I will explain SSO(Single Sign-on) implementation with the Matrix Synapse server. Before delving in, I will give an overview of the matrix and SSO.

Matrix

Matrix is for Instant Messaging. It works like email but it is instantaneous and secure. We can use a matrix as a server and build a Unified communication platform. Not only that but also it provides various features. For installation setups, you can watch this video.

SSO (Single Sign-on)

Single Sign-On (SSO) is an authentication and authorization process that allows a user to access multiple applications or services with a single set of login credentials.

I am going to build an application, that has various features. I have two different backend applications for other purposes. One feature of the application is Unified Communication. Users of the application can collaborate with each other, they can create Rooms and chat. For that purpose I need SSO.

Matrix provides SSO support. It supports various protocols for SSO such as SAML, OpenID, and CAS. Here I choose the OpenID protocol and Keycloak as a provider.

Keycloak

Keycloak is an open-source identity and access management (IAM) solution that provides single sign-on (SSO), user authentication, and authorization services for applications and services. For installing Keycloak click here.

Keycloak Configuration

By default, Keycloak runs in 8080 port. If our Matrix server wants to connect with the SSO provider we should run both the Matrix server and Keycloak in https and configure with SSL certificate.

Once we configure the SSL certificate for Matrix Synapse and Keycloak, we can create Realm and Client in Keycloak.

Create a Realm

Here I have created a realm called matrix. Once you created the realm then choose the realm after logging in. After choosing the realm do all other activities such as creating new clients and users.

Create a new Client

The above three screenshots are examples of creating a client and configuring with matrix synapse callback.

We have to give a valid redirect URL [synapse public baseurl]/_synapse/client/oidc/callback.

Create users by clicking the Users menu. Using the same user, we can log in to our application.

Matrix configuration

After the matrix is installed in the server we can access homeserver.yaml file under the cd /etc/matrix-synapse/ folder.

Open homeserver.yaml file and add the below configuration lines for SSO implementation.

client_whitlist for disable continue with your account page. For more details refer to this link.

Now we can access the SSO feature by using a frontend application. We can build our own front-end application or use element-web as an open-source matrix client.

React application

Here I have given a sample gist of the react application which uses SSO login.

The below code is for initiating the Matrix login function after the SSO token is received from the Keyclaok

In the above snippets, I have given the main logic of the SSO implementation. We consider this as a reference. Now we can run our application.

Our react application runs in port number 3000. In the web application click the SSO login button. It redirects to the Keycloak login page and once the user a successfully logged in Keycloak provides an SSO token in the redirect URL we need to get the SSO token and pass the token to the matrix login API and the matrix login function returns the access token.