Set Up an SMTP Relay Server

Updated
  • 3 minute(s) read
Prev Next

Starting March 1, 2026, Microsoft will reject Simple Mail Transfer Protocol (SMTP) connections that use basic authentication; username and password authentication. After this date, attempting to send email using just a username and password will fail with an error and only modern authentication (OAuth 2.0) will be valid. That means that Microsoft will refuse connections with a username and password over SMTP, even with TLS, after the deadline.

To send mail through Microsoft 365 without basic authentication, you need to authenticate with Azure Entra ID and obtain an OAuth token.

To resolve this change, CTERA requires setting up an SMTP relay server to act as an intermediary mail server.

smtp-oauth-relay is a lightweight SMTP relay service that accepts traditional username/password SMTP connections from legacy applications or devices. The relay exposes an SMTP endpoint that clients connect to with a special username format, tenant and client ID, and the Azure app client secret as the password. The service then performs OAuth2 token acquisition and sends messages on behalf of the configured Microsoft 365 tenant using Microsoft Graph.

Prerequisites

  • An SMTP proxy machine with docker services installed.

  • A TLS certificate.
    The SMTP OAuth Relay does not require any specific certificate from CTERA Portal or Microsoft Azure. You can use any valid TLS certificate to secure the SMTP connection, including:

    • Existing organizational certificates (wildcard or single-domain)
    • Self-signed certificates
    • Certificates from any trusted Certificate Authority such as GoDaddy, DigiCert, etc.

    The following table the TLS certificate options.

    Option Trust configuration Best for
    Organizational CA-signed certificate Automatically trusted if CA is in client trust store Enterprise environments
    Public CA certificate (such as GoDaddy, etc. Automatically trusted by all clients Production deployments
    Wildcard certificate like *.yourdomain.com Automatically trusted Multiple services sharing one certificate
    Self-signed certificate Must be imported into client trust store Testing, isolated environments

Step-by-step guide

  1. Prepare directory and certificates on the SMTP Relay host
    1. Create a working directory for TLS certificates on the SMTP Relay host: mkdir -p ~/smtp-relay/certs
    2. Copy the certificate files to ~/smtp-relay/certs directory and verify that there are two certificate files, like the following:
      [root@localhost ~]# ls -l /root/smtp-relay/certs
total 8
-rw-r--r--. 1 root root 1826 Jan 19 13:45 cert.pem
-rw-------. 1 root root 3272 Jan 19 13:45 key.pem
[root@localhost ~]#
    3. For an organizational or self-signed certificate, import it into CTERA Portal’s trust store by running the following on the CTERA Portal server:
    portal-cert.sh import -f cert.pem smtp-relay
portal-manage restart
    Note

    The SMTP relay's TLS certificate is to encrypt the SMTP connection and is completely independent of Azure authentication or application-specific certificates.

  2. Pull and run the official container image.
    The official image is published to GitHub Container Registry. Pull the image and then run it, mounting the certificates directory and using the environment file created above.
    docker run -d --name smtp-relay \
-p 8025:8025 \
-v /root/smtp-relay/certs:/usr/src/smtp-relay/certs:ro \
-e LOG_LEVEL=DEBUG \
-e TLS_SOURCE=file \
-e TLS_CERT_FILEPATH=/usr/src/smtp-relay/certs/cert.pem \
-e TLS_KEY_FILEPATH=/usr/src/smtp-relay/certs/key.pem \
-e REQUIRE_TLS=true \
ghcr.io/justiniven/smtp-oauth-relay:latest
  3. Check the container logs by running the following command docker logs -f smtp-relay
  4. You must allow inbound TCP traffic on the SMTP port that you mapped from the container (8025 in the above example) using the following commands:
    sudo firewall-cmd --permanent --add-port=<port>/tcpn
sudo firewall-cmd --reload
    Where is the SMTP port that you mapped from the container.
  5. Setup Azure Entra . using the below guide
    Note

    The following guide can be used to help you set up Azure Entra ID: https://github.com/JustinIven/smtp-oauth-relay/blob/main/docs/azure-setup.md.

  6. Clients on the network connect to the host on the SMTP port, such as port 8025, using STARTTLS and authenticate with Azure app credentials (tenant ID and client ID as the username, client secret as the password) per the smtp-oauth-relay documentation.
    Note

    STARTTLS is an email command that upgrades an existing, insecure SMTP connection to a secure, encrypted one using TLS on the configured port.

The SMTP username combines two Azure identifiers: <tenant-id>@<client-id> and the SMTP password value is the Client Secret value.

Related articles