24 February 2020

Executive summary

If you are using Akeeba Ticket System Professional on your site with GMail or G Suite email you need to make use of the Akeeba Ticket System mediator script for GMail if you are using the Reply by Email or New Ticket by Email feature with an email account hosted on GMail or G Suite.

The mediator is a small application hosted on Akeeba Ltd's server which mediates between your site where Akeeba Ticket System is installed and Google's API servers to procure and refresh the access tokens which are used by Akeeba Ticket System installed on your site to retrieve emails.

Akeeba Ltd does not store the GMail access tokens on its servers, or anywhere else, does not have access to your emails and can not send emails on your behalf.

The detailed explanation

What is Akeeba Ticket System

Akeeba Ticket System Professional (ATS) is a Joomla component which is installed on your site. It provides the functionality of a self-hosted support ticket system.

Normally, your clients will log into your site and visit the ATS pages you have created there to create or reply to support tickets. An email is sent to the user when they create a new ticket or a reply is posted to their existing ticket.

You can find more about Akeeba Ticket System itself in its product page.

When and why Akeeba Ticket System needs access to your emails

If you choose to do so, you can use either or both of optional features provided by the "Akeeba Ticket System - Fetch Email" plugin shipped with ATS: Reply by email and Create ticket by email.

The first option allows your clients to reply to the new ticket / new reply email notification by email. The contents of that email are posted as a reply to their support ticket.

The second option allows your clients to send an email to a designated address to create a new support ticket.

For these two features to work, ATS needs to log into your email server, check for the existence of new email messages, retrieve them, process them and finally mark them as read or delete them (depending on your preferences). This is done using either of the two industry-standard email retrieval protocols, IMAP or POP3. Logging into these mail servers typically takes place by sending a username (in most cases the email address) and a password.

How email access applies to GMail and G Suite

GMail and G Suite email (collectively called "GMail" below) have long supported access to the mail server through the industry-standard IMAP protocol. This allowed site administrators using ATS on their sites to enter their GMail email address and password in ATS to access their emails over the IMAP protocol.

Several years ago, GMail introduced Two Factor Authentication in GMail. This makes access to your email much more secure. However, it means that using your regular GMail password no longer worked for retrieving email from your GMail account. To cater for these uses cases Google introduced application-specific passwords which were randomly generated upon the GMail user's request and could be revoked at any time. You could use an application-specific password with ATS to retrieve your email.

At the end of 2019 Google announced that it would be retiring application-specific passwords. Starting June 15th, 2020 it will be impossible to connect to create new application-specific passwords. Starting February 15th, 2021 existing application-specific passwords will stop working.

Google has offered an alternative for application-specific passwords for a few years now. It's called OAuth2 token access and it's more secure than application-specific passwords.

The way it works is that the application that needs email access sends the user to Google's authentication servers. The user logs in there and verifies that they want the application to have access to their email account. Upon acceptance, Google's servers send two long bits of text called access token and refresh token back to the application. The application uses the access token to log into IMAP and retrieve email. The access token periodically expires. In this case the application uses the refresh token to get a new access token from Google's servers. This means that the equivalent of a password, the access token, never has access for too long and even if it's somehow stolen it can cause very limited damage.

GMail's OAuth2 token access flow is what you have experienced if you have linked your GMail or G Suite account with an email application such as Mozilla Thunderbird, Apple Mail, Windows Mail, Microsoft Outlook for Android / iOS etc. The popup Google page you had to log into was Google's authentication server. At the end of the process your email application received an access token and a refresh token to access your GMail / G Suite email account.

The need for a mediator script

The security of OAuth2 token access is very tightly controlled. Access and refresh tokens are only issued against an API application that has been registered with Google. Such an application can either be a desktop (e.g. Mozilla Thunderbird) or mobile (e.g. Microsoft Outlook for Android / iOS) application or a hosted web application.

Since we are talking about a Joomla component we are inherently talking about a hosted web application. However, for reasonable security reasons, a hosted web application registered with Google is restricted to a very specific domain name that its developer has to demonstrate they have control over. That is to say, we cannot create an application for ATS on behalf of all of our clients since each and every client has one or more sites, hosted on different domain names which are not under our control.

Considering that an API application is mandatory for OAuth2 token access to GMail and G Suite email accounts there are exactly two alternatives to this problem.

The first alternative is asking you, our clients who install ATS on your sites, to create an API application on Google's Cloud Console for each and every one of your sites, get it approved by Google and use it to connect ATS to your email account. While this would be the easiest way for us it would be extremely complicated for you. Worse yet, we couldn't offer to do that on your behalf or even help you navigate the process. That would be a very frustrating experience for you.

The second option is having us create an API application on Google's Cloud Console that applies to all of our clients' sites, get it approved by Google and use it to retrieve the access and refresh tokens. The tokens are passed directly to your site without them being stored on our server or anywhere else. Moreover, the same application can be used by your ATS on your site to exchange the refresh token with a new access token. Again, the new access token is sent back directly to your site without it being stored on our server or anywhere else. This miniature application is the Akeeba Ticket System mediator for GMail.

We chose to implement the second option because it's easier for you, our clients, to use. The only downside is that you get a request to authorize Akeeba Ticket System to read and send emails. This is a normal side-effect of how OAuth2 token access works. As noted, we do not store your access credentials (tokens), therefore we DO NOT have access to your email. If you are a subscriber of Akeeba Ticket System Professional you can request a copy of the source code of the mediator script to verify our assertion yourself.

Privacy, security and GDPR / CCPA compliance

Disclaimer: We are not lawyers. The information in this section is not legal advice and should not be treated as such. The information in this section is for informational purposes only. If you are unsure about compliance with privacy or other applicable laws in your jurisdiction please contact your lawyer to get a valid, professional, legal opinion.

As explained above, Akeeba Ltd does not store your access credentials (tokens) and does not have access to your email account. This makes the mediator script security-neutral.

Moreover, we do not keep or log any personally identifiable information when you use the mediator script. The only information logged is the fact that your site's IP address accessed the mediator script at a certain time. As a result the mediator script does not violate your privacy and does not require you to add any specific verbiage to your site's Privacy Policy to be compliant with the EU GDPR, California's CCPA or other similar privacy legislation.

Only your site can retrieve and process email. The only disclosure you may need in your Privacy Policy page is that your site will process the email sent to the designated support email address(es) for the purpose of creating new support tickets and / or creating new support ticket replies.