When deploying an open-source chat solution like Matrix Synapse, authentication is a critical piece of the puzzle. Many businesses rely on centralized identity providers to manage user access efficiently. That’s where OpenID Connect (OIDC) comes in, allowing seamless integration with enterprise-grade identity solutions like Microsoft Azure Active Directory (Azure AD) which is now also known as Microsoft Entra ID.

By leveraging OIDC, we can integrate Azure AD as a Single Sign-On (SSO) provider for Matrix Synapse, ensuring users authenticate using their existing corporate credentials including and enforcing two factor authentication (2FA). This eliminates the need for separate logins while enhancing security and user convenience.

One of the biggest advantages of using open-source software like Matrix Synapse is flexibility. Unlike proprietary communication platforms, Matrix allows us to customize and extend its authentication system to fit our business needs. And by integrating with Azure AD, we get enterprise-level security without locking ourselves into a single ecosystem.

In this post, I’ll walk through the process of integrating Microsoft Azure AD with Matrix Synapse using OIDC, covering configuration, troubleshooting, and the benefits this brings to businesses looking for secure, open, and scalable communication solutions.

Installation

In this chapter, we will go through the installation of the necessary base packages for setting up a Matrix Synapse server on a Linux system. This includes installing PostgreSQL for the database, Synapse for the Matrix server, Nginx as the reverse proxy, and Certbot for obtaining SSL certificates from Let’s Encrypt.

FreeBSD

# 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

# Get the GPG Keyring from upstream repo
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-get update
apt install matrix-synapse-py3 libpq5 postgresql nginx certbot python3-certbot-nginx
# Obtain SSL Certificate
certbot certonly --standalone -d matrix.example.com

Configuration

In this chapter, we will walk through the configuration process for integrating Microsoft Azure AD with Matrix Synapse on a Linux system, utilizing PostgreSQL for database management, Certbot for SSL certificate management, and Nginx as a reverse proxy. This setup will enable seamless authentication via Azure AD and ensure that your Matrix Synapse server is securely accessible.

Microsoft Azure AD Tenant

To integrate Matrix Synapse with Microsoft Azure Active Directory (Azure AD) using OpenID Connect (OIDC), the first step is to register an application in Azure AD. This registration allows Synapse to authenticate users via Azure’s identity platform.

Start by logging into the Microsoft Entra Admin Center using an administrator account. Once logged in:

1. In the left-hand navigation pane, go to “App registrations”.
2. Click “New registration” to create a new application.

When the registration form appears, fill in the following details:

• Name: Give your application a recognizable name, such as Matrix Synapse OIDC.
• Supported Account Types: Choose one of the following based on your needs:
  • Single tenant – Only users from your organization’s Azure AD can sign in.
  • Multitenant – Users from any Azure AD organization can sign in.
  • Personal Microsoft Accounts – Allows Microsoft account users to authenticate.
• Redirect URI: This is the callback URL where Azure AD will send authentication responses
  
  Example: https://matrix.example.com/_synapse/client/oidc/callback
• Ensure that the URL matches the configuration in your Matrix Synapse setup.

3. Click Register to finalize the app registration.

Once the app is registered, Azure AD provides critical details required for Synapse configuration:

• Application (client) ID: This uniquely identifies your registered app.
• Directory (tenant) ID: This identifies your Azure AD instance.

Copy these values, as they will be required when configuring Synapse. To allow Matrix Synapse to authenticate with Azure AD securely, you must create a client secret. Therefore, click Add and copy the client secret value immediately (it won’t be visible later).

• Go to Certificates & Secrets in your registered app.
• Click New client secret and provide a description.
• Set an expiration period (e.g., 6 months, 12 months, or never).

Database

For a production-ready Matrix Synapse setup, it is highly recommended to use PostgreSQL instead of the built-in SQLite database. Below are the steps to configure a PostgreSQL database for your Matrix instance. These steps are the same for both FreeBSD and Debian, where we simply create a user called matrix and a new database also called matrix with UTF8 encoding from template0:

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

Adjust Matrix Server Config

Now, we need to adjust or Matrix Synapse homeserver.yaml config file. Take care about your file location, depending on your setup.

Configuration File Locations

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

This YAML file is the heart of your Synapse installation, allowing you to fine-tune server behavior, database connections, federation settings, and authentication mechanisms.

Switching to PostgreSQL for Production

By default, Synapse uses an SQLite database, which is fine for testing but unsuitable for production due to performance limitations. To replace SQLite with a more scalable PostgreSQL instance, follow these steps:

Open homeserver.yaml and locate the database block. Replace it with the following template, modifying it to match your PostgreSQL credentials:

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

Ensure that PostgreSQL is running and that your user has the necessary permissions to access the database. This config ensures that we can now use PostgreSQL as a database backend but we still need to integrate our Microsoft Azure AD configuration to use our OIDC authentication.

Adding Microsoft Azure AD OIDC Provider

To enable the OIDC provider with Microsoft Azure ID, we simply need to add an oidc provider to our Matrix Synapse homeserver.yaml. Therefore, we simply add the following chapter in the same config:

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

When setting up Matrix Synapse, you may need to configure an additional Virtual Host (VHost) in Nginx to ensure that your instance is properly accessible over HTTPS and federates correctly with other Matrix servers. This guide will walk you through the process of adding a new VHost configuration for your setup on both Linux (Ubuntu/Debian) and FreeBSD.

Configuration File Locations

• Debian: /etc/nginx/sites-enabled/matrix.example.com.conf
• FreeBSD: /usr/local/etc/nginx/sites-enabled/matrix.example.com.conf

Note: Make sure to replace example.com with your actual domain name for your Matrix instance.

server {
    listen 80;
    listen [::]:80;
    server_name matrix.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

server {
    listen 8448 ssl http2;
    listen [::]:8448 ssl http2;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Note: Depending on your certbot installation the path to your PKI files may vary.

Restart The Service

Afterwards, we have everything configured and can now restart the service by running the following command – depending on our system:

# FreeBSD
service matrix-synapse restart
service nginx restart

# Debian
systemctl restart matrix-synapse
systemctl restart nginx

Conclusion

In conclusion, integrating open-source chat tools like Matrix Synapse on systems such as FreeBSD or Debian with Microsoft Azure AD via OIDC offers a powerful combination of flexibility, security, and ease of use for businesses. By leveraging single sign-on (SSO) and centralized user management, companies can streamline user authentication while enforcing multi-factor authentication (MFA) for an added layer of security. This integration not only enhances the security posture but also fosters a seamless transition into open-source solutions, making them more accessible and attractive to businesses that are already familiar with Microsoft Azure AD. By supporting widely adopted enterprise tools alongside open-source platforms, companies can effectively balance innovation with security, reducing friction and raising the acceptance of open-source solutions in the workplace. This approach aligns with the growing demand for secure, scalable, and cost-effective communication tools, empowering organizations to thrive in a modern, interconnected ecosystem – where the next steps can now lead into replacing Microsoft Azure AD.