Skip to main content
By default, Cloudstic uses built-in OAuth client credentials compiled into the binary. This works for most users, but you may want to use your own credentials when:
  • Your organization restricts third-party app access
  • You want full visibility over API usage and quotas in your own Cloud Console
  • You’re building a self-hosted or team deployment of Cloudstic
  • You want to use a Google service account for unattended automation

​
Google Drive

Cloudstic reads the GOOGLE_APPLICATION_CREDENTIALS environment variable to load credentials from a JSON file. The same variable works for both a custom OAuth client and a service account. The Google SDK detects which type it is automatically.

​
Option A: Custom OAuth client

Use this when you want to authenticate as yourself (interactive browser-based login) but under your own Google Cloud project.
1

Create a Google Cloud project

Go to Google Cloud Console and create a new project, or select an existing one.
2

Enable the Drive API

Navigate to APIs & Services > Library, search for Google Drive API, and click Enable.
3

Create OAuth credentials

  1. Go to APIs & Services > Credentials
  2. Click Create credentials > OAuth client ID
  3. Choose Desktop app as the application type
  4. Name it (e.g. “Cloudstic Backup”)
  5. Click Create, then Download JSON
4

Configure the OAuth consent screen

If prompted, go to OAuth consent screen and configure it:
  • Set User type to Internal (for Google Workspace) or External
  • Add the scope https://www.googleapis.com/auth/drive.readonly
  • Add your email as a test user if using External type
5

Set the credentials path

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
cloudstic backup -source gdrive-changes
Cloudstic opens your browser for consent. The resulting token is cached in your config directory as google_token.json (or at GOOGLE_TOKEN_FILE if set) and reused for future backups.

​
Option B: Service account

Use this for automated, unattended backups. No browser is required. A service account authenticates as itself, not as a user.
1

Create a service account

In Google Cloud Console:
  1. Go to IAM & Admin > Service Accounts
  2. Click Create service account
  3. Give it a name and description, then click Create and continue
  4. Skip role assignment (access is granted via Drive sharing)
  5. Click Done
2

Download the key file

  1. Click the service account you just created
  2. Go to the Keys tab
  3. Click Add key > Create new key
  4. Choose JSON, then click Create
Save the downloaded file somewhere secure (e.g. /etc/cloudstic/service-account.json).
3

Grant Drive access

Share the Drive folder or Shared Drive with the service account’s email address:
my-backup@my-project.iam.gserviceaccount.com
Grant Viewer access. The service account can now read those files.
4

Set the credentials path

export GOOGLE_APPLICATION_CREDENTIALS=/etc/cloudstic/service-account.json
cloudstic backup -source gdrive-changes
No browser prompt. Cloudstic authenticates immediately using the service account.
For Shared Drives, the service account must be explicitly added as a member of the Shared Drive (not just a folder inside it). Domain-wide delegation is required if you need to access drives owned by other users in your Google Workspace organization.

​
Securing the credentials file

Store credential files with restricted permissions and never commit them to version control: 
chmod 600 /etc/cloudstic/service-account.json
In automated setups, set GOOGLE_APPLICATION_CREDENTIALS in a secured environment file (see Automating Backups):
~/.cloudstic_env
export GOOGLE_APPLICATION_CREDENTIALS=/etc/cloudstic/service-account.json
export GOOGLE_TOKEN_FILE=/etc/cloudstic/google_token.json

​
OneDrive

For OneDrive, Cloudstic uses the PKCE public client flow. No client secret is needed. Set ONEDRIVE_CLIENT_ID to your Azure app’s client ID to override the built-in app.
1

Register an app in Azure AD

  1. Go to Azure Portal > Azure Active Directory > App registrations
  2. Click New registration
  3. Name it (e.g. “Cloudstic Backup”)
  4. Set Redirect URI to http://localhost with type Public client/native
  5. Click Register
2

Configure API permissions

Under API permissions, add the following delegated permissions for Microsoft Graph:
  • Files.Read
  • Files.Read.All
  • User.Read
  • offline_access
If your organization requires it, click Grant admin consent.
3

Copy the client ID

On the app’s Overview page, copy the Application (client) ID.
4

Set the environment variable

export ONEDRIVE_CLIENT_ID="your-application-client-id"
cloudstic backup -source onedrive-changes
Cloudstic opens your browser using your app’s client ID. The token is cached in your config directory as onedrive_token.json (or at ONEDRIVE_TOKEN_FILE if set).
No client secret is required. Cloudstic uses the OAuth 2.0 PKCE flow, which is designed for native and desktop apps and does not require a secret.

​
Business and education accounts

If you’re backing up a Microsoft 365 or Office 365 account, your organization may block third-party apps by default. Using your own Azure AD app registered within your tenant bypasses this restriction. Contact your IT administrator to:
  • Register the app in your organization’s Azure AD tenant
  • Grant admin consent for the required permissions
  • Enable access for the users who will run Cloudstic

​
Environment variable reference

VariableProviderDescription
GOOGLE_APPLICATION_CREDENTIALSGoogle DrivePath to credentials JSON (OAuth client or service account)
GOOGLE_TOKEN_FILEGoogle DrivePath to cached OAuth token (default: <config-dir>/google_token.json)
ONEDRIVE_CLIENT_IDOneDriveAzure AD app client ID (no secret required)
ONEDRIVE_TOKEN_FILEOneDrivePath to cached OAuth token (default: <config-dir>/onedrive_token.json)

​
Next steps

Automating Backups

Schedule unattended backups using cron or systemd

Google Drive Source

Full Google Drive configuration reference

OneDrive Source

Full OneDrive configuration reference

Encryption Keys

Secure your encryption credentials for automation