Google Drive

​

Overview

​

Pre-built tooling

​

Pre-built integrations

​

Access requirements

​

Setup guide

​

Pre-built Google Drive Integration Overview

Nango’s pre-built Google Drive integration allows you to sync specific files and folders that your users select. The integration uses the following components:

1. OAuth Flow: Handle authentication using Nango’s SDK
2. Google Drive Picker: Let users select files and folders to sync
3. Document Sync: Sync metadata for selected files and folders
4. Document Fetching: Download individual file contents as needed

​

Complete Implementation Guide

The easiest way to implement Google Drive integration is to use the Nango Sample App as your starting point. The sample app provides a complete, production-ready implementation that you can customize for your needs.

You can watch a Loom video walkthrough of the sample app if you prefer.

​

Requirements

• Docker (desktop) installed & running
• NodeJS & NPM installed
• A Nango account (sign up at nango.dev)

​

Install & Run Instructions (~10 min)

1. Clone the sample app repository:

   git clone https://github.com/NangoHQ/sample-app.git
   cd sample-app
   npm install

2. Start the app:

   npm run start

   You should see [back] Listening on http://0.0.0.0:3010 in the end. If this doesn’t show, kill the process with Ctrl + C and run npm run start again. Sometimes the docker database takes a bit longer to start up.

3. Expose the app to the internet:

   npm run webhooks-proxy

   This should print an output similar to: your url is: https://cute-zebras-hug.loca.lt

   If you experience any troubles with this we recommend using ngrok and you need to expose the URL http://localhost:3010:

   ngrok http 3010

4. Configure Nango webhooks:

   • Copy the URL from the previous step
   • Go to Environment Settings in Nango
   • Set the primary Webhook URL to ${URL}/webhooks-from-nango
   • Example: https://tame-socks-warn.loca.lt/webhooks-from-nango

5. Access the sample app:

   • Open http://localhost:3011
   • Click on “Files” to start the Google Drive integration

6. Connect your Google Drive account:

   • Click on the “Import from Google Drive” button
   • In the connect popup, click on the “Connect” button
   • Select your Google Drive account and authorize the app
   • Click on the “Finish” button to close the modal.

7. Select the files and folders you want to sync:

   • Click on the “Select Files from Google Drive” button
   • A modal will appear with the files and folders you can choose from.
   • Select the files and folders you want to sync.
   • Click on the “Select” button to close the modal.

8. The files and folders will be synced to your Nango account and displayed in the UI.

9. Download a file:

   • Click on the “Download” button to download the file.
   • The file will be downloaded to your computer.

10. Disconnect your Google Drive account:

    • Click on the “Disconnect” button to disconnect your Google Drive account.
    • The files and folders will be deleted from your Nango account.

​

What Happens Under the Hood

The sample app uses Nango to:

1. Authentication

   • Authenticate users with Google Drive
   • Show the Google Drive picker
   • Handle OAuth flow automatically

2. File Syncing

   • Sync selected files & folders
   • Initial sync on selection
   • Periodic updates

3. File Download

   • Download raw file content
   • Handle different file types
   • Use Nango’s proxy for reliable downloads

​

Key Components

​

Frontend Implementation

1. Authorization Flow The authorization process is implemented in front-end/src/api.ts:

   • postConnectSession: Initiates the OAuth connection
   • getNangoCredentials: Retrieves credentials after successful authorization

   The flow works as follows:

   1. Frontend initiates connection via postConnectSession
   2. Backend creates a Nango connection session
   3. User is redirected to Google OAuth consent screen
   4. After authorization, user is redirected back to the app
   5. Frontend can fetch credentials using getNangoCredentials

​

Backend Implementation

1. Webhook Handler & Data Sync The webhook handling and data sync logic is implemented in back-end/src/routes/postWebhooks.ts:

   Key components:

   • Main webhook handler that verifies signatures and routes requests
   • handleNewConnectionWebhook: Processes new Google Drive connections
   • handleSyncWebhook: Handles sync completion and data processing

   The sync process:

   1. Nango syncs files from Google Drive
   2. Webhook notifies backend of sync completion
   3. Backend fetches records using nango.listRecords
   4. File metadata is stored in the database
   5. Deletions are tracked and handled appropriately

2. File Download with Proxy File download functionality is implemented in back-end/src/routes/downloadFile.ts:

   The download process:

   1. Frontend requests file download with file ID and connection ID
   2. Backend uses Nango proxy to fetch file from Google Drive
   3. File is streamed to client with proper headers
   4. Error handling ensures graceful failure

   Key features:

   • Uses Nango proxy for secure file access
   • Proper content type and disposition headers
   • Streaming response for efficient file transfer
   • Comprehensive error handling

​

Integration Flow

1. Authorization Flow:

   • Frontend initiates OAuth via postConnectSession (front-end/src/api.ts)
   • User authorizes access to Google Drive
   • Backend receives webhook for new connection (back-end/src/routes/postWebhooks.ts)
   • Initial sync is triggered automatically

2. Data Sync Flow:

   • Nango syncs files from Google Drive
   • Webhook notifies backend of sync completion
   • Backend processes records and updates database
   • File metadata is stored for later access

3. File Download Flow:

   • Frontend requests file download
   • Backend uses Nango proxy to fetch file (back-end/src/routes/downloadFile.ts)
   • File is streamed to client
   • Proper error handling ensures reliability

​

Nango Dashboard

Explore these sections in your Nango account:

1. Google Drive Integration

   • Integration Settings
   • Configure sync settings
   • View integration status

2. Connections

   • View Connections
   • Monitor sync status
   • Check connection health

3. Logs

   • View Logs
   • Track sync operations
   • Debug issues

​

Common Issues and Solutions

1. Connection Issues

   • Check Docker is running
   • Verify webhook URL is correct
   • Ensure Google Cloud credentials are valid

2. Sync Problems

   • Check Nango logs
   • Verify file permissions
   • Monitor sync status

​

File Type Support

The sample app supports all Google Drive file types through Nango’s proxy:

• Regular files (PDFs, images, etc.)
• Google Docs
• Google Sheets
• Google Slides
• Other Google Workspace files

The implementation handles file type conversion and downloading automatically.

​

Useful links

​

Common Scopes

​

API gotchas

• From the scopes page, make sure to select scopes based on the APIs you enabled earlier when setting up the app.
• Under certain circumstances, Google expires a user’s refresh token and the token refresh in Nango will fail. You can find a list of reasons from Google here, including:

1. The user has revoked your app’s access.
2. The user changed passwords and the refresh token contains Gmail scopes.
3. The user account has exceeded a maximum number of granted (live) refresh tokens.
4. The user granted time-based access to your app and the access expired.
5. If an admin set any of the services requested in your app’s scopes to Restricted.
6. For Google Cloud Platform APIs - the session length set by the admin could have been exceeded.
7. In “Testing” mode with an external user type, refresh tokens expire in 7 days unless only basic scopes are used — userinfo.email, userinfo.profile, openid, or their OpenID Connect equivalents. You can remove this 7-day limit by switch from Testing to Production. Follow step 6 in the Setup Guide above.
8. Google allows up to 100 refresh tokens per account per OAuth client ID; new tokens overwrite the oldest without warning when the limit is reached.

• While setting up the OAuth credentials, the Authorized JavaScript origins should be your site URL (https://app.nango.dev if you’re testing from the Nango UI).
• For applications using sensitive or restricted scopes, Google requires verification and a security assessment. This process can take several weeks to complete.
• Google’s OAuth consent screen has different configurations for “External” and “Internal” user types. Internal is only available for Google Workspace users and limits access to users within your organization.
• Google implements incremental authorization, allowing you to request additional scopes over time without requiring users to re-authorize all previously granted scopes.
• Google enforces rate limits on API requests, which vary depending on the specific API being used.