Connect Gmail or Microsoft 365 to Nextcloud Mail Using OAuth2

To connect Gmail or Microsoft 365 to Nextcloud Mail with OAuth2, register a web application with the mail provider, copy Nextcloud Mail’s redirect URI into that registration, and save the client ID and secret under Nextcloud’s Groupware administration settings. Then connect the mailbox in Mail and approve the provider’s sign-in prompt. A working setup must both load incoming messages and send a test message—not merely display a successful authorization screen.

Check that your account and Nextcloud installation fit this method

Nextcloud Mail uses IMAP to read messages and SMTP to send them. OAuth2 obtains permission from the identity provider; XOAUTH2 is the mechanism the mail client uses to present an access token to these mail services. It does not turn the Nextcloud login into a universal single sign-on for every mail server.

Nextcloud’s current administration documentation describes dedicated Gmail OAuth and Microsoft Outlook XOAUTH2 integrations. Microsoft support was added in Mail 3.0.0; menu wording may vary with Mail and Nextcloud releases. This walkthrough is based on the Nextcloud 35 Mail administration manual, current as checked in October 2026.

• Use an HTTPS Nextcloud URL that opens reliably from a browser, with the Mail app installed and enabled.
• Have Nextcloud administrator access and permission to register an OAuth application in Google Cloud or Microsoft Entra.
• Know whether the account is Gmail/Google Workspace, Outlook.com, or a Microsoft 365 mailbox hosted in Exchange Online.
• Confirm the provider permits IMAP access and, for sending, authenticated SMTP under the organization’s policies.

Important limit: a custom IMAP provider that accepts OAuth2 is not automatically supported by Nextcloud Mail’s Gmail/Microsoft configuration screens. The Nextcloud Mail feature request for generic OAuth2 providers documents this distinction. For another provider, check your exact Mail release and its supported authentication methods rather than entering unrelated Google or Microsoft credentials.

Register an OAuth client with the right redirect URI

Gmail or Google Workspace

1. In Nextcloud, sign in as an administrator, open Administration settings → Groupware, and locate Gmail integration. Copy the redirect URI shown by your instance. Do not assume a URL copied from someone else’s installation is correct.
2. Open Google Cloud Console and select or create a project. Configure the Google Auth Platform consent/branding and audience settings as appropriate for your Workspace organization or external users; add test users if the application remains in Testing.
3. Create an OAuth client of type Web application. Put the exact URL from Nextcloud in Authorized redirect URIs, then save the client ID and client secret securely. Google requires a literal redirect URI match, including scheme, path, capitalization, and trailing slash.
4. Review the authorization scopes and publishing requirements. Gmail IMAP and SMTP OAuth access uses https://mail.google.com/, a broad restricted scope subject to Google’s user-data and verification policies. The administrator must determine whether the proposed use can meet those requirements.

Google documents the web-server registration flow in its OAuth2 web application instructions and the specific Gmail XOAUTH2 scope and protocol. A test configuration is useful for initial validation, but an external OAuth application left in Testing generally receives refresh tokens that expire after seven days when requesting Gmail mail access. See Google’s token-expiration guidance. Repeated weekly reauthorization can therefore indicate a publishing-state limitation rather than a broken IMAP password.

Microsoft 365 or Outlook.com

1. In Nextcloud’s Administration settings → Groupware, find Microsoft integration and copy the displayed redirect URI.
2. In the Microsoft Entra admin center, go to App registrations and create a registration. For the account types described in Nextcloud’s standard guide, choose both organizational and personal Microsoft accounts; use a Web redirect platform and enter Nextcloud’s URI exactly.
3. Copy the Application (client) ID. Under Certificates & secrets, create a client secret and copy its value immediately, not the secret identifier. Record its expiration in your operations calendar.
4. Use the mail-related delegated permissions required for the provider’s IMAP and SMTP OAuth flow, with organizational consent where required. Microsoft documents the IMAP.AccessAsUser.All and SMTP.Send scopes as well as offline_access for refresh tokens. Do not confuse these protocol permissions with Microsoft Graph Mail.Read/Mail.Send permissions.

For registration details, consult Microsoft’s app registration documentation and Exchange Online’s IMAP/SMTP OAuth instructions. Nextcloud’s documented general-purpose setup leaves the tenant field at common. A tenant-specific value or narrower supported audience should be used only when the administrator has verified the associated account-type and policy changes.

Save the credentials in Nextcloud and connect the mailbox

1. Return to Administration settings → Groupware. Paste the provider’s client ID and client secret into the corresponding Gmail integration or Microsoft integration section, and save. Never put the secret into the redirect URI field or publish it in screenshots, tickets, or version control.
2. Sign in as the intended mailbox user, open Mail, and choose to add a mail account. Enter its email address, select the automatic account configuration first, and start connecting. Nextcloud’s documented Microsoft flow may still present a password field; the entered placeholder is discarded when provider OAuth is configured. Do not substitute a real account password unnecessarily.
3. In the provider’s pop-up window, select the correct Google or Microsoft identity, review the requested access, and grant consent if approved by your organization. Allow browser pop-ups and return to the original Nextcloud tab after the provider redirects back.
4. If automatic configuration selects the wrong server, inspect the manual IMAP and SMTP hostnames and encryption options for that particular provider. The OAuth button is associated with recognized Gmail/Microsoft endpoints; manually entered unrelated hostnames may not activate the expected sign-in flow.

In the Nextcloud Mail account form, a recognized Google endpoint with OAuth configured can show Sign in with Google, and the Microsoft equivalent can show Sign in with Microsoft. The live Nextcloud Mail account form source documents these conditional labels. The presence of the provider-specific button is a useful early sign that Nextcloud has recognized the intended integration, but it does not prove that authorization or mailbox access has completed.

Resolve failures by the stage at which they occur

Microsoft explains the SMTP AUTH control, including the per-mailbox override, in its Exchange Online SMTP AUTH documentation. Avoid globally weakening mail security just to make one mailbox work; if policy prohibits the protocol, use an approved mail client or organization-supported workflow instead.

Verify both directions of mail flow

1. Open Inbox in Nextcloud Mail, refresh, and confirm that a recently received message appears with the expected sender, subject, and contents.
2. Send a short test email to another mailbox you control. Verify delivery there, then check the Sent folder in Nextcloud Mail. This separates SMTP permission problems from IMAP sync problems.
3. Sign out and back in, then reopen Mail. For operational deployments, recheck after the access token would normally have been refreshed; immediate success does not prove long-term token renewal.

If the inbox still fails to synchronize, Nextcloud documents occ mail:account:export to find the mail account ID and occ mail:account:sync -vvv ACCOUNT_ID for targeted troubleshooting. Its Groupware troubleshooting manual also explains per-account IMAP/SMTP debug logging and warns that logs may contain sensitive information. Capture only what is needed, redact tokens and addresses before sharing, and turn verbose debugging off afterward.

The setup is ready for use when provider consent completes, Mail can retrieve current messages, outgoing mail reaches its destination, and the connection stays usable without repeated authorization prompts. If any one of those checks fails, troubleshoot that specific stage instead of recreating the entire OAuth application immediately.