copilot-swe-agent[bot]
c7d3ec57c3
Commitd2217531(google-labs-jules SSRF fix) catastrophically deleted 11,500+ lines across 100+ files while fixing an unrelated IMAP issue. Restored from d2217531^ (pre-bad-commit state): Deleted files (fully restored): - app/api/{automation,classification_rules,comments,sharing}.py - app/middleware/upload_rate_limit.py - app/tasks/{automation_tasks,classify_document}.py - app/utils/{automation_hooks,classification_rules}.py - docs/AppleAppStoreCompliance.md - frontend/input.css, package.json, package-lock.json, tailwind.config.js - frontend/static/js/{annotations,claim,comments,sharing}.js - frontend/templates/{admin_connections,file_annotations,file_summary}.html - tests/{test_api_files_comprehensive,test_auth_extended,test_sharing, test_comments,test_connections,test_imap_profiles,test_api_sessions, test_automation,test_classification_rules,test_api_advanced_filters, test_api_classification_rules,test_upload_rate_limit,test_api_dropbox, test_classify_document,test_comments_ui,test_upload_to_icloud, test_api_onedrive_comprehensive,test_frontend_build,test_sentry, test_diagnostic,test_database,test_views_dropbox,test_local_auth}.py Truncated files (content restored): - app/{auth,config,main,models,celery_worker,database}.py - app/api/{__init__,api_tokens,diagnostic,dropbox,files,google_drive, integrations,local_auth,mobile,onedrive,pipelines,qr_auth, settings,url_upload}.py - app/middleware/upload_rate_limit.py - app/tasks/upload_to_nextcloud.py - app/utils/{allowed_types,settings_service,settings_sync,user_scope,webhook}.py - app/views/{base,dropbox,files,google_drive,onedrive,settings}.py - docs/{API,AuthenticationSetup,ConfigurationGuide,DatabaseConfiguration, DeploymentGuide,DropboxSetup,GoogleDriveSetup,KubernetesDeployment, MobileApp,OneDriveSetup,ProductionReadiness,SentrySetup, SocialLoginSetup,UserGuide}.md - frontend/static/{js/upload.js,styles.css} - frontend/templates/{api_tokens,base,devices,dropbox,dropbox_callback, file_view,files,google_drive,onedrive,onedrive_callback, signup}.html - frontend/translations/en.json - migrations/env.py - tests/{conftest,test_api_integrations,test_api_mobile,test_api_settings, test_api_tokens,test_audit_logs,test_duplicates,test_imap_tasks, test_setup_wizard,test_views_files_comprehensive}.py Security fixes kept from post-d2217531 commits: - app/utils/network.py: DNS SSRF fail-secure fix (06b0fced) - app/utils/file_operations.py: path traversal fix (1018ea17) - tests/test_imap_tasks.py: re-applied 4 is_private_ip mock patches Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> Agent-Logs-Url: https://github.com/christianlouis/DocuElevate/sessions/51133dd8-9bec-41ab-aa10-3de753634187
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).
|