Some remote storage providers use an authentication method called OAuth2. This is a three-party system which involves the service provider, the user, and a web application. The latter item, the web application, can be implemented in two different ways. Either as a centrally managed "helper" application which acts as an intermediary between the OAuth2 workflow and your Akeeba Backup installation, or as something you host on your own site. This documentation section discusses the nature of OAuth2 authentication, the pros and cons of each approach, and how to configure self-hosted OAuth2 helpers if you wish.
This section applies to the following remote file storage providers: Dropbox, OneDrive, Google Drive, Box.com.
When you ask Akeeba Backup to upload your backup archives to a remote storage provider, such as Amazon S3 or Dropbox, it is not enough to just tell it where to upload the files. You need to also provide some kind of authentication information which lets Akeeba Backup prove to the remote storage engine that it acts on your behalf, you being a user on that remote storage provider who is authorised to upload and manage files in that remote storage location.
All enterprise storage providers such as Amazon S3, Microsoft Azure BLOB Storage, BackBlaze B2 etc rely on one or more static pieces of text. "Static" in this context means that they do not change at all, or they only need to be changed very infrequently (in the order of several months or several years). You, the user, log into the remote storage provider's interface once, create these keys, and transcribe them to Akeeba Backup's configuration. That's the beginning, middle, and end of it.
Conversely, all consumer / prosumer storage providers, such as OneDrive, Google Drive, Dropbox, and Box.com use a different scheme called OAuth2. This works differently in both how authentication takes place, and how you interact with it.
Under this scheme, the static keys (called Client ID and Client Secret) are not used directly. The Client ID is part of a URL on the storage provider's servers where you, the user, are redirected to. You log into your account with the storage provider and consent to allowing an application have access to your storage account. Following your consent, the storage provider sends the application a one-time code. The application sends this code, the Client ID, and the Client Secret back to the storage provider which responds with two pieces of text: the access token and the refresh token.
The access token is functionally equivalent to the keys of enterprise storage, but it has a short expiration time which is typically somewhere between 10 minutes and 1 hour. The slightly longer-lived refresh token has an expiration time typically between 1 month and 1 year, but it can't be used directly. It has to be sent to the storage provider together with the Client ID and Client Secret to be exchanged with a new access token and refresh token pair[1].
The Client ID and Client Secret are static pieces of text. They are issued by the storage provider when a developer creates an API application. This is where problems start when dealing with OAuth2 authentication.
Part of creating an API application is providing an authorised domain and/or OAuth2 callback URL. This is where the storage provider will redirect your browser to after you provide consent. This has to be set up when creating the API application. This means that we cannot have it point to your site: we neither know what it is in advance, nor could we support more than one site, let alone more than one paying client, at a time.
Even if the fixed URL / domain was not a problem, the Client ID and Client Secret which are necessary to exchange the refresh token with a new access token, the bit of information we need to upload files, must be kept secret. Failure to do so would allow any third party, including any malicious third party, to impersonate our application which would lead to all sorts of security nightmares. This means that the Client ID and Secret cannot be shipped with an application that is installed on the end user's site, like Akeeba Backup. So, even if the previous constraint did not exist or could be worked around somehow, the problem of not being to support OAuth2 directly would remain.
Our solution to this problem was creating a small OAuth2 helper script for each support remote storage engine. It has a predictable callback URL on our own domain, and we get to keep the Client ID and Client Secret invisible to you. These short scripts merely act as mediators between your Akeeba Backup installation and the storage provider. We DO NOT store, log, or otherwise process your access and refresh keys; we just pass them back to you.
Having a helper script managed by us has a few downsides. First of all, you need to trust us that we do not store or otherwise process your access and refresh keys. This is easy; not only we are reputable company, we are subject to the EU GDPR which would obliterate our business if we did anything different.
Moreover, you rely on our server being online and accessible to your site when your backups are taking place. While we take all the necessary technical measures possible to ensure that this is the case, we still need to restart the server from time to time (e.g. OS kernel updates), or there may be network issues beyond our control which limit your access to it.
Furthermore, access to these OAuth2 helper scripts is a service we provide. We only offer it to paying customers with an active subscription. When your subscription expires, you can no longer use any remote storage method which uses OAuth2.
Finally, when it comes to being able to offer this service we are at the mercy of storage providers. For example, Google made it impossible for us to continue offering integration with shared drives and folders using our own OAuth2 application, but it's perfectly possible to do that if you use your own OAuth2 application instead.
The solution to any and all of these issues is, of course, you hosting your own OAuth2 Helper application instead of using the one we host ourselves. This is possible, but there are some caveats.
First of all, you need to create your own API application with your remote storage provider. It's not as scary as it sounds. You don't need to be a developer, you don't need to pay any money. It's just yet another thing you need to do.
Moreover, your site will need to be able to access itself over the web (loopback access). This is not always a given. Before you go down that route, ask your host if this is allowed on their servers.
Furthermore, you must ensure that third party plugins do not interfere with the output of the custom OAuth2 helpers handled by your Akeeba Backup installation. Since this is your site, that's your responsibility. If third party plugins prevent access to these URLs, add or remove from the output, or cause a PHP error you will be unable to operate a custom OAuth2 helper. In this case you can create a new site in a subdomain, without any content, with Akeeba Backup Professional installed on it, and set up the OAuth2 helpers on that site. Then, they can be used by any number of other sites.
Finally, you will be responsible for the set up and upkeep of your API applications. Most storage providers will require you to provide a publicly accessible Terms of Service and Privacy Policy page, and an email and phone number for the person who will be acting as your Data Protection Officer (DPO) even if you only intend to use this application yourself. They will also contact you annually, asking you to verify that the permissions you are asking are correct.
Based on that, we recommend using your own OAuth2 helpers only if you have a significant number of sites (more than ten), you are confident that you will be able to handle this process, and you have a reason for not wanting to use our own provided helper even if it's an unsubstantiated distrust against us; we promise that we won't take it personally. In every other case, using the OAuth2 Helper hosted by us is the recommended course of action.
The OAuth2 helper scripts we host on our site are mediators, simple pass-through scripts which do not store, log, or otherwise process your personally identifiable information. They are used in three cases:
When initiating authentication with the "Authentication - Start Here" button. Our server simply redirects you to a predefined URL on the storage provider's server; only your IP address, and timestamp are recorded in our server's access log file for security purposes.
When you come back from the remote storage provider's consent screen. The one-time use code, your IP address, and timestamp are recorded in our server's access log for security purposes. The one-time code is immediately "burned" as it is exchanged for an access and refresh token pair. The access and refresh token pair is NOT stored or logged anywhere; it is only displayed to you, so you can copy it into Akeeba Backup.
When Akeeba Backup needs to exchange the refresh token for an access token. The refresh token, your IP address, and timestamp are recorded in our server's access log for security and performance control purposes. Unfortunately, we cannot not log this information. We've had cases when someone was spamming our token refresh endpoint with hundreds of thousands of requests every day, degrading the service for everyone else. The only way to stop these attacks is by logging the aforementioned information.
If you are not comfortable with this minimal amount of logging, you will have to use your own OAuth2 Helpers.
[1] Most providers will not change the refresh token during this exchange. Instead, they will extend its lifetime. The principle, however, remains the same.