Microsoft 365 OAuth for EGroupware Mail

This page explains how to connect Microsoft 365 (Exchange Online) mailboxes to EGroupware Mail with OAuth2, and what an Entra ID (Azure AD) or Exchange Online administrator has to allow for it to work.

• No app registration in your tenant is needed. EGroupware uses its own multi-tenant Microsoft app. You do not create a client ID, client secret or redirect URI.
• Each user signs in to Microsoft once in a popup window (MFA is supported). EGroupware then stores a refresh token and accesses the mailbox via IMAP and SMTP with XOAUTH2.
• Your tenant must allow consent to the EGroupware app, and the mailboxes must have IMAP and SMTP AUTH enabled.

EGroupware does not use application permissions (IMAP.AccessAsApp) or the client credentials flow, so the Microsoft procedure with New-ServicePrincipal and Add-MailboxPermission is not required.

OAuth is used for onmicrosoft.com, Outlook, Hotmail and Live addresses, and for custom domains whose mailboxes are hosted in Microsoft 365 (mail server outlook.office365.com / smtp.office365.com).

On the first sign-in, Microsoft asks for consent to the permissions listed above.

• If users may consent to apps in your tenant, every user consents in the popup themselves.

• If user consent is restricted (common in organisations), an administrator must grant consent for the whole tenant once. Open the following URL as a Global Administrator, Privileged Role Administrator or Cloud Application Administrator, replace <tenant> with your tenant ID or primary domain, and accept:

  https://login.microsoftonline.com/<tenant>/adminconsent?client_id=eb5e2a98-70a2-471c-9e0a-a665ba1dfb0e
  

  Alternatively, after a first sign-in attempt, grant consent under Entra admin center > Enterprise applications > EGroupware > Permissions > Grant admin consent.

After consent, the app shows up in your tenant as an Enterprise application. It is registered in EGroupware's tenant, not in yours, so there are no secrets or certificates for you to manage.

Sign-in happens in a browser popup on the user's device. Conditional Access policies that block unknown apps or locations, or that require a compliant or hybrid-joined device, can block it. Exclude the EGroupware enterprise application or adjust the policy if users get an access error after signing in.

According to Microsoft, SMTP AUTH is disabled while Security Defaults are enabled. Receiving mail via IMAP works, but sending fails. To send mail through EGroupware, disable Security Defaults and protect the tenant with Conditional Access instead, or send via another SMTP server.

Run these commands in Exchange Online PowerShell (Connect-ExchangeOnline).

IMAP must be enabled for the mailbox:

Get-CASMailbox -Identity user@example.com | Format-List ImapEnabled
Set-CASMailbox -Identity user@example.com -ImapEnabled $true

SMTP AUTH must be enabled, either for the whole organisation:

Set-TransportConfig -SmtpClientAuthenticationDisabled $false

or only for the mailboxes that use EGroupware (the mailbox setting overrides the organisation setting):

Set-CASMailbox -Identity user@example.com -SmtpClientAuthenticationDisabled $false

In the Microsoft 365 admin center, the per-mailbox setting is under Users > Active users > (user) > Mail > Manage email apps > Authenticated SMTP.

Changes can take some time to become effective.

1. Add the account in EGroupware Mail (or as administrator in Admin > Mail accounts) with the Microsoft 365 e-mail address.
2. Leave the password fields for IMAP and SMTP empty. An empty password means "use OAuth, if supported".
3. A popup opens with the Microsoft sign-in. Sign in, complete MFA if required, and accept the consent screen.
4. The popup closes automatically, the token is saved and the mail app refreshes.

If the message "Successful, but NO refresh-token received!" appears, sign-in worked but Microsoft did not return a refresh token. Check that consent includes offline_access and try again.

Sieve (server-side filters and vacation notices) is not available for Microsoft 365 accounts. Use the rules in Outlook on the web instead.

• Outgoing HTTPS from the EGroupware server to login.microsoftonline.com must be allowed. If you use an HTTP proxy, configure it in EGroupware setup.
• The session cookie SameSite setting must not be Strict, because the sign-in returns to EGroupware via a cross-site redirect.
• Keep EGroupware up to date. The Microsoft app, its secret and fixes for Microsoft sign-in are delivered with EGroupware updates.

Recent EGroupware versions have the setup option Microsoft Tenant ID (below the IdP URL in the setup configuration). If you enter your tenant ID there, Microsoft sign-ins are only accepted for that tenant.

If OAuth worked before and has stopped, the cause is usually a change in the Microsoft 365 tenant or mailbox. Check in this order:

1. Reconnect the account in EGroupware. Open the mail account and go through the Microsoft sign-in in the popup again. If only the refresh token had become invalid (e.g. after a password reset or revoked sessions), this fixes it. If it fails, note the error message shown, especially any AADSTS… code.

2. Entra sign-in logs. In the Entra admin center go to Monitoring > Sign-in logs and filter by the application "EGroupware" or the application ID eb5e2a98-70a2-471c-9e0a-a665ba1dfb0e. Failed sign-ins show the error code and the reason, e.g. a blocking Conditional Access policy or missing consent. This is usually the quickest way to find the cause.

3. Enterprise application. Under Enterprise applications, check that the EGroupware app still exists, that Enabled for users to sign-in? is set to Yes, and that the granted permissions (consent) are still in place.

4. Mailbox protocols. Check IMAP and SMTP AUTH for the affected mailbox:

   Get-CASMailbox -Identity user@example.com | Format-List ImapEnabled, SmtpClientAuthenticationDisabled
   Get-TransportConfig | Format-List SmtpClientAuthenticationDisabled

   ImapEnabled must be True. SmtpClientAuthenticationDisabled must be False on the mailbox, or empty on the mailbox and False for the organisation.

5. Recent tenant changes. Check whether anything changed around the time the problem started: new or changed Conditional Access policies, Security Defaults enabled, a stricter user consent policy, password resets or revoked sessions for the user.

• Microsoft: Authenticate an IMAP, POP or SMTP connection using OAuth
• Microsoft: Enable or disable SMTP AUTH in Exchange Online
• Forum: Email: OAuth with Microsoft mail servers and GMail