OAuth2 for Apps Script

The library follows a four-step workflow to authorize and use an API:

1. Create the Service: Initialize an OAuth2Service object with your client credentials, endpoints, and configuration.
2. Direct the User: Since Apps Script cannot perform automatic redirects, generate an authorization URL using getAuthorizationUrl() and present it to the user as a clickable link (e.g., in a sidebar or dialog).
3. Handle the Callback: Create a callback function (specified via setCallbackFunction) that receives the request and passes it to service.handleCallback(request) to complete the flow.
4. Make Requests: Once authorized, retrieve the token via service.getAccessToken() and include it in the Authorization: Bearer <token> header of your UrlFetchApp calls.

/**
 * 1. Create the OAuth2 service
 */
function getDriveService_() {
  return OAuth2.createService('drive')
      .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/auth')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setClientId('...')
      .setClientSecret('...')
      .setCallbackFunction('authCallback')
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope('https://www.googleapis.com/auth/drive')
      .setParam('login_hint', Session.getEffectiveUser().getEmail())
      .setParam('access_type', 'offline')
      .setParam('prompt', 'consent');
}

/**
 * 2. Direct the user to the authorization URL
 */
function showSidebar() {
  var driveService = getDriveService_();
  if (!driveService.hasAccess()) {
    var authorizationUrl = driveService.getAuthorizationUrl();
    var template = HtmlService.createTemplate(
        '<a href="<?= authorizationUrl ?>" target="_blank">Authorize</a>. Reopen the sidebar when the authorization is complete.');
    template.authorizationUrl = authorizationUrl;
    var page = template.evaluate();
    DocumentApp.getUi().showSidebar(page);
  }
}

/**
 * 3. Handle the callback
 */
function authCallback(request) {
  var driveService = getDriveService_();
  var isAuthorized = driveService.handleCallback(request);
  if (isAuthorized) {
    return HtmlService.createHtmlOutput('Success! You can close this tab.');
  } else {
    return HtmlService.createHtmlOutput('Denied. You can close this tab');
  }
}

/**
 * 4. Get the access token
 */
function makeRequest() {
  var driveService = getDriveService_();
  var response = UrlFetchApp.fetch('https://www.googleapis.com/drive/v2/files?maxResults=10', {
    headers: {
      Authorization: 'Bearer ' + driveService.getAccessToken()
    }
  });
}

To deploy a local copy of the Sample Web App to Google Apps Script, use the clasp command line tool. Ensure you have installed clasp and executed clasp login before proceeding.

1. Initialize the script project: Run the following commands in the project directory:

   clasp create "Sample Web App"
   clasp push
   clasp open

2. Retrieve the Redirect URI: In the Apps Script editor that opens, run the logRedirectUri function. Open the logs (View > Logs) and copy the displayed URL.
3. Configure GitHub OAuth: Go to the GitHub Developer console, create a new OAuth App, and paste the copied URL into the Authorization callback URL field.
4. Configure Credentials: In Code.gs, uncomment the CLIENT_ID and CLIENT_SECRET variables and paste the values from your GitHub OAuth App.
5. Deploy the application:

   clasp deploy

6. Access the Web App: Construct the execution URL using your deployment ID: https://script.google.com/macros/s/<DEPLOYMENT_ID>/exec.

clasp create "Sample Web App"
clasp push
clasp open
# ... after editing Code.gs ...
clasp deploy

To build a production-ready integration, follow these three patterns:

Token Storage

Always use .setPropertyStore() to persist tokens so users don't have to re-authorize every time. Use PropertiesService.getUserProperties() for user-specific access, or PropertiesService.getScriptProperties() for shared access.

Caching

To avoid hitting PropertiesService quotas, enable caching by adding .setCache(CacheService.getUserCache()). Ensure the cache scope matches your property store scope.

Locking

To prevent race conditions where multiple executions attempt to refresh an expired token simultaneously, use .setLock(LockService.getUserLock()). Ensure the lock scope matches your property store and cache scopes.

return OAuth2.createService('Foo')
    .setPropertyStore(PropertiesService.getUserProperties())
    .setCache(CacheService.getUserCache())
    .setLock(LockService.getUserLock())