Cloud Storage Integrations

Audience: Org Admin, System Admin, Deployment Administrator, Support
Related: Backups and Restore · Configuration · Environment and Secrets · Reverse Proxy and TLS

Dropbox and Google Drive provide optional organization backup destinations. Blackcap separates platform application credentials from organization account connections: a System Admin configures the OAuth application and callback URLs, then an authorized administrator connects the appropriate Dropbox or Google account for the organization’s backup workflow.

Use Backups and Restore for backup contents, restore safety, provider-specific retention, and the SQLite/PostgreSQL boundary. This guide covers provider application setup and connection troubleshooting.

Shared requirements

Before connecting either provider:

1. Blackcap must have a stable externally reachable HTTPS URL.
2. external_base_url and trusted proxy/TLS behavior must produce the same public scheme and hostname users open.
3. The exact provider callback URL must be registered with the provider.
4. Client IDs/keys and secrets must be stored through protected Platform configuration or the root-protected environment/bootstrap path; do not commit them.
5. The Active Organization must be the organization that should own the connected backup destination.
6. Test a manual backup and restore-list operation before enabling an automatic schedule.

Canonical callback paths are:

https://<public-blackcap-host>/cloud-backup/dropbox/callback
https://<public-blackcap-host>/cloud-backup/google/callback

The legacy /oauth/dropbox/callback and /oauth/google/callback routes remain accepted for compatibility, but new provider applications should use the canonical /cloud-backup/... paths.

Dropbox setup

Blackcap uses scoped Dropbox OAuth access.

Create the Dropbox application

In the Dropbox developer console, create an application with:

• Scoped access;
• App Folder access unless a reviewed deployment specifically needs broader access;
• files.content.read;
• files.content.write.

App Folder access keeps Blackcap backup files in the application’s provider-controlled folder instead of giving the application general access to the account.

Register the redirect URI

Register the exact public callback:

https://<public-blackcap-host>/cloud-backup/dropbox/callback

Scheme, hostname, port, path, and trailing-slash behavior must match the URI Blackcap sends. Do not register an internal Gunicorn address such as http://127.0.0.1:8080.

Configure Dropbox in Blackcap

Open:

Administration → Configuration → Platform → Providers

Configure:

• Dropbox App Key;
• Dropbox App Secret;
• Dropbox Redirect URI.

Then open the Backups/Connections workflow in the intended organization context and select Connect Dropbox. The OAuth callback stores the organization/provider connection; it must not expose the application secret to an Org Admin who lacks the platform credential permission.

Verify Dropbox

• The connection shows Connected for the intended organization.
• A manual backup can upload successfully.
• The backup appears in the Blackcap App Folder.
• Job Status shows the backup/upload phases without an active failure.
• Performance can show provider and phase timing after an instrumented run.
• Restore listing can see eligible Blackcap backups without exposing unrelated Dropbox files.

Google Drive setup

Blackcap uses Google OAuth with the drive.file scope:

https://www.googleapis.com/auth/drive.file

This scope is intentionally narrower than full Drive access. It allows Blackcap to manage files it created or that the user explicitly opened with the application; it is not a general Google Drive browser.

Create and configure the Google project

1. Create or select a Google Cloud project.
2. Enable the Google Drive API.
3. Configure the OAuth consent screen for the deployment. During testing, add the intended Google account as a test user when the app is not published.
4. Create an OAuth Client ID of type Web application.
5. Register the exact callback:

https://<public-blackcap-host>/cloud-backup/google/callback

Configure Google Drive in Blackcap

Open:

Administration → Configuration → Platform → Providers

Configure:

• Google Drive Client ID;
• Google Drive Client Secret;
• Google Drive Redirect URI.

Then connect Google Drive from the organization’s backup/connection workflow. The connected account and provider token are organization-scoped even though the OAuth application credentials are platform-scoped.

Verify Google Drive

• The intended organization shows a connected Google Drive account.
• A manual backup creates or updates a Blackcap-managed file using drive.file.
• Provider listing, download staging, and restore selection see only eligible Blackcap backup artifacts.
• Job Status and Performance show Google Drive provider/phase results where instrumentation exists.

HTTPS and proxy behavior

OAuth providers require a public callback and normally require HTTPS. Blackcap’s supported front ends are:

• Raspberry Pi: stunnel is the recommended TLS front end for the current Pi deployment;
• GCP: Nginx and managed certificate renewal in front of loopback Gunicorn.

The reverse proxy must preserve the public scheme/host through the approved forwarded-header path. Incorrect external_base_url, trusted-proxy settings, certificate hostname, or port commonly produces a provider redirect_uri_mismatch even when Blackcap itself is reachable.

Scope, secrets, and backups

• Platform provider credentials configure the shared OAuth application.
• Organization connection/token records identify the account used by that organization.
• Diagnostic clones do not copy usable provider tokens or secrets.
• Provider OAuth tokens are removed by an explicit disconnect, not by normal backup-history retention.
• Backup-run purge removes old metadata, not Dropbox or Google Drive ZIP files.
• Remote-provider backup retention is controlled by the organization’s backup settings and provider cleanup behavior.
• On GCP/PostgreSQL, platform ZIP backup does not replace Cloud SQL backup/recovery policy.

Disconnecting or changing accounts

Disconnect through the owning Connections/Backups workflow. Reconnecting should create or update the organization’s provider connection without changing another organization. Changing the platform OAuth application may require reconnecting existing organizations when provider refresh tokens are tied to the old client.

Before deleting a provider application or revoking its credentials, confirm which organizations still rely on it and create a local or alternate-provider backup.

Troubleshooting

Redirect URI mismatch

Compare the provider-registered URI with the value Blackcap generates. Check HTTPS, hostname, explicit port, callback path, and proxy-forwarded scheme. Use the canonical /cloud-backup/.../callback route.

The callback returns to the wrong organization

Start the connection while operating in the intended Active Organization. Do not reuse a stale callback/session from another organization. Review the provider connection record and audit event rather than editing rows directly.

The provider connects but upload fails

Check Job Status → Backup / Restore, provider error text, available provider storage, application permissions/scopes, local staging-file permissions, and outbound network/DNS. Do not paste access or refresh tokens into support text.

Backups are not visible for restore

Confirm provider, organization, destination/folder, backup scope, and current connection. The drive.file scope intentionally does not list arbitrary Drive files that Blackcap did not create or receive access to.

Tokens repeatedly expire

Confirm the provider application remains enabled, the consent/test-user configuration is valid, the client ID/secret did not change, server time is correct, and the callback URL still matches. Disconnect and reconnect through the UI rather than copying token rows.

Developer requirements

• Keep Dropbox and Google provider calls in their provider adapters and backup services.
• Preserve platform credential versus organization connection scope.
• Never log client secrets, authorization codes, access tokens, refresh tokens, or full provider payloads.
• Use state/session validation and the normal CSRF/OAuth protections.
• Record safe Job Status, Performance, and audit metadata without storing provider credentials.
• Test callback generation behind the supported Pi and GCP proxy paths.
• Update this guide, Backups, Configuration, and the API/connection documentation when provider behavior changes.