Creating OAuth Credentials for Cloud Storage

Set up your own OAuth app for secure cloud storage connections

What You'll Learn
  • What OAuth is and why it matters for your privacy
  • Understanding Client ID, Client Secret, and scopes
  • How to create OAuth credentials for Google Drive
  • How to create OAuth credentials for OneDrive
  • Which scopes to choose for different use cases
  • The Google publishing-status step that keeps your connection from expiring after a week

Understanding OAuth

OAuth (Open Authorization) is a standard protocol that allows applications to access your data without exposing your password. When you connect Google Drive or OneDrive to FileFortress, OAuth is what makes that connection possible.

Connecting OneDrive? From v0.32 you probably don't need this guide

On v0.32 and later, run filefortress remotes add onedrive and sign in — there is nothing to register and no credentials to copy, and the connection is made directly between your browser and Microsoft. Follow this guide only if you specifically want the connection to run through an app you own, with permissions you chose.

Google Drive has no one-click equivalent, so this guide is the way to connect it with permissions you control.

Why Bring Your Own OAuth?

Registering your own OAuth app puts the connection entirely in your name. What it gets you:

  • Full control over permissions — You decide exactly which scopes to grant, including narrowing a connection to read-only
  • Independent quota — Your own API limits, not shared with anyone else
  • Audit trail — Your provider's dashboard shows the app by name, and you can revoke it there at any time
  • No dependency on our app registrations — Your connection is unaffected by anything that happens to FileFortress's own OAuth apps

Where your tokens actually go. Your own app is not the only way to keep them off our servers, and it isn't automatic either — it depends on which version added the remote:

  • Remotes added with v0.32 or later — bring-your-own, and one-click OneDrive — are authorized in your browser and refreshed directly with the provider. Our server is in neither step.
  • Remotes added by an earlier version stored no app credentials, so they can't refresh on their own. They still renew through a FileFortress relay, which means your refresh token passes through our server. Re-adding such a remote moves it onto the on-device path.
  • The managed remotes add gdrive connection is brokered by our server by design — that's the one this guide lets you replace.

In every case your tokens live encrypted on your device. Where our server is involved it handles them only in passing — never written to our database.

Key Concepts

Client ID

A public identifier for your OAuth app. Think of it like a username that tells Google or Microsoft which app is requesting access.

Client Secret

A confidential password for your OAuth app. Keep this secure and never share it. Google issues one for desktop apps; Microsoft doesn't — a desktop app there is a "public client" and uses no secret at all.

Understanding Scopes

Scopes define what permissions your OAuth app requests. They're like a list of things you're allowing FileFortress to do with your cloud storage. Common scopes include:

Scope What It Allows When to Use
drive.readonly Read files and folders only When you only need to search and view files
drive Full read/write access to Drive When you need to modify or delete files
Files.Read.All Read files and folders only OneDrive, searching and browsing only
Files.ReadWrite.All Full read/write access OneDrive, when you want duplicate removal
offline_access Keep the connection alive without re-signing in OneDrive, always — see the warning below
Recommendation

Pick by what you intend to do. Read-only is enough for searching, browsing, and finding duplicates — indexing only reads metadata. You need a write scope to actually delete anything, so if you plan to use duplicates remove, choose the read/write scope now. Scopes are fixed when the remote is created, so widening later means reconnecting the remote.

Google Drive Setup

Follow these steps to create OAuth credentials for Google Drive:

Step 1: Access Google Cloud Console

Go to the Google Cloud Console and sign in with your Google account.

Step 2: Create a New Project

  1. Click the project selector dropdown at the top of the page
  2. Click New Project
  3. Enter a project name (e.g., "FileFortress OAuth")
  4. Click Create
Tip

You can use an existing project if you prefer, but creating a dedicated project keeps things organized and makes it easier to manage permissions later.

Step 3: Enable the Google Drive API

  1. With your project selected, go to APIs & Services → Library
  2. Search for "Google Drive API"
  3. Click on Google Drive API
  4. Click Enable

Step 4: Configure the OAuth Consent Screen

  1. Go to APIs & Services → OAuth consent screen
  2. Select External as the user type (unless you're a Google Workspace user)
  3. Click Create
  4. Fill in the required fields:
    • App name: FileFortress (or any name you'll recognize)
    • User support email: Your email address
    • Developer contact information: Your email address
  5. Click Save and Continue
  6. On the Scopes screen, click Add or Remove Scopes
  7. Select the scopes you need (see recommendations below)
  8. Click Save and Continue through the remaining screens
Don't skip this: set Publishing status to "In production"

A new Google app starts in Testing, and Google expires the sign-in of any app left in Testing after seven days. Your remote will work perfectly for a week and then start failing with an authorization error.

On the OAuth consent screen page, find Publishing status and click Publish app. Confirm when prompted.

You do not need Google to verify the app. Verification is about showing an app to strangers; you are the only user of yours. Publishing it unverified means one extra warning screen at sign-in — and it is what makes the connection last. Adding yourself as a "test user" does not avoid the seven-day expiry.

Publishing does change one thing besides the expiry: while in Testing only the accounts you listed as test users can consent, whereas a published app will show its consent screen to any Google account that is sent to it. Since only you have the Client ID and Secret, that is a small difference in practice — but keep both to yourself.

Step 5: Create OAuth Credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Select Desktop app as the application type. Create a new client rather than reusing one you already have — only the Desktop type accepts the local address FileFortress listens on
  4. Enter a name (e.g., "FileFortress Desktop")
  5. Leave the redirect URI list empty. There is nothing to add here — see the box below
  6. Click Create
  7. You'll see a popup with your Client ID and Client Secret
  8. Copy both values and store them securely — the Client Secret will not be shown again!
Don't register a redirect URI for Google

This is the opposite of the OneDrive instructions further down, so it is worth being explicit. When you add the remote, FileFortress starts a listener on your own machine and shows you the address it picked — something like http://localhost:54176/callback. The port is different every time.

A Desktop app client accepts that automatically, whatever the port, with an empty redirect URI list. A Web application client does not: it matches the address exactly, so a randomly chosen port can never match and sign-in fails with Error 400: redirect_uri_mismatch.

So if you see that error: you almost certainly created — or reused — a Web application client. Create a fresh Desktop app client and leave its redirect URIs blank.

Important

If you lose your Client Secret, you'll need to create new credentials. You cannot retrieve the secret after closing the popup.

Recommended Scopes for Google Drive

# Read-only — search and browse, but no duplicate removal
https://www.googleapis.com/auth/drive.readonly

# Read/write — needed for `duplicates remove`
https://www.googleapis.com/auth/drive

Google classes both of these as restricted scopes, which is why it shows the unverified-app warning during sign-in even for an app you built yourself. That warning is expected here and safe to click through — see the troubleshooting section below.

OneDrive Setup

Follow these steps to create OAuth credentials for OneDrive:

Step 1: Access Azure Portal

Go to the Azure Portal and sign in with your Microsoft account.

Note

You don't need an Azure subscription to create OAuth apps. The free tier of Azure Active Directory is sufficient.

Step 2: Register a New Application

  1. Go to Microsoft Entra ID (or search for "App registrations")
  2. Click App registrations in the left sidebar
  3. Click New registration
  4. Fill in the registration form:
    • Name: FileFortress (or any name you'll recognize)
    • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
    • Redirect URI: Select "Public client/native (mobile & desktop)" and enter exactly: http://localhost/callback
      The /callback path is required — Microsoft ignores the port number for localhost addresses but matches the path exactly, so a URI without it is rejected with "the provided value for the input parameter 'redirect_uri' is not valid".
  5. Click Register

Step 3: Allow Public Client Flows

  1. In the left sidebar, click Authentication
  2. Scroll to Advanced settings and set Allow public client flows to Yes
  3. Click Save

Desktop applications can't keep a secret, so Microsoft treats them as "public clients". This setting is what permits the sign-in to complete without one. Skip it and you'll get AADSTS7000218.

Step 4: Configure API Permissions

  1. In your app registration, click API permissions in the left sidebar
  2. Click Add a permission
  3. Select Microsoft Graph
  4. Select Delegated permissions
  5. Search for and add the scopes you need (see recommendations below)
  6. Click Add permissions

Step 5: Get Your Client ID

Go to your app's Overview page and copy the Application (client) ID. That's the only credential you need.

Don't create a client secret

A desktop app doesn't use one, and FileFortress won't ask you for one. The sign-in is protected by PKCE instead, which is the mechanism Microsoft recommends for exactly this case. If you already created a secret, you can safely delete it — leave the secret prompt empty.

Recommended Scopes for OneDrive

# Read-only — search and browse, but no duplicate removal
Files.Read.All
offline_access
User.Read

# Read/write — needed for `duplicates remove`
Files.ReadWrite.All
offline_access
User.Read
Include offline_access in either set

Without it Microsoft issues no refresh token at all, and setup stops immediately with "No refresh token was returned". It isn't optional.

Using Your Credentials with FileFortress

With your credentials in hand, connect your cloud storage. The interactive setup walks you through the same steps as this guide, so you can start there if you'd rather not pass everything on the command line:

# Start the interactive OAuth setup
filefortress remotes add oauth

# Google Drive — needs both the client ID and the secret
filefortress remotes add oauth \
  --provider gdrive \
  --name "My Google Drive" \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

# OneDrive (v0.32+) — client ID only; a desktop app has no secret
filefortress remotes add oauth \
  --provider onedrive \
  --name "My OneDrive" \
  --client-id YOUR_CLIENT_ID

# Narrower: search and browse, but never change anything.
# Without --scopes you get the read/write default.
filefortress remotes add oauth \
  --provider onedrive \
  --name "My OneDrive" \
  --client-id YOUR_CLIENT_ID \
  --scopes "Files.Read.All offline_access User.Read"

Before v0.32, --client-secret was required for OneDrive too. If your version rejects the command without one, either upgrade or pass the secret from your app registration.

To keep your Google secret off the command line and out of your shell history, use --client-secret-file, --client-secret-env, or the FILEFORTRESS_OAUTH_CLIENT_SECRET environment variable instead of --client-secret.

Security Best Practices

🔒 Keep Secrets Secure

Never commit your Client Secret to version control. Use environment variables or secret files.

📝 Audit Regularly

Review your OAuth app's activity in Google Cloud Console or Azure Portal periodically.

🚫 Use Minimum Permissions

Only request scopes you actually need. Read-only covers searching and browsing; add write access only if you want FileFortress to delete duplicates for you.

🔄 Rotate Secrets

Create new credentials periodically and delete old ones to maintain security.

Publishing Status

Google: publish your app to In production, as described above. Leaving it in Testing is the single most common reason a Google Drive remote stops working after a week. Verification is a separate thing and is not needed for an app only you use.

Microsoft: nothing to do. Azure app registrations have no equivalent testing mode or expiry, and your refresh token stays valid as long as you keep using the remote.

Troubleshooting

"App is not verified" Warning

Both Google and Microsoft may show a warning that your app isn't verified. This is normal for personal OAuth apps. Click "Advanced" or "Continue anyway" to proceed. Your app is only accessing your own data, so this warning is just a standard security measure.

Google: "Error 400: redirect_uri_mismatch"

Your Google client is the wrong type. FileFortress signs you in through a listener on your own machine at an address like http://localhost:54176/callback, and the port changes on every run.

  • A Web application client matches the redirect address exactly, so a random port can never match. Reusing one you already had is the usual cause
  • The fix: create a new OAuth client of type Desktop app and leave its redirect URI list empty — Google accepts the local address automatically
  • Do not paste an address ending in /api/v1/remotes/gdrive/exchange. That belongs to a different sign-in method and will not work here

Invalid Client or Unauthorized

  • Double-check you've copied the Client ID correctly (and the Secret, for Google)
  • Ensure the OAuth consent screen is configured (for Google)
  • Verify the correct API permissions/scopes are added
  • For Microsoft: confirm Allow public client flows is set to Yes — without it the sign-in fails with error AADSTS7000218

Connection Worked, Then Stopped After About a Week

This is almost always a Google app still in Testing mode. Google expires the sign-in of unpublished apps after seven days.

  • The fix: in the Google Cloud Console, go to APIs & Services → OAuth consent screen, and set Publishing status to In production via Publish app. Publishing without verification is fine and is what you want here
  • Then reconnect the remote so it picks up a fresh, non-expiring authorization. Publishing does not revive the expired sign-in on its own, and there is no in-place re-authorization yet, so remove the remote and add it again under the same name: filefortress remotes remove <remote-name>, then re-run your original filefortress remotes add oauth --provider gdrive command. You will be asked for folder selection and encryption settings again, and the re-added remote is indexed from scratch

If the remote is encrypted, have your password and salt before you remove it

Re-adding an encrypted remote means entering the same encryption password and salt you used originally. FileFortress stores them only on your device, so it cannot recover or verify them for you — and files already encrypted in your cloud can only be read back with the values that encrypted them. Write them down before you run remotes remove, not after.

Other Token Refresh Failures

  • For Microsoft: check that the offline_access scope was included — without it the provider never issues a refresh token, and setup fails immediately with "No refresh token was returned"
  • Check whether you revoked the app's access in your provider's account settings; if so, reconnect the remote
  • If nothing above explains it, reconnect from scratch: filefortress remotes remove <remote-name>, then re-run your filefortress remotes add oauth command

Related Articles