Last updated:
1 week ago
This article covers custom OAuth configuration for Thunderbird 155 and newer. See OAuth2 for Thunderbird for an overview.
Table of Contents
Overview
- Starting with Thunderbird 155, you can add your own custom OAuth configuration with an Thunderbird add-on or by manual config without code changes to Thunderbird for IMAP, and Exchange email accounts. Prior to 155, this required Thunderbird code changes.
- The examples given in this article are for Exchange but are it's possible to do this for any OAuth provider that supports Exchange, or IMAP. POP3 support is in progress (see bug 2061466).
- If you need help with OAuth2 configuration for a specific provider, please contact the provider's support team first to get the configuration details. Thunderbird support cannot provide provider-specific configuration details. Then, you can use the OAuth information provided by the provider to configure Thunderbird manually or via an add-on. If you need help with custom OAuth manual configuration, or a custom OAuth add-on, then please ask for support in the Thunderbird support forum and for Enterprise deployments, please ask in the Thunderbird Enterprise mailing list.
OAuth2 provider add-ons (recommended for administrators and organizations)
Who is this for?
- Organizations
- Universities
- IT administrators
- Third-party provider developers
Thunderbird provides a WebExtension API that allows add-ons to register OAuth2 providers. Please see: oauthProvider API.
An add-on can provide OAuth2 configuration including:
- Client ID
- Authorization endpoint
- Token endpoint
- Scopes
- PKCE settings
- Browser flow settings
This allows organizations to package their OAuth2 configuration once and deploy it to many users. The API now supports two deployment models:
- Registering OAuth2 providers for new mail services that Thunderbird doesn't already know about.
- Overriding Thunderbird's built-in OAuth2 configuration for selected email domains or entire hostnames. This allows an organization to replace Thunderbird's built-in configuration only where required, while continuing to use the built-in provider for everyone else.
For example, an organization using Microsoft 365 with its own Azure application registration can transparently replace Thunderbird's built-in Microsoft OAuth2 configuration for users in its own email domain, while all other Microsoft 365 users continue using Thunderbird's built-in configuration.
Thunderbird also displays when OAuth2 settings are being provided by an extension, including the name of the extension, so users can easily identify where their configuration is coming from.
Administrator workflow
Organizations that wish to deploy a common OAuth2 configuration to many users can package it as a Thunderbird WebExtension.
1. Create the extension manifest
Create a manifest.json containing the OAuth provider registration and any required OAuth2 settings (client ID, authorization endpoint, token endpoint, scopes, PKCE settings, browser flow settings, hostname registrations, email domain overrides, etc.).
Example manifest.json
{
"manifest_version": 2,
"name": "Example Microsoft 365 OAuth Provider",
"version": "1.0",
"applications": {
"gecko": {
"id": "oauth-provider@example.org",
"strict_min_version": "155.0"
}
},
"oauth_provider": {
"issuer": "this.must.be.unique",
"clientId": "your-client-id-here-0000-000000000000",
"clientSecret": "",
"issuerIdentifier": "https://login.microsoftonline.com/your-tenant-id-0000-0000-000000000000/v2.0",
"authorizationEndpoint": "https://login.microsoftonline.com/your-tenant-id-0000-0000-000000000000/oauth2/v2.0/authorize",
"tokenEndpoint": "https://login.microsoftonline.com/your-tenant-id-0000-0000-000000000000/oauth2/v2.0/token",
"redirectionEndpoint": "https://localhost",
"usePKCE": true,
"useExternalBrowser": true,
"hostnames": [
"office365.com",
"outlook.com"
],
"emailDomains": [
"example.com"
],
"scopes": "https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send https://outlook.office.com/EWS.AccessAsUser.All offline_access"
}
}
2. Package the extension into a standard Thunderbird extension (.xpi) file.
- Zip the manifest.json file.
- Rename to change the file extension from ".zip" to ".xpi.
3. Deploy the extension
Deploy the extension to users using the organization's preferred software deployment mechanism. Possible deployment methods include:
- Enterprise Policy (policies.json)
- Windows Group Policy (ADMX templates)
- Microsoft Intune
- macOS Configuration Profiles
- Linux enterprise package deployment
- Manual installation, if appropriate
Thunderbird's Enterprise Policies already support automatically installing extensions from either local files or URLs, as well as force-installing extensions so users cannot remove them. The newer ExtensionSettings policy also allows administrators to automatically install or force-install a specific extension by ID using an install_url.
4. Install / enable the extension
Depending on the deployment method, the extension may:
- be installed automatically when Thunderbird starts,
- be force-installed by enterprise policy,
- or be installed manually by the user via the Add-ons Manager.
Once installed, no additional account configuration is normally required.
User experience
Once the extension is installed, Thunderbird automatically uses the registered OAuth2 provider whenever an account matches the configured hostname or email-domain rules.
Thunderbird displays an indicator when OAuth2 settings are being provided by an extension. The indicator includes the name of the extension being used, so users can easily identify which extension, if any, is supplying their configuration. This allows users and administrators to see which extension is customizing their OAuth configuration.
Per-account OAuth2 manual customization (recommended for advanced users)
Who is this for?
- Advanced users
- Testing
- Individual account configuration
If only a single account needs custom OAuth2 settings, Thunderbird also supports configuring OAuth2 directly for an individual account.
Unlike the add-on approach, these settings affect only that account and are not intended for organization-wide deployment.
This is currently available for Microsoft Exchange accounts, with support for IMAP currently under development.
Per-account OAuth2 Microsoft Exchange customization
Exchange Setup Instructions
- Add a new email account: Thunderbird app menu > > and enter a Microsoft 365 email address e.g.
nemo@o365.thunderbird.netand then click MANUAL CONFIGURATION on the bottom left of the Account hub. - Click and then click .
- In the Exchange settings dialog, type one of the following URLs into the Enter the service URL field:
- For EWS: https://outlook.office365.com/EWS/Exchange.asmx
- For Graph: https://graph.microsoft.com/
- Click . For EWS, Exchange Web Services will automatically be selected. For Graph, Microsoft Graph will be selected.
- Your Microsoft 365 email address e.g.
nemo@o365.thunderbird.netyou used previously should be be automatically entered into the Username field (if not, then correct it). - For Authentication Method, select .
- Click Advanced configuration above the button.
- In Server settings, click the button above and to the right of Message Storage.
- Check the Override Office365 Settings check box.
- Enter the application ID your organization has set up in the Application ID field. Sometimes, it will be called a Client ID.
- Enter your organization's Microsoft 365 Tenant ID in the Tenant ID field.
- Optionally enter the Redirect URI. Default value is: http://localhost.
- Optionally enter the Endpoint Host. Default value is: https://login.microsoftonline.com
- Optionally enter the OAuth scopes. Default values are:
- For EWS, enter: https://outlook.office.com/EWS.AccessAsUser.All offline_access
- For Graph, enter: https://graph.microsoft.com/User.Read https://graph.microsoft.com/MailboxFolder.ReadWrite https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/Mail.Send https://graph.microsoft.com/offline_access
- Click the button to close the Advanced Account Settings dialog.
- Accept the Reauthorize Access dialog and trigger an email update. Messages should download and the account should operate as normal.
US Government Compute Cloud (GCC)
GCC does not include the common Thunderbird application ID, so all GCC users must have an organization that registers a Thunderbird application ID for their tenant IDs. When following the instructions above, use the Application ID and Tenant ID provided to you by your administrator and the following values for the other fields:
- Exchange URL:
- For EWS: https://outlook.office365.us/EWS/Exchange.asmx
- For Graph: https://graph.microsoft.us/
- Redirect URI: http://localhost
- Endpoint Host: https://login.microsoftonline.us
Per-account OAuth2 IMAP customization
In Thunderbird 155, support for per-account OAuth2 manual configuration for IMAP accounts was added. This section will be updated with an example.
Future standards, like PACC and DCR, will eliminate most OAuth custom configuration
Thunderbird is considering implementing emerging standards intended to reduce the amount of manual OAuth2 configuration required including:
Over time, these standards should allow Thunderbird to discover or negotiate OAuth2 configurations automatically with compatible servers, reducing (or potentially eliminating) the need to distribute client IDs or manually configure OAuth settings.
