Custom OAuth for Thunderbird

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:

1. Registering OAuth2 providers for new mail services that Thunderbird doesn't already know about.
2. 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.).

 "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.

• Simply 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.

When an extension is supplying the OAuth2 configuration, Thunderbird indicates this in Thunderbird app menu ☰ > Account Settings, by displaying the name of the extension that is providing the OAuth2 settings. This allows users and administrators to see which extension is customizing their OAuth configuration.

Per-account OAuth2 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.

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:

• PACC (Provisioning and Configuration Capabilities)
• Dynamic Client Registration (DCR)

Over time, these standards should allow Thunderbird to discover or negotiate OAuth2 configuration automatically with compatible servers, reducing (or potentially eliminating) the need to distribute client IDs or manually configure OAuth settings.