copilot-swe-agent[bot]
e518bce922
Resolve all merge conflicts between our automation feature branch and current main (v0.163.0, 920 commits ahead). Conflicts resolved: - app/api/__init__.py: add automation_router alongside main's new routers (classification_rules, qr_auth, sessions, system_reset) - app/config.py: add main's new settings (dropbox_use_global_credentials, factory_reset_on_startup, enable_factory_reset) - app/models.py: add main's new models (ClassificationRuleModel, UserSession, QRLoginChallenge, SharePoint integration type) - app/utils/settings_service.py: merge automation_hooks_enabled with main's new metadata entries - docs/API.md: merge automation API docs with main's classification rules docs - docs/ConfigurationGuide.md: add factory reset settings - tests/conftest.py: import both AutomationHook and new main models Migration renumbered: - 037_add_automation_hooks → 040_add_automation_hooks - down_revision: 039_add_classification_rules (was 036_add_document_translation_fields) - Chain: 036 → 037 → 038 → 039 → 040 (automation hooks) For all non-automation files with conflicts, main's version was taken since our branch did not modify those files (conflicts were from a stale prior merge). Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> Agent-Logs-Url: https://github.com/christianlouis/DocuElevate/sessions/cb62f012-3b69-4415-835e-3857ce3e9f45
160 lines
7.7 KiB
Markdown
160 lines
7.7 KiB
Markdown
# Setting up Dropbox Integration
|
||
|
||
This guide explains how to set up the Dropbox integration for DocuElevate.
|
||
|
||
## Required Configuration Parameters
|
||
|
||
| **Variable** | **Description** |
|
||
|-------------------------|--------------------------------------------------|
|
||
| `DROPBOX_APP_KEY` | Dropbox API app key |
|
||
| `DROPBOX_APP_SECRET` | Dropbox API app secret |
|
||
| `DROPBOX_REFRESH_TOKEN` | OAuth2 refresh token for Dropbox |
|
||
| `DROPBOX_FOLDER` | Default folder path for Dropbox uploads |
|
||
|
||
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
|
||
|
||
## Setup Methods
|
||
|
||
DocuElevate supports two distinct Dropbox OAuth flows:
|
||
|
||
1. **Per-User Integration Wizard (Recommended for end users)**: Triggered from the Integrations dashboard (`/integrations`) by clicking **Authorize** on a Dropbox destination or Dropbox-backed Watch Folder. Credentials are saved securely to your personal integration record — global settings are never exposed.
|
||
2. **System-Level Setup Wizard**: Available at `/dropbox-setup` for administrators configuring the global system-wide Dropbox connection. Generates environment variables for all worker nodes.
|
||
3. **Manual Setup**: Following the step-by-step instructions in this document.
|
||
|
||
## Per-User OAuth Flow (Integrations Dashboard)
|
||
|
||
End users authorize their own Dropbox integration from the **Integrations** dashboard:
|
||
|
||
1. Navigate to `/integrations` and click **+ Add Destination** (or **+ Add Source** for Watch Folder).
|
||
2. Create a Dropbox destination integration (or a Watch Folder with `source_type = dropbox`).
|
||
3. Click the **Authorize** button next to the integration — it links directly to the OAuth wizard pre-loaded with your integration's configuration.
|
||
4. If the administrator has configured system-wide Dropbox app credentials (`DROPBOX_APP_KEY` / `DROPBOX_APP_SECRET`), the wizard defaults to using them — no need to register your own Dropbox app. Uncheck the toggle to use custom credentials if needed.
|
||
5. Click **Start Authentication Flow**, authorize access in Dropbox, and the refresh token is automatically saved to your personal integration record.
|
||
6. After authorization, an interactive **folder browser** lets you select the target folder directly from your Dropbox — no need to manually type folder paths.
|
||
7. The page redirects to `/integrations` on success. Re-authorization is available at any time via the **Re-Authorize** button.
|
||
|
||
> **Note:** Your credentials are stored encrypted per-integration and are never mixed with other users' data. Each user can have multiple Dropbox integrations with independent tokens.
|
||
|
||
## Using the System-Level Setup Wizard (Admin)
|
||
|
||
The easiest way to configure the global Dropbox integration is to use the built-in setup wizard:
|
||
|
||
1. Navigate to the `/dropbox-setup` page in your DocuElevate instance.
|
||
2. Follow the on-screen instructions to create a Dropbox app.
|
||
3. Enter your App Key and App Secret in the wizard.
|
||
4. Optionally specify a custom folder path for uploads.
|
||
5. Click **Start Authentication Flow** to begin the authorization process.
|
||
6. Complete the Dropbox authentication process.
|
||
7. The system will automatically exchange the authorization code for a refresh token.
|
||
8. Copy the generated environment variables for your worker nodes.
|
||
|
||
The wizard handles all the token exchange steps and provides you with the exact configuration needed for your environment.
|
||
|
||
## Step-by-Step Manual Setup Instructions
|
||
|
||
### 1. Create a Dropbox App
|
||
|
||
1. Go to the [Dropbox Developer Apps Console](https://www.dropbox.com/developers/apps)
|
||
2. Click "Create app"
|
||
3. Select "Scoped access" for API
|
||
4. Choose "Full Dropbox" access (or "App folder" for more restricted access)
|
||
5. Give your app a name (e.g., "DocuElevate")
|
||
6. Click "Create app"
|
||
|
||
### 2. Configure App Permissions
|
||
|
||
1. In your app's settings page, go to the "Permissions" tab
|
||
2. Enable the following permissions:
|
||
- `files.content.write` (to upload files)
|
||
- `files.content.read` (if you need to read file content)
|
||
3. Click "Submit" to save changes
|
||
|
||
### 3. Get App Key and Secret
|
||
|
||
1. On your app's settings page, find the "App key" and "App secret"
|
||
2. Set these as `DROPBOX_APP_KEY` and `DROPBOX_APP_SECRET` in your configuration
|
||
|
||
### 4. Generate a Refresh Token
|
||
|
||
1. Go to the "OAuth 2" tab in your app settings
|
||
2. Add a redirect URI: `http://localhost` (this is for the authorization flow)
|
||
3. Generate an authorization URL with these instructions:
|
||
|
||
```
|
||
https://www.dropbox.com/oauth2/authorize?client_id=YOUR_APP_KEY&response_type=code&token_access_type=offline
|
||
```
|
||
|
||
4. Replace `YOUR_APP_KEY` with your app key
|
||
5. Open this URL in your browser
|
||
6. Authorize the app when prompted
|
||
7. You'll be redirected to `localhost` with a code parameter in the URL
|
||
8. Copy this code parameter
|
||
|
||
### 5. Exchange the Code for a Refresh Token
|
||
|
||
1. Use this curl command to exchange the code for tokens:
|
||
|
||
```bash
|
||
curl -X POST https://api.dropboxapi.com/oauth2/token \
|
||
-d code=YOUR_AUTH_CODE \
|
||
-d grant_type=authorization_code \
|
||
-d client_id=YOUR_APP_KEY \
|
||
-d client_secret=YOUR_APP_SECRET \
|
||
-d redirect_uri=http://localhost
|
||
```
|
||
|
||
2. From the response, copy the `refresh_token` value
|
||
|
||
### 6. Configure DocuElevate
|
||
|
||
1. Set `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`, and `DROPBOX_REFRESH_TOKEN` with your values
|
||
2. Set `DROPBOX_FOLDER` to the path where files should be uploaded (e.g., `/Documents/Uploads`)
|
||
|
||
## Token Management
|
||
|
||
The system will use the refresh token to automatically generate short-lived access tokens when needed. Refresh tokens typically don't expire unless revoked.
|
||
|
||
### Testing Your Token
|
||
|
||
You can test if your token is working correctly:
|
||
|
||
1. Navigate to the `/dropbox-setup` page in your DocuElevate instance
|
||
2. Click the "Test Token" button to verify your credentials
|
||
3. If the test fails, click "Refresh Token" to obtain a new refresh token
|
||
|
||
## Troubleshooting
|
||
|
||
If you encounter issues with Dropbox integration:
|
||
|
||
1. **Authentication Errors**: Make sure your App Key and App Secret are correct
|
||
2. **Token Expired**: Click "Refresh Token" button on the setup page to obtain a new token
|
||
3. **Folder Permissions**: Ensure your app has the correct permissions enabled for file operations
|
||
4. **Invalid Redirect URI**: See section below for the most common cause and fix.
|
||
5. **Rate Limiting**: Dropbox API has rate limits; if exceeded, wait and try again
|
||
|
||
### Fixing "Invalid redirect_uri" Error
|
||
|
||
This error appears on the Dropbox authorization page when the redirect URI in the OAuth request does not match any URI registered in your Dropbox app console.
|
||
|
||
**Most common cause**: The application is deployed behind a reverse proxy (Traefik, Nginx, Caddy) that does **not** forward the `X-Forwarded-Proto: https` header to DocuElevate. Without this header, the server cannot determine that it is being accessed over HTTPS and may construct an `http://` redirect URI, while the registered URI in Dropbox is `https://`.
|
||
|
||
**Fix**:
|
||
|
||
Option 1 – Configure your proxy to forward `X-Forwarded-Proto`:
|
||
|
||
```nginx
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
```
|
||
|
||
Option 2 – Set `PUBLIC_BASE_URL` in your environment (recommended for most deployments):
|
||
|
||
```bash
|
||
PUBLIC_BASE_URL=https://docuelevate.example.com
|
||
```
|
||
|
||
When `PUBLIC_BASE_URL` is set, DocuElevate uses it directly for all OAuth redirect URIs instead of trying to infer the scheme from request headers. This is the most reliable option.
|
||
|
||
After setting `PUBLIC_BASE_URL`, ensure the Dropbox app console redirect URI matches exactly (e.g., `https://docuelevate.example.com/dropbox-callback`). The setup wizard at `/dropbox-setup` will show you the exact URI to register.
|
||
|
||
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
|