View source for Dropbox integration admin guide

= Zimbra Dropbox integration Admin Guide =

This guide will take you through the steps to set-up the Dropbox integration in Zimbra. Once you have completed the steps in this guide you can follow the end-user guide at https://wiki.zimbra.com/wiki/Dropbox_integration_end_user_guide for the final OAuth set-up.

<span id="_create_a_dropbox_application_oauth"></span>
= Create a Dropbox Application (OAuth) =

To be able to use the Dropbox integration you have to create a Dropbox account, the basic free plan will work with this integration.

Go to https://www.dropbox.com/developers/apps/ and click create app:

https://blog.zimbra.com/wp-content/uploads/2023/05/001-create-app.png

Configure the app using <code>Scoped access</code>, select <code>Full Dropbox</code> access and give your app a unique name and click Create App:

https://blog.zimbra.com/wp-content/uploads/2023/05/002-app-settings.png

Once your app is created go to the <code>Settings</code> tab and configure your Redirect URL:

* https://PUT-YOUR-ZIMBRA-SERVER-DOMAIN-HERE/service/extension/oauth2/authenticate/dropbox

Put your Zimbra domains under Chooser/saver domains section.

https://blog.zimbra.com/wp-content/uploads/2023/05/003-app-config2.png

In the app <code>Permissions</code> tab select the following scopes:

* account_info.write
* account_info.read
* files.metadata.write
* files.metadata.read
* files.content.write
* files.content.read
* sharing.write
* sharing.read
* file_requests.write
* file_requests.read
* contacts.write
* contacts.read

And click submit:

https://blog.zimbra.com/wp-content/uploads/2023/05/004-set-scope.png

In the Branding tab you can set optional App description and icon.

Go back to the settings tab and: '''Click Enable additional users so that others may authorize with the app.''' Then copy the App key and App secret for configuring Zimbra.

https://blog.zimbra.com/wp-content/uploads/2023/05/005-get-key.png

<span id="_setting_up_zimbra"></span>
= Setting up Zimbra =

From the command line run the following command to install the Dropbox Zimlet:

<pre>apt install -y zimbra-zimlet-dropbox</pre>
From the command line as the user <code>zimbra</code> run the following commands:

<pre>zmprov mcf +zimbraOAuthConsumerRedirectUri 'https://PUT-YOUR-ZIMBRA-SERVER-DOMAIN-HERE/service/extension/oauth2/authenticate/dropbox:dropbox'
zmprov mcf +zimbraOAuthConsumerCredentials 'PUT-APP-KEY-HERE:PUT-APP-SECRET-HERE:dropbox'</pre>
Finally restart mailbox to load the Zimlet by running as user <code>zimbra</code>:

<pre>zmmailboxdctl restart</pre>
<span id="_samesite_cookie_restriction_and_dropbox_oauth"></span>
== SameSite Cookie restriction and Dropbox OAuth ==

In case you have configured Zimbra to use a Strict same site cookie restriction, this has to be reverted by running the following command as user <code>zimbra</code>:

<pre>/opt/zimbra/bin/zmlocalconfig -e zimbra_same_site_cookie=&quot;&quot;</pre>
Typically if the same site cookie restriction is set to Strict the user will see a login screen after allowing Zimbra to access the Dropbox app. But even after signing on again the Dropbox integration will not be activated. In the mailbox log (/opt/zimbra/log/mailbox.log) you will see the following:

<pre>2023-05-10 05:21:36,776 ERROR [qtp2138564891-84:https://mail.zimbra.tech/service/extension/oauth2/authenticate/dropbox?code=ihvIiCKLSO4AAAAAAAAAGBTxfo_wGZg3VngTnK6f24g&amp;state=%2Fmodern%2FdropboxAuthCompleted%3Bnoop] [] extensions - An oauth application error occurred. : permission denied: 401: must authenticate</pre>
For debugging purpose you can copy/paste the URL from the log, to the browser of the authenticated user to activate the app. If this works, it means you have not unset the same site cookie restriction correctly or you have a cache issue. Restart Zimbra and flush the browser cache and try again.

<span id="_an_oauth_application_error_has_occurred"></span>
== An OAuth application error has occurred ==

This error will be shown in case the OAuth scope on the Dropbox app is not set or does not have all the required access rights, add at least the 12 mentioned in the steps above.

<span id="_connect_zimbra_with_dropbox_and_use_the_integration"></span>
= Connect Zimbra with Dropbox and use the integration =

These steps have to be done by each end-user (only once) and are described in: https://wiki.zimbra.com/wiki/Dropbox_integration_end_user_guide