> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Custom OAuth Credentials

> Register your own Google or Microsoft app to use instead of Cloudstic's built-in OAuth client

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.

<Steps>
  <Step title="Create a Google Cloud project">
    Go to [Google Cloud Console](https://console.cloud.google.com) and create a new project, or select an existing one.
  </Step>

  <Step title="Enable the Drive API">
    Navigate to **APIs & Services > Library**, search for **Google Drive API**, and click **Enable**.
  </Step>

  <Step title="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**
  </Step>

  <Step title="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
  </Step>

  <Step title="Set the credentials path">
    ```bash theme={null}
    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](/installation#configuration-directory) as `google_token.json` (or at `GOOGLE_TOKEN_FILE` if set) and reused for future backups.
  </Step>
</Steps>

### Option B: Service account

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

<Steps>
  <Step title="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**
  </Step>

  <Step title="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`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set the credentials path">
    ```bash theme={null}
    export GOOGLE_APPLICATION_CREDENTIALS=/etc/cloudstic/service-account.json
    cloudstic backup -source gdrive-changes
    ```

    No browser prompt. Cloudstic authenticates immediately using the service account.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

### Securing the credentials file

Store credential files with restricted permissions and never commit them to version control:

```bash theme={null}
chmod 600 /etc/cloudstic/service-account.json
```

In automated setups, set `GOOGLE_APPLICATION_CREDENTIALS` in a secured environment file (see [Automating Backups](/guides/automation)):

```bash ~/.cloudstic_env theme={null}
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.

<Steps>
  <Step title="Register an app in Azure AD">
    1. Go to [Azure Portal](https://portal.azure.com) > **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**
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Copy the client ID">
    On the app's **Overview** page, copy the **Application (client) ID**.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    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](/installation#configuration-directory) as `onedrive_token.json` (or at `ONEDRIVE_TOKEN_FILE` if set).
  </Step>
</Steps>

<Note>
  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.
</Note>

### 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

| Variable                         | Provider     | Description                                                              |
| -------------------------------- | ------------ | ------------------------------------------------------------------------ |
| `GOOGLE_APPLICATION_CREDENTIALS` | Google Drive | Path to credentials JSON (OAuth client or service account)               |
| `GOOGLE_TOKEN_FILE`              | Google Drive | Path to cached OAuth token (default: `<config-dir>/google_token.json`)   |
| `ONEDRIVE_CLIENT_ID`             | OneDrive     | Azure AD app client ID (no secret required)                              |
| `ONEDRIVE_TOKEN_FILE`            | OneDrive     | Path to cached OAuth token (default: `<config-dir>/onedrive_token.json`) |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Automating Backups" icon="clock" href="/guides/automation">
    Schedule unattended backups using cron or systemd
  </Card>

  <Card title="Google Drive Source" icon="google" href="/sources/google-drive">
    Full Google Drive configuration reference
  </Card>

  <Card title="OneDrive Source" icon="microsoft" href="/sources/onedrive">
    Full OneDrive configuration reference
  </Card>

  <Card title="Encryption Keys" icon="key" href="/guides/encryption-keys">
    Secure your encryption credentials for automation
  </Card>
</CardGroup>