Matrix Synapse FreeBSD or Debian: SSO Made Simple with Azure

(2025-03-10):

When deploying an open-source chat solution like Matrix Synapse, authentication is a critical component. Many organizations rely on centralized identity providers to manage access securely and efficiently. This is where OpenID Connect (OIDC) comes into play, enabling seamless integration with enterprise identity platforms such as Microsoft Azure Active Directory, now known as Microsoft Entra ID.

By leveraging OIDC, Matrix Synapse can use Azure AD as a Single Sign-On (SSO) provider. Users authenticate with their existing corporate credentials while benefiting from enforced security measures such as multi-factor authentication (MFA / 2FA). This removes the need for separate login credentials and significantly improves security and usability.

One of the major strengths of Matrix Synapse is its flexibility. Unlike proprietary chat platforms, Matrix allows full control over authentication and identity integration. Combining Synapse with Azure AD delivers enterprise-grade security without vendor lock-in.

This guide walks through installing and configuring Matrix Synapse on FreeBSD or Debian, integrating Microsoft Azure AD via OIDC, and preparing the system for production use.

Installation

This section covers installing the required base packages for a Matrix Synapse server, including PostgreSQL for database management, Nginx as a reverse proxy, and Certbot for TLS certificates.

FreeBSD

For FreeBSD based systems the following packages need to be installed by pkg:

# Install packages
pkg install -y py39-matrix-synapse postgresql15-server postgresql15-client py39-certbot py39-certbot-nginx

# Enable services
sysrc postgresql_enable="YES"
sysrc nginx_enable="YES"
sysrc synapse_enable="YES"

# Obtain SSL certificate
certbot certonly --standalone -d matrix.example.com

Debian

For Debian based systems the following packages must be installed via the official Matrix Debian Repository:

# Add Matrix upstream repository
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" \
  > /etc/apt/sources.list.d/matrix-upstream.list

# Install packages
apt update
apt install -y matrix-synapse-py3 libpq5 postgresql nginx certbot python3-certbot-nginx

# Obtain SSL certificate
certbot certonly --standalone -d matrix.example.com

Configuration

The following sections describe how to configure PostgreSQL, Microsoft Azure AD (Entra ID), and Matrix Synapse to enable secure OIDC-based authentication.

Microsoft Azure AD Tenant

To integrate Matrix Synapse with Microsoft Azure AD using OpenID Connect, you must register an application in your Entra ID tenant.

Log in to the Microsoft Entra Admin Center with an administrator account
Navigate to App registrations
Click New registration

Configure the application registration as follows:

Name: Matrix Synapse OIDC
Supported account types:
- Single tenant – Only users from your organization
- Multitenant – Users from any Azure AD organization
- Personal Microsoft accounts – Optional, if required
Redirect URI:
https://matrix.example.com/_synapse/client/oidc/callback

After clicking Register, note the following values as they are required later:

Application (client) ID
Directory (tenant) ID

Next, create a client secret:

Open Certificates & Secrets
Click New client secret
Provide a description and expiration period
Copy the secret value immediately (it cannot be retrieved later)

Database

For production environments, PostgreSQL is strongly recommended over SQLite due to better performance and scalability. The following steps apply to both FreeBSD and Debian:

su - postgres
createuser --pwprompt matrix
createdb --encoding=UTF8 --locale=C --template=template0 --owner=matrix matrix

Adjust Matrix Server Config

Matrix Synapse is configured using the homeserver.yaml file.

Configuration File Locations

FreeBSD: /usr/local/etc/matrix-synapse/homeserver.yaml
Debian: /etc/matrix-synapse/homeserver.yaml

This file controls database settings, federation behavior, authentication providers, and general server options.

Switching to PostgreSQL for Production

Replace the default SQLite configuration with the following PostgreSQL settings:

database:
  name: psycopg2
  args:
    user: matrix
    password: $PASSWORD
    database: matrix
    host: localhost
    cp_min: 5
    cp_max: 10

Ensure PostgreSQL is running and accessible. This configuration prepares Synapse for production workloads.

Adding Microsoft Azure AD OIDC Provider

oidc_providers:
  - idp_id: microsoft
    idp_name: Microsoft
    issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
    client_id: "<client-id>"
    client_secret: "<client-secret>"
    scopes: ["openid", "profile"]
    authorization_endpoint: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize"
    token_endpoint: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
    userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo"

    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username.split("@")[0] }}"
        display_name_template: "{{ user.name }}"

Configure Nginx Reverse Proxy

An Nginx HTTPS virtual host is required to expose Matrix Synapse securely and ensure proper federation with other Matrix servers.

Restart The Service

After completing the configuration, restart the services:

# FreeBSD
service matrix-synapse restart
service nginx restart

# Debian
systemctl restart matrix-synapse
systemctl restart nginx

Conclusion

Running Matrix Synapse on FreeBSD or Debian with Microsoft Azure AD (Entra ID) via OpenID Connect provides a secure, scalable, and enterprise-ready messaging platform. This setup combines the openness of Matrix with centralized identity management, delivering strong authentication without sacrificing flexibility or control.