Configuring OAuth for SOGo in iRedmail

*AI generated**

iRedMail is a free, open-source mail server solution that lets you quickly set up a full-featured email server on Linux. Rather than manually installing and configuring each component individually, iRedMail automates the entire process through a shell script that bundles together all the software needed to run a production-ready mail server.

It comes with the following components for each service;

• Postfix — sending/receiving mail (SMTP)
• Dovecot — mail storage and retrieval (IMAP/POP3)
• SOGo and/or Roundcube — webmail interfaces
• SpamAssassin / Amavis / ClamAV — spam and virus filtering
• OpenLDAP or MySQL/PostgreSQL — user/domain account storage
• Nginx — web server for the webmail frontend
• Fail2Ban — brute force protection

This article is focused on integrating OAuth for SOGo webmail client using OpenID Connect (OIDC) together with Dovecot, Postfix and OpenLDAP in iRedmail. This also assumes that an Identity provider (IdP) is currently installed and running.

To install iRedmail, follow the official guide at **https://docs.iredmail.org**

The article is based on the implementation by Markus Petermann

Step 1: OpenID Client

To enable OIDC for SOGo, a client application must be registered on your IdP such as Keycloak, Authentik, or any other OIDC-compatible provider. This client acts as the bridge between SOGo and the IdP, defining how authentication requests are handled and which flows are permitted. During setup, you will typically configure the client with a confidential authentication mode (requiring a client secret), enable the Authorization Code flow so that users are securely redirected to the IdP login page, and set the root or base URL to point to your SOGo mail server domain. Once registered, the IdP will issue a client ID and secret, which SOGo will use to verify user identities without ever handling passwords directly.

Step 2: Configuring SOGo

Out of the 2 webmail applications, SOGo and Roundcube, only SOGo is configured to authenticate with OIDC. We can choose whether to keep Roundcube or not during the installation or by disabling plaintext authentication which is mentioned later in this article.

Before SOGo configuration is changed, a table in the sogo database should be created to manage OIDC sessions.

# For MySQL (iRedMail default)
mysql -u root

USE sogo;

CREATE TABLE IF NOT EXISTS sogo_openid (
    c_user_session TEXT NOT NULL,
    c_old_session TEXT,
    c_session_started INT(11) NOT NULL,
    c_refresh_token TEXT,
    c_access_token_expires_in INT(11),
    c_refresh_token_expires_in INT(11)
);

GRANT ALL PRIVILEGES ON sogo.sogo_openid TO 'sogo'@'localhost';
FLUSH PRIVILEGES;
EXIT;

SOGo keeps its configuration in the sogo/sogo.conf file. Add or edit the following parameters in the file. Replace values in angled brackets with your values.

sogo/sogo.conf

NGImap4AuthMechanism = xoauth2;

SOGoXSRFValidationEnabled = NO;

OCSOpenIdURL = "mysql://sogo:<database_pwd_for_db_user_sogo>@127.0.0.1:3306/sogo/sogo_openid";

SOGoSMTPAuthenticationType = xoauth2;

SOGoSieveServer = "sieve://127.0.0.1:4190/?tls=YES&tlsVerifyMode=allowInsecureLocalhost";

SOGoTimeZone = "<TimeZone>";

SOGoAuthenticationType = openid;
SOGoOpenIdClient = "<Client_Id_from_the_IdP>";
SOGoOpenIdClientSecret = "<Client_secret_from_the_IdP>";

SOGoOpenIdConfigUrl = "https://<idp-domain>/.well-known/openid-configuration";
SOGoOpenIdIssuer = "https://<idp-domain>";
SOGoOpenIdAuthorizationEndpoint = "https://<idp-domain>/protocol/openid-connect/auth";
SOGoOpenIdTokenEndpoint = "https://<idp-domain>/protocol/openid-connect/token";
SOGoOpenIdUserinfoEndpoint = "https://<idp-domain>/protocol/openid-connect/userinfo";
SOGoOpenIdJWKSEndpoint = "https://<idp-domain>/protocol/openid-connect/certs";
SOGoOpenIdScope = "openid profile email";
SOGoOpenIdEmailParam = "preferred_username";
SOGoOpenIdEnableRefreshToken = YES;
SOGoOpenIdTokenCheckInterval = 30;
SOGoOpenIdLogoutEnabled = YES;

As per the guide by Markus;

SOGo seems unable to use OpenID alone; instead, an additional UserSource is used to look up the user and their metadata after successful authentication. In this case, the preferred_username value (which in our case is <firstname.lastname>) is used to find the respective user entry in the LDAP directory.

So the;

SOGoUserSources = (
{
type = ldap;
id = example;
CNFieldName = cn;
IDFieldName = uid;
UIDFieldName = uid;
IMAPLoginFieldName = uid; // username used for Dovecot/Postfix
MailFieldNames = (mail);
baseDN = "cn=users,cn=accounts,dc=ldap,dc=example,dc=net";
filter = "(objectClass='inetorgperson') AND (memberOf='cn=mailusers,cn=groups,cn=accounts,dc=ldap,dc=example,dc=net')";
bindDN = "uid=sogo,cn=sysaccounts,cn=etc,dc=ldap,dc=example,dc=net";
bindPassword = foobar;
bindFields = (uid);
bindAsCurrentUser = NO;
canAuthenticate = YES;
hostname = "ldap://127.0.0.1:389";
......
});

block is configured by default for users to be able to access the LDAP (There is another user source for the global address book with canAuthenticate=NO. Choose the correct section). In this, the bindDN and bindPassword comes by default with the read only admin account in iRedmail. when bindAsCurrentUser is set to YES, SOGo first binds the bindDN user to search the relevant user in the LDAP after login, and then binds as the user to the LDAP again to make the user only access its directory. If the user needs to access other users’ directories, set this to NO.

Then restart the SOGo

systemctl restart sogod
#Don't forget the "d" at the end

Step 3: Dovecot configuration

This step is based on based on the guide by Open-xchange Step 1.1.

Dovecot is the IMAP/POP3 server in iRedmail. it handles mailboxes, mail retrieval and in this case the authentication for users.

dovecot/dovecot-oauth2.conf.ext file teaches Dovecot how to validate OAuth2 tokens issued by your IdP. When a mail client sends an XOAUTH2 token, Dovecot forwards it here to verify it and retrieve user details.

Add the below to the new file.

dovecot/dovecot-oauth2.conf.ext

tokeninfo_url = https://<idp-domain>/protocol/openid-connect/userinfo?ignore=
#Use introspection instead of tokeninfo
#introspection_url = https://<idp-domain>/protocol/openid-connect/token/introspect
#introspection_mode = post

# Client credentials for introspection
client_id = <Client_Id_from_IdP>
client_secret = <Client_secret_from_IdP>

# How to extract username from token response
username_attribute = preferred_username
username_format = %{preferred_username}

# Token validation
active_attribute = active
active_value = true

# SSL configuration
tls_ca_cert_file = /etc/ssl/certs/ca-bundle.crt

introspection endpoint requires another client to be created in IdP. So the tokeninfo_url can be used instead. username_attribute can be set to preferred_username depending on the implementation, for example email. Make sure the IdP is mapped correctly with the LDAP to use the intended username.

dovecot/dovecot.conf is the main configuration file for Dovecot. It wires together authentication methods, SSL policy, and the passdb/userdb stack.

dovecot/dovecot.conf

auth_verbose = yes
auth_debug = yes

auth_mechanisms = PLAIN xoauth2 LOGIN

# With disable_plaintext_auth=yes AND ssl=required, STARTTLS is mandatory.
# Set disable_plaintext_auth=no AND ssl=yes to allow plain password transmitted
# insecurely.

disable_plaintext_auth = yes
ssl = required

#listener for postfix (use tcp listener if postfix is on a different server[See step 4])
service auth {
    unix_listener /var/spool/postfix/private/dovecot-auth {
        user = postfix
        group = postfix
        mode = 0660
}    }

# Virtual mail accounts.
userdb {
    args = /etc/dovecot/dovecot-ldap.conf
    driver = ldap
}
#password authentication from IdP. link the previously created file here.
passdb {
    driver = oauth2
    mechanisms = xoauth2
    args = /etc/dovecot/dovecot-oauth2.conf.ext
}

# LDAP for 3rd party email clients (password authentication). This can be removed if plaintext authentication is to be removed.
passdb {
  driver = ldap
  mechanisms = plain login
  args = /etc/dovecot/dovecot-ldap.conf
}

oauthbearer is not needed as SOGo uses xoauth2.

xoauth2 is required for OAuth2-based clients (SOGo). PLAIN and LOGIN can be kept if legacy IMAP clients that use passwords directly, are required (Roundcube, Thunderbird etc.). removing PLAIN and LOGIN will make Roundcube in iRedmail unusable too. The two passdb blocks are tried in order. OAuth2 clients hit the first and succeed; password clients fall through to the second.

If plain authentication with an LDAP backend is used for other email clients, the *userdb*configuration might need to be changed from static to ldap, including the LDAP-specific configuration.

dovecot/conf.d/10-auth.conf is loaded by Dovecot’s modular config system and handles SOGo’s special master-user authentication. Add the below lines to the file.

dovecot/conf.d/10-auth.conf

# Allow SOGo to use master user authentication
passdb {
  driver = passwd-file
  master = yes
  args = /etc/dovecot/master-users
  pass = yes
  skip = unauthenticated
}

It defines a master user passdb using a flat password file. SOGo needs to access any user’s mailbox on their behalf (e.g., to sync calendars, handle shared folders, or proxy IMAP connections). Master user auth allows SOGo to authenticate as sogo*targetuser using its own credential, bypassing the target user's password. skip = unauthenticated means this passdb is only consulted when a master user login is actually attempted.

dovecot/dovecot-ldap.conf tells Dovecot’s LDAP driver to verify passwords by actually binding to the LDAP server as the user, rather than fetching the password hash and comparing locally. Dovecot never sees or stores the password. The LDAP server (in this case OpenLDAP) handles the credential check natively, respecting account lockouts, password policies, and expiry rules.

dovecot/dovecot-ldap.conf

auth_bind = yes

Restart the Dovecot service

systemctl restart dovecot

Step 4: Postfix configuration

This step is based on based on the guide by open-xchange Step 1.2. The redirection link is deprecated. Refer this as the updated guide. Section “Dovecot authentication via TCP” in that guide is irrelevant as the same server hosts Dovecot and Postfix both.

Postfix is the Mail Transfer Agent (MTA) that uses SMTP to deliver mails out of SOGo. This step refers to configuring Postfix to use Dovecot as its Simple Authentication and Security Layer (SASL) authentication backend. When a mail client connects to Postfix to send mail (SMTP AUTH), Postfix delegates the credential check to Dovecot rather than handling it itself.

postfix/main.cf is the main Postfix configuration file. Edit the following settings.

postfix/main.cf

smtpd_sasl_type = dovecot

# Sender restrictions
smtpd_sender_restrictions =
    reject_non_fqdn_sender
    reject_unlisted_sender
    permit_mynetworks
    permit_sasl_authenticated
    check_sender_access pcre:/etc/postfix/sender_access.pcre
    reject_unknown_sender_domain
    reject_sender_login_mismatch
    reject_authenticated_sender_login_mismatch

# Can be an absolute path, or relative to $queue_directory
# Debian/Ubuntu users: Postfix is setup by default to run chrooted, so it
# is best to leave it as-is below
smtpd_sasl_path = private/dovecot-auth

# and the common settings to enable SASL:
smtpd_sasl_auth_enable = yes

smtpd_sasl_security_options = noanonymous
smtpd_sasl_tls_security_options = noanonymous
smtpd_tls_auth_only = yes

# With Postfix version before 2.10, use smtpd_recipient_restrictions
# allow mail from your own networks OR from clients that successfully authenticated via SASL, reject everything else
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination

When Dovecot is used as the authentication driver for Postfix, it is good practice to use a dedicated submission port for Mail User Agents (TCP 587).

Add the following to postfix/master.cf in the correct lines. Usually they are commented.

postfix/master.cf

submission inet n       -       n       -       -       smtpd
  -o syslog_name=postfix/submission
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_tls_auth_only=yes
  -o smtpd_sasl_type=dovecot
  -o smtpd_sasl_path=private/dovecot-auth
  -o smtpd_sasl_security_options=noanonymous
  -o smtpd_sasl_local_domain=$myhostname
  -o smtpd_sender_login_maps=hash:/etc/postfix/virtual
  -o smtpd_client_restrictions=permit_sasl_authenticated,reject
  -o smtpd_sender_restrictions=reject_sender_login_mismatch
  -o smtpd_recipient_restrictions=reject_non_fqdn_recipient,reject_unknown_recipient_domain,permit_sasl_authenticated,reject
  -o milter_macro_daemon_name=ORIGINATING
smtps     inet  n       -       n       -       -       smtpd
  -o syslog_name=postfix/smtps
  -o smtpd_tls_wrappermode=yes
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_sasl_type=dovecot
  -o smtpd_client_restrictions=permit_sasl_authenticated,reject
  -o smtpd_sender_restrictions=reject_sender_login_mismatch,permit_sasl_authenticated,reject
  -o smtpd_recipient_restrictions=permit_sasl_authenticated,reject_unauth_destination
  -o milter_macro_daemon_name=ORIGINATING

Restart Postfix service

systemctl restart postfix

Step 5: Nginx Configuration

A guide on Apache configuration is given by Markus Petermann. Apache was dropped since iRedMail-0.9.8. The Nginx template for SOGo will be saved at nginx/templates/sogo.tmpl

It is assumed that the Nginx is configured with SSL/TLS, the proxy paths, and the certificate paths beforehand. If not, follow the guide on Running web applications under subdomain with Nginx.

Additionally add the following header to the configuration file under location /SOGo.

proxy_set_header X-Forwarded-Proto https;

Reload nginx service (no need to restart)

systemctl reload nginx