Configure Postfix SMTP Relay using OAuth2

In the environment of self-hosting several solutions, one of the main pain points has been setting up SMTP within those services. It is a struggle that is amplified only by rudimentary support within the applications. I have had issues integrating STARTTLS and TLS reliably, and the main solutions involve using a third-party mail relay to handle forwarding.

I refused to accept this reality and started looking for potential avenues to get SMTP working with a local mail relay.

Solution

With the use of the GitHub project sasl-xoauth2, I have been able to resolve onsite SMTP needs using Microsoft Exchange Online for integration. The project sets up an OAuth2 session by creating an application within a Microsoft tenant. The project supports a wide range of setups, but currently only a single account setup will be documented in this section.

I recommend giving their documentation a read. Referencing both sites may provide greater detail into setting up the project for specific needs not covered by this documentation.

Requirements

Operating System and Software

This configuration has been tested on Debian 12. Instructions for Debian-based systems should be equivalent. Package names may differ between different repositories. All commands run in this section are run as root. Sudo may be appended where needed if running in a user terminal session.

We will use build tools and Postfix for sasl-xoauth2 setup. For debian, the full list of required build packages are listed below.

				
					sudo bash
apt install git build-essential cmake pandoc python3-argparse-manpage \
pkg-config curl libcurl4-openssl-dev libjsoncpp-dev libsasl2-dev \
python3-distutils python3-msal -y

Install postfix if not already present. In the setup menu that opens, select “Ok” followed by “No Configuration.”

				
					apt install postfix -y

Microsoft Identity

You must have a Microsoft tenant account for this guide. This will allow access to the application API which will be used to create the necessary OAuth connection for SMTP.

You must have a user account and password with which you plan on sending mail with. All emails used to send mail must be registered to the user through Exchange, otherwise it will be rejected.

Network Structure

This project assumes the SMTP relay server is postured to receive connections from only allowlisted local IP addresses. This reduces the attack surface and liability of hosting a compromised SMTP server.

The SMTP server will be set up with only allowlisted IPs with no client authentication. This means that any service connecting from an allowlisted IP is allowed to send any set of credentials (including none) and the relay server will accept it. For this reason, the SMTP server and all connecting servers should be hardened as needed.

Installation

Enable SMTP authentication

The following set of steps establish setting up SMTP authentication access via Exchange.

Log into exchange.microsoft.com with administrator credentials.
Go to settings, then mailflow.
Uncheck Turn off SMTP Auth Protocol for your organization and click save.

SMTP authentication must also be turned on for the user being used as part of the relay server. Create a user following your tenant environment’s procedure.

Log into admin.microsoft.com with administrator credentials.
On the left menu, select Users, then Active Users.
Click on the account that will be used for SMTP.
In the right menu that opens, go to Mail, then Manage Email Apps.
Check the Authenticated SMTP option and save all changes.

Install sasl-xauth2

SSH into the relay server.
Visit the Github website at https://github.com/tarickb/sasl-xoauth2 from a browser.
- Confirm the repository is still available at https://github.com/tarickb/sasl-xoauth2.git
Run the commands provided below. Replace any text in [brackets].

				
					cd /usr/local/src
git clone [repo]
cd sasl-xoauth2
mkdir build
cd build

Build the project from source. This may prove difficult depending on the operating system being used and any changes made to the source code. Troubleshooting should begin at verifying necessary packages are installed.

				
					cmake ..
make
make install

The source code as of February 2025 did not properly link the needed files to the correct location. Create a symbolic link from the install location to the expected location.

				
					ln -s /usr/local/lib/sasl2/libsasl-xoauth2.so /usr/lib/x86_64-linux-gnu/sasl2/libsasl-xoauth2.so

Set Up Postfix Initial Configuration

Edit the following configuration files and store them in their respective location. Replace all text in [brackets] but keep all <carots>.

/etc/postfix/main.cf

Creates the main configuration for Postfix. Certificates are specified to load them in properly.

The mynetworks section must be updated with each IP address or subnet connection. For example, a single IP is 192.168.1.5/32 while a subnet would be 192.168.1.0/24.

				
					smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options =
smtp_sasl_mechanism_filter = xoauth2
smtp_tls_security_level = encrypt
smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt
relayhost = [smtp.office365.com]:587
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
sender_canonical_maps = regexp:/etc/postfix/sender_canonical
mynetworks = 127.0.0.0/8, [other_networks_here]
smtpd_relay_restrictions = permit_mynetworks, defer_unauth_destination
smtp_header_checks = regexp:/etc/postfix/smtp_header_checks

/etc/postfix/sasl_passwd

Creates the file that tells Postfix to point to the OAuth token for authentication.

				
					[smtp.office365.com]:587
[username]@[domain]:/etc/tokens/[username]@[domain]

/etc/postfix/smtp_header_checks

This file specifies the sender’s name when the email is received. If not updated, the email will not have a presented name outside of the organization and will show up as [email protected] instead of John Smith.

				
					/^From:+/ REPLACE From: [name_presented_to_recipient] &lt;[email]&gt;

/etc/postfix/sender_canonical

This file specifies the sender’s name when the email is received. This is added to this file to support all mail configurations possible.

				
					/^sender_fullname:.+/ sender_fullname: [name_of_account]
/^From:.+/ from: [name_presented_to_recipient] &lt;[email]&gt;

/.+/ [email]

Finally, set up the files to be used by Postfix and restart the service. Postfix WILL NOT work yet.

				
					postmap /etc/postfix/sasl_passwd
postmap /etc/postfix/smtp_header_checks
postmap /etc/postfix/sender_canonical
systemctl restart postfix

Create Microsoft Application Link

				
					mkdir -p /home/ampdata/ssl
cp -a /etc/ssl/. /home/ampdata/ssl/
chmod 700 /home/ampdata/ssl
chown -R ampdata:ampdata /home/ampdata/ssl

Set Up Token Authentication

While still in the application created moments ago, go to overview.

Under Essentials, record the Client ID.
Under Essentials, record the Tenant ID.
Above essentials, select specifics and record the Oauth 2.0 Token Endpoint (v2) URL.

Create and edit the file below. Replace all text in [brackets].

/etc/sasl-xoauth2.conf

				
					{
  "client_id": "[ClientID]",
  "client_secret": "",
  "token_endpoint": "[Endpoint]"
}

Make a symbolic link to the location where sasl-xoauth2 expects the configuration to be at for testing purposes.

				
					rm /usr/local/etc/sasl-xoauth2.conf
ln -s /etc/sasl-xoauth2.conf /usr/local/etc/sasl-xoauth2.conf

Generate the token link for OAuth2 authorization. The tokens folder must also be created.

				
					mkdir /etc/tokens
sasl-xoauth2-tool get-token outlook \
    /etc/tokens/[email] \
    --client-id=[ClientID] \
    --use-device-flow \
    --tenant=[TenantID]

Go to the link provided in the terminal and provide the authentication code.

Log in with the email that will be used to send emails from.
Accept the application permissions.

Run the following commands to assign ownership. The next set of commands test functionality.

				
					chown -R postfix:postfix /etc/tokens

				
					sasl-xoauth2-tool test-config
sasl-xoauth2-tool test-token-refresh /etc/tokens/[email]

Restart postfix.

				
					systemctl restart postfix

Chroot Configuration

Postfix tends to run in a chroot environment. To test whether Postfix is running in chroot, run the command below:

				
					grep -E '^(smtp|.*chroot)' /etc/postfix/master.cf

If chroot is y, continue below. If not, installation is complete.

Create directories within the Postfix chroot directory and copy necessary files over.

				
					mkdir -p /var/spool/postfix/usr/local/etc
mkdir /var/spool/postfix/etc/tokens
mkdir -p /var/spool/postfix/etc/ssl/certs
cp /etc/ssl/certs/ca-certificates.crt /var/spool/postfix/etc/ssl/certs/ca-certificates.crt
cp /etc/sasl-xoauth2.conf /var/spool/postfix/etc/sasl-xoauth2.conf
ln -s /var/spool/postfix/etc/sasl-xoauth2.conf /var/spool/postfix/usr/local/etc/sasl-xoauth2.conf
cp -a /etc/tokens/. /var/spool/postfix/etc/tokens/

Finally, restart postfix. Installation complete.

				
					systemctl restart postfix

Functionality Testing

Edit the following file for sending a test email. Replace the text in [brackets].

/etc/postfix/testemail.txt

				
					to: [recipient_email]
subject: Test Postfix

Run the following command. If successful, an email should show up to the recipient.

				
					sendmail -v [recipient_email] &lt; /etc/postfix/testemail.txt

Testing complete. At this point, the Postfix server should be fully functional. This will allow you to point other servers’ SMTP settings to this new relay and forward mail. Note that sometimes the sender’s email with SMTP settings has to be set correctly, otherwise the relay will send mail under the email configured in the sending server’s configuration. This is useful for sending email under an alias.

Contributors

Edward Anguiano

Estimated Execution Time: 1 hour

Difficulty: Advanced

Knowledge of Microsoft 365 Required
Knowledge of SSH required
Knowledge of Postfix and SMTP protocol recommended
Basic Linux understanding recommended

Target System: Debian 12

Project constructed using Debian 12
Project HAS been reproduced

Problem