Element (Synapse) SAML Integration

This document explains how to implement Monosign with Synapse, the Matrix homeserver that is used by Element and other Matrix clients. It covers Single Sign-On using SAML 2.0, where Monosign acts as the Identity Provider (IdP) and Synapse as the Service Provider (SP). Before you continue, it is better to start with the Synapse documentation (opens in a new tab) about the saml2_config option.

This configuration is done with Synapse 1.164.1 (image ghcr.io/element-hq/synapse:v1.164.1) and Element Web 1.12.33 (image ghcr.io/element-hq/element-web:v1.12.33) running on Docker, with the built-in SQLite database of Synapse. If your versions or deployment type are different, please check the Synapse and Element documentation.

Synapse supports SAML 2.0 natively (with the library pysaml2), next to OpenID Connect and CAS. There is no single sign-on screen in Synapse or Element; SAML is configured in the file homeserver.yaml of Synapse. The sign-in is started from a Matrix client such as Element, which shows a Continue with Monosign button.

Monofor has no responsibility to do Synapse and Element configurations. If you need support please contact the Element community or your Element support provider.

Synapse is free and open source (AGPL-3.0) and Element Web is open source (AGPL-3.0 or the Element commercial license). Single sign-on is not limited by a license in the self-hosted version.

The server name of a Matrix homeserver (server_name) becomes a part of every user ID (for example @john:<server-name>) and cannot be changed later. Choose it before the first sign-in.

Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the SAML settings on Monosign
Assign a user to the Element (Synapse) application
Configuration Single Sign-On for Synapse and Element Web
Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Synapse is not in the application catalog, so click Create from scratch.

Fill in the application details on the Application tab and click Next.

Property	Value	Description
Name	`Element (Synapse)`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	The sign-in is made through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the address of Element Web (for example `https://<element-address>`). The sign-in is started from the Matrix client with the Continue with Monosign button (see step 5); it cannot be started directly from the Monosign portal.
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All). Synapse needs the user name, the name and the e-mail address of the user.

Synapse creates a Matrix account for every Monosign user who signs in for the first time. Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.

After the application is created, click Keys and add a new Access Key for SAML access.

Select SAML as the key type and click Create. Monosign generates the Key value of the SAML application automatically; it is a part of the Monosign SAML addresses.

Property	Value	Options
Type	`SAML`	Rest API, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Key	Generated automatically	Unique identifier of the SAML application in the Monosign addresses.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

The key page shows the Monosign values that are needed in the Synapse configuration (step 4):

Monosign value	Example	Used in Synapse as
Metadata (View IdP Metadata / Download IdP Metadata)	`https://<monosign-host>/saml/<key>/metadata`	`sp_config.metadata.remote[].url`. Synapse reads the Sign On Service, the Entity Id and the certificate of Monosign from this document, so they do not need to be entered one by one.
Sign On Service	`https://<monosign-host>/saml/<key>/login`	Read by Synapse from the metadata.
Entity Id	`https://<monosign-host>/saml/<key>`	Read by Synapse from the metadata (`idp_entityid` is needed only when the metadata has more than one entity).
View Certificate / Download Certificate	X.509 certificate of Monosign	Also read from the metadata; it is not entered in Synapse by hand.

2- Configuring the SAML Settings on Monosign

Click the Configure button of the SAML key (or Edit of the key) and go to the SAML Settings → Configuration tab. Enter the address where Synapse receives the SAML response in Assertion Consumer Url, the address of the Synapse metadata as Audience and set the Name Id to the e-mail address of the user.

Property	Value	Description
Assertion Consumer Url	`https://<synapse-address>/_synapse/client/saml2/authn_response`	The address where Synapse receives the SAML response (HTTP-POST binding). The path is fixed by Synapse; the host is the `public_baseurl` of the homeserver, not the address of Element Web.
Audience	`https://<synapse-address>/_synapse/client/saml2/metadata.xml`	The Entity Id of Synapse as a service provider. Synapse builds it from `public_baseurl`; the same address is also the SP metadata that you can open in a browser.
ACS Validation Mode	`Enforce`	Monosign accepts only the registered ACS address. Synapse sends exactly this address in its request, so `Enforce` works. `Warn Only` is the default and works as well.
NameId Format	`System Default (unspecified)`	Default value.
Name Id	`Email`	NameID of the SAML response. Synapse does not use it for the user name; the user is identified by the attribute `uid` (see below).

Open the Attribute Mapping tab, add the three attributes that Synapse reads and click Update to save.

Attribute	Value	Description
uid	`{{UserName}}`	Required. Unique name of the user. Synapse uses it as the identifier of the user and, by default, to build the Matrix user ID (`@<uid>:<server-name>`).
displayName	`{{FormattedUserName}}`	Optional. Display name of the Matrix account.
email	`{{Email}}`	Optional. E-mail address that is added to the Matrix account.

The attribute names are case sensitive: the built-in user mapping of Synapse reads exactly uid, displayName and email. Monosign sends these names as they are, and Synapse accepts them only with the option allow_unknown_attributes: true (step 4); without it Synapse answers with the error 'uid' not in SAML2 response even though the attribute is in the response.

3- Assign a User to the Element (Synapse) Application

Open the application in Monosign, click the Assignments tab and click Assign a User.

Search and select the users who can sign in to Synapse, check the Expiration Date and save. You can select more than one user.

Property	Value	Description
User(s)	Selected users	Users who can sign in to Synapse with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Synapse and Element Web

As we mentioned at the start, please check out the Synapse documentation first. Add the SAML provider to the file homeserver.yaml of Synapse and replace the placeholder values.

server_name: "<synapse-host-name>"
public_baseurl: "https://<synapse-host-name>/"

saml2_config:
  idp_name: "Monosign"
  sp_config:
    allow_unknown_attributes: true
    metadata:
      remote:
        - url: "https://<monosign-host>/saml/<key>/metadata"
    accepted_time_diff: 3
  user_mapping_provider:
    config:
      mxid_source_attribute: uid

Option	Value	Description
public_baseurl	`https://<synapse-host-name>/`	Public HTTPS address of Synapse. The Entity Id and the ACS address of Synapse are built from it, so they must match the Audience and the Assertion Consumer Url of step 2.
idp_name	`Monosign`	Name of the provider on the sign-in button (Continue with Monosign).
sp_config.allow_unknown_attributes	`true`	Required for Monosign. Monosign sends the attributes with the plain names `uid`, `displayName` and `email`. Without this option the SAML library of Synapse drops them and the sign-in fails with 'uid' not in SAML2 response.
sp_config.metadata.remote	`url: https://<monosign-host>/saml/<key>/metadata`	Metadata of the Monosign SAML key (step 1). Synapse reads it when it starts, so Monosign must be reachable from the Synapse host. You can also point `local` to a downloaded metadata file.
accepted_time_diff	`3`	Allowed clock difference in seconds between Synapse and Monosign. The default is 0; keep the clocks of both servers synchronized.
user_mapping_provider.config.mxid_source_attribute	`uid` (default)	SAML attribute that the Matrix user ID is built from. `mxid_mapping` (`hexencode` by default, or `dotreplace`) defines how characters that are not allowed in a Matrix user ID are replaced.
attribute_requirements	Optional	Allows the login only when the SAML attributes have given values, for example a department or a group.
sso.client_whitelist	Optional	After the sign-in Synapse asks the user to confirm that the client may access the account (the page Continue to your account). Add the address of Element Web with a slash at the end (for example `https://<element-address>/`) to skip this page.

When Synapse is behind a reverse proxy, the proxy must send the headers X-Forwarded-For and X-Forwarded-Proto and the listener of Synapse must have x_forwarded: true. After changing homeserver.yaml, restart Synapse. Once SAML is enabled, the SP metadata of Synapse is available at https://<synapse-address>/_synapse/client/saml2/metadata.xml.

Element Web needs to know the homeserver. Create a config.json for Element Web and mount it in the container:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://<synapse-host-name>",
      "server_name": "<synapse-host-name>"
    }
  },
  "disable_custom_urls": true,
  "brand": "Element"
}

Installation (for reference only). The installation of Synapse and Element Web is described in their documentation. For this document they were installed with Docker Compose as below; the configuration file of Synapse was generated with the generate command of the image, and the folder data belongs to the container user 991. The two services need two host names with HTTPS (one for the homeserver and one for Element Web).

services:
  synapse:
    image: ghcr.io/element-hq/synapse:v1.164.1
    restart: unless-stopped
    user: "991:991"
    volumes:
      - ./data:/data
    ports:
      - "6277:8008"
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
  element:
    image: ghcr.io/element-hq/element-web:v1.12.33
    restart: unless-stopped
    volumes:
      - ./element-config.json:/app/config.json:ro
    ports:
      - "6278:80"
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

5- Sign In Test

Now try to log in to Synapse using Monosign SSO from Element.

Open a new browser window (or a private window) and type the address of Element Web. The sign-in page of Element shows the user name and password form and, below it, the Continue with Monosign button.

Click the button. On the Monosign sign-in page of the application log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.

After the sign-in Monosign sends the SAML response to the ACS address of Synapse (/_synapse/client/saml2/authn_response). Synapse shows the page Continue to your account; click Continue.

At the first sign-in Synapse creates the Matrix account with the user name, the display name and the e-mail address from Monosign and Element opens with the new account.

Troubleshooting

Symptom	Cause	Solution
The Continue with Monosign button is not shown	`saml2_config` is missing in `homeserver.yaml`, Synapse could not read the Monosign metadata when it started, or Element Web points to another homeserver.	Check the section `saml2_config`, open the metadata address from the Synapse host, read the Synapse log after the start and check `default_server_config` in the `config.json` of Element Web.
Monosign shows an error about the ACS address	The Assertion Consumer Url of Monosign is different from the ACS address of Synapse, for example because `public_baseurl` is wrong, which matters most when ACS Validation Mode is `Enforce`.	Use exactly `https://<synapse-address>/_synapse/client/saml2/authn_response` in Monosign and set `public_baseurl` as in step 4.
The page after the sign-in shows 'uid' not in SAML2 response	Either the attribute `uid` is not sent by Monosign, or it is sent but Synapse drops it because `allow_unknown_attributes` is not set.	Add the attributes `uid`, `displayName` and `email` in the Attribute Mapping of the Monosign SAML key and press Update (step 2), and set `allow_unknown_attributes: true` under `sp_config` (step 4).
The sign-in fails with an error about the time of the response	The clocks of Synapse and Monosign are different.	Synchronize the clocks and set `accepted_time_diff` (step 4).
The sign-in succeeds on Monosign but Synapse refuses the user	The response does not satisfy `attribute_requirements`, or the certificate in the metadata does not match the current Monosign certificate.	Check `attribute_requirements` and restart Synapse so that it reads the current metadata of Monosign.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
The sign-in cannot be started from the Monosign portal	Synapse accepts only sign-ins that it started itself (service provider initiated), unless `allow_unsolicited` is set in `sp_config`.	Start the sign-in from Element with the Continue with Monosign button.
The browser stays on Logging in...	The sign-in was started from the fallback page of Synapse (`/_matrix/static/client/login/`). That page is made to run inside a client application and shows no result in a plain browser.	Sign in with Element Web or another Matrix client.

After completing the configuration on Synapse and Monosign, it is better to test in a new private browser window if the SAML SSO doesn’t work, because old session cookies may cause errors.