MozillaWiki

Thunderbird:Autoconfiguration:ConfigFileFormat: Difference between revisions

Page Discussion

Thunderbird:Autoconfiguration:ConfigFileFormat (view source)

Revision as of 18:18, 18 April 2023

7,222 bytes added ,  18 April 2023
spelling
(spelling)
 
(31 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Author: [[User:BenB|Ben Bucksch]]. Please do not change this doc without checking with the author.
Author: [[User:BenB|Ben Bucksch]]. Please do not change this doc without checking with the author.


This page is the authorative specification of the config file that the Mozilla ISPDB and config services at ISPs return.
This page is the authoritative specification of the config file that the Mozilla ISPDB and config services at ISPs return.


It is XML, with a clearly defined format, to be stable and usable by other mail clients, too. Update Aug 2010: In fact, [http://projects.gnome.org/evolution/ Evolution] and [http://userbase.kde.org/KMail KMail] and [http://www.kontact.org Kontact] now use it, too.
It is XML, with a clearly defined format, to be stable and usable by other mail clients, too. Update Aug 2010: In fact, [http://projects.gnome.org/evolution/ Evolution] and [http://userbase.kde.org/KMail KMail] and [http://www.kontact.org Kontact] now use it, too.
Line 7: Line 7:
= Description =
= Description =


[https://developer.mozilla.org/en/Thunderbird/Autoconfiguration#Configuration_file Some description]
* [https://developer.mozilla.org/en/Thunderbird/Autoconfiguration Description of the different mechanisms to serve the configuration file]
* [https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration/FileFormat/HowTo How to create your own config file]


= XML =
= XML =
Line 21: Line 22:
       <displayShortName>GMail</displayShortName>
       <displayShortName>GMail</displayShortName>


      <!-- type=
          "imap": IMAP
          "pop3": POP3
          -->
       <incomingServer type="pop3">
       <incomingServer type="pop3">
         <hostname>pop.example.com</hostname>
         <hostname>pop.example.com</hostname>
         <port>995</port>
         <port>995</port>
        <socketType>SSL</socketType>
           <!-- "plain": no encryption
           <!-- "plain": no encryption
                 "SSL": SSL 3 or TLS 1 on SSL-specific port
                 "SSL": SSL 3 or TLS 1 on SSL-specific port
                 "STARTTLS": on normal plain port and mandatory upgrade to TLS via STARTTLS
                 "STARTTLS": on normal plain port and mandatory upgrade to TLS via STARTTLS
                 -->
                 -->
        <socketType>SSL</socketType>
         <username>%EMAILLOCALPART%</username>
         <username>%EMAILLOCALPART%</username>
             <!-- "password-cleartext",
             <!-- Authentication methods:
                "plain" (deprecated):
                "password-cleartext",
                           Send password in the clear
                           Send password in the clear
                           (dangerous, if SSL isn't used either).
                           (dangerous, if SSL isn't used either).
                           AUTH PLAIN, LOGIN or protocol-native login.
                           AUTH PLAIN, LOGIN or protocol-native login.
                 "password-encrypted",
                 "password-encrypted",
                "secure" (deprecated):
                           A secure encrypted password mechanism.
                           A secure encrypted password mechanism.
                           Can be CRAM-MD5 or DIGEST-MD5. Not NTLM.
                           Can be CRAM-MD5 or DIGEST-MD5. Not NTLM.
Line 50: Line 54:
                 "TLS-client-cert":
                 "TLS-client-cert":
                           On the SSL/TLS layer, the server requests a client certificate and the client sends one (possibly after letting the user select/confirm one), if available. (Not yet supported by Thunderbird)
                           On the SSL/TLS layer, the server requests a client certificate and the client sends one (possibly after letting the user select/confirm one), if available. (Not yet supported by Thunderbird)
                "OAuth2":
                          OAuth2. Works only on specific hardcoded servers, please see below. Should be added only as second alternative.
                 "none":
                 "none":
                           No authentication
                           No authentication
                  Compatibility note: Thunderbird 3.0 accepts only "plain" and "secure". It will ignore the whole XML file, if other values are given. -->
                -->
         <authentication>password-cleartext</authentication>
         <authentication>password-cleartext</authentication>
         <pop3>
         <pop3>
Line 68: Line 74:
         <hostname>smtp.googlemail.com</hostname>
         <hostname>smtp.googlemail.com</hostname>
         <port>587</port>
         <port>587</port>
         <socketType>STARTTLS</socketType> <!-- see above -->
         <socketType>STARTTLS</socketType> <!-- see <incomingServer> -->
         <username>%EMAILLOCALPART%</username> <!-- if smtp-auth -->
         <username>%EMAILLOCALPART%</username> <!-- if smtp-auth -->
             <!-- smtp-auth (RFC 2554, 4954) or other auth mechanism.
             <!-- smtp-auth (RFC 2554, 4954) or other auth mechanism.
Line 102: Line 108:
         <password>optional: the user's password</password>
         <password>optional: the user's password</password>
       </outgoingServer>
       </outgoingServer>
      <identity>
        <!-- needed? -->
        <!-- We don't want Verizon setting "Organization: Verizon"
              for its customers -->
      </identity>
      <!-- see description. Not yet supported, see bug 564043. -->
      <inputField key="USERNAME" label="Screen name"></inputField>
      <inputField key="GRANDMA" label="Grandma">Elise Bauer</inputField>


       <!-- Add this only when users (who already have an account) have to
       <!-- Add this only when users (who already have an account) have to
           do something before the account can work with IMAP/POP or SSL.
           do something manually before the account can work with IMAP/POP or SSL.
           Note: Per XML, & (ampersand) needs to be escaped to & a m p ;
           Note: Per XML, & (ampersand) needs to be escaped to & a m p ;
           (without spaces).
           (without spaces).
           Not yet implemented, see bug 586364. -->
           Not yet implemented, see bug 586364. -->
       <enable
       <enable
          visiturl="https://mail.google.com/mail/?ui=2&shva=1#settings/fwdandpop">
        visiturl="https://mail.google.com/mail/?ui=2&amp;shva=1#settings/fwdandpop">
          <instruction>Check 'Enable IMAP and POP' in Google settings page</instruction>
        <instruction>Check 'Enable IMAP and POP' in Google settings page</instruction>
          <instruction lang="de">Schalten Sie 'IMAP und POP aktivieren' auf der Google Einstellungs-Seite an</instruction>
        <instruction lang="de">Schalten Sie 'IMAP und POP aktivieren' auf der Google Einstellungs-Seite an</instruction>
       </enable>
       </enable>


Line 134: Line 130:
           mostly for us.
           mostly for us.
       -->
       -->
       <instruction url="http://www.example.com/help/mail/thunderbird">
       <documentation url="http://www.example.com/help/mail/thunderbird">
         <descr lang="en">Configure Thunderbird 2.0 for IMAP</descr>
         <descr lang="en">Configure Thunderbird 2.0 for IMAP</descr>
         <descr lang="de">Thunderbird 2.0 mit IMAP konfigurieren</descr>
         <descr lang="de">Thunderbird 2.0 mit IMAP konfigurieren</descr>
       </instruction>
       </documentation>


     </emailProvider>
     </emailProvider>
    <!-- Syncronize the user's address book / contacts. Not implemented. Thunderbird uses RFC 6764 to do auto discovery. -->
    <!-- TODO: delete this section!! -->
    <addressBook type="carddav">
      <username>%EMAILADDRESS%</username>
        <!-- Authentication methods. See also <incomingServer>.
              "http-basic":
                        Authenticate to the HTTP server using
                        WWW-Authenticate: Basic
              "http-digest":
                        Authenticate to the HTTP server using
                        WWW-Authenticate: Digest
              "OAuth2":
                        OAuth2. Uses the same token as for email.
              -->
      <authentication>http-basic</authentication>
      <serverURL>https://contacts.example.com/remote.php/dav<serverURL>
    </addressBook>
    <!-- Syncronize the user's calendar. Not implemented. Thunderbird uses RFC 6764 to do auto discovery. -->
    <!-- TODO: delete this section!! -->
    <calendar type="caldav">
      <username>%EMAILADDRESS%</username>
      <authentication>http-basic</authentication> <!-- see <addressBook> -->
      <serverURL>https://calendar.example.com/remote.php/dav<serverURL>
    </calendar>
    <!-- Upload files, allowing the user to share them. Not implemented.
        This can be used for Thunderbird's FileLink feature,
        or to set up a file sync folder on the user's desktop. -->
    <!-- TODO: delete this section!! Obsoleted by RFC 6764. -->
    <fileShare type="webdav">
      <username>%EMAILADDRESS%</username>
      <authentication>http-basic</authentication> <!-- see <addressBook> -->
      <serverURL>https://share.example.com/remote.php/dav<serverURL>
    </fileShare>
    <!-- This allows to access the webmail service of the provider.
        The URLs are loaded into a standard webbrowser for the user.
        Specifying this is optional. -->
    <webMail>
      <!-- Webpage where the user has to log in manually by entering username
          and password himself.
          HTTPS required. -->
      <loginPage url="https://mail.example.com/login/" />
      <!-- Same as loginAutomaticDOM, but the website makes checks that
          the user comes from the login page. So, open the login page
          in the browser, get the page's DOM, fill out name and password
          fields for the user, and trigger the login button.
          The login button might not be an HTML button, just a div, so
          to trigger it, send a click event to it.
          HTTPS is required for the URL. -->
      <loginPageInfo url="https://mail.example.com/login/">
        <!-- What to fill into the usernameField.
            Format is the same as for <username> within <incomingServer>,
            including placeholders. See below for valid placeholders. -->
        <username>%EMAILADDRESS%</username>
        <!-- Allows to find the textfield on the page, to fill it out.
            The id attribute give the DOM ID,
            The name attribute give the DOM name attribute.
            One or both of id and name attributes must exist.
            Try the ID first (e.g. using getElementById()), if existing.
            Otherwise, try finding the element by name.
            Don't treat the IDs given in this XML file as trusted,
            but before using them, verify the format
            (e.g. only characters and digits for IDs).
            If you use powerful functions like jQuery, and the XML returns
            you code in the username ID, and you feed it unchecked to jQuery,
            it may be executed. -->
        <usernameField id="email_field" name="email" />
        <passwordField name="password" />
        <!-- The submit button to trigger the server submit
            after filling in the fields.
            id and name attributes: See <usernameField> -->
        <loginButton id="submit_button" name="login"/>
      </loginPageInfo>
    </webMail>
    <!-- see description. Not yet supported, see bug 564043. -->
    <inputField key="USERNAME" label="Screen name"></inputField>
    <inputField key="GRANDMA" label="Grandma">Elise Bauer</inputField>


     <clientConfigUpdate url="https://www.example.com/config/mozilla.xml" />
     <clientConfigUpdate url="https://www.example.com/config/mozilla.xml" />
Line 145: Line 223:
</clientConfig>
</clientConfig>
</pre>
</pre>
= Multiple servers =
incomingServer and outgoingServer may appear several times. They are in order of priority, the first entry should generally be used, unless there's a specific factor or policy which prefers a later config.
For example, there may be configs with STARTTLS and normal SSL. Use the first entry listed. If that fails (server config change), you can try the second config. If IMAP and POP3 servers both exist, then both should be listed; the client or end user can select the protocol which best suits its needs. The config/ISP can, however, express a preference for IMAP or POP3 by what is listed first in the config file.


= Placeholders =
= Placeholders =
Line 180: Line 264:


The system is generic, so that it can in theory be used for other values as well. No other such purpose is currently known, apart from a separate POP and SMTP username maybe. It should not be used to let the user supply hostnames, as that would defeat the purpose of the autoconfig and be worse than the manual config UI provided by the client.
The system is generic, so that it can in theory be used for other values as well. No other such purpose is currently known, apart from a separate POP and SMTP username maybe. It should not be used to let the user supply hostnames, as that would defeat the purpose of the autoconfig and be worse than the manual config UI provided by the client.
= OAuth2 =
Due to a defficiency in the OAuth2 spec, the client is usually required to send a client credential key, which in turn requires the client to be registered and approved by the email provider. Unfortunately, this not only allows email providers to block specific email clients (which is contrary to the idea of Open-Source), but also makes it impossible to support arbitrary OAuth2 servers. That's why Thunderbird is forced to hardcode the servers that it supports and the respecive client keys. That means that you cannot use OAuth2 for your own server. Only the servers listed on [https://searchfox.org/comm-central/source/mailnews/base/src/OAuth2Providers.jsm OAuth2Providers.jsm] will work.
A server using OAuth2 auth looks this:
<pre>
  ...
    <incomingServer type="imap">
      <hostname>imap.gmail.com</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <username>%EMAILADDRESS%</username>
      <authentication>OAuth2</authentication>
      <authentication>password-cleartext</authentication>
    </incomingServer>
  </emailProvider>
  <oAuth2>
    <issuer>login.yahoo.com</issuer>
    <scope>mail-w</scope>
    <authURL>https://api.login.yahoo.com/oauth2/request_auth</authURL>
    <tokenURL>https://api.login.yahoo.com/oauth2/get_token</tokenURL>
  </oAuth2>
</pre>
Note that the `<oAuth2>` contents are not yet supported by Thunderbird. They are planned to be supported later, removing the need to hardcode these parameters. As of today, `<authentication>OAuth2</authentication>` is supported.
Note that there are two `<authentication>` elements. This allows a fallback, in case a client does not support OAuth2 or does not have a client key for this OAuth2 issuer and therefore cannot authenticate with this issuer.
Scope: If we set up email, address book, calendar, and webdav, we do *not* want the user go have to go through 4 authentication processes. Yet, a provider might use different scopes for email and calendar, and that is in line with the OAuth2 spec. The solution is to combine several scopes, using [https://tools.ietf.org/html/rfc6749#section-3.3 spaces as separator], in a single auth request. [https://stackoverflow.com/questions/8449544/multiple-scope-values-to-oauth2/51437063#51437063 The order is important]. That's why we deliberately do not make the scope specific to a service or server, but to the entire configuration. We don't want the user to have to authenticate several times in a row. This is a requirement from the end user.


= TODO =
= TODO =
Retrieved from "https://wiki.allizom.org/Special:MobileDiff/360864...1246173"