Authentication with OAuth 2.0

If your connector requires the user to authorize access to a 3rd-party service using OAuth 2.0, then there are additional auth specific functions that your connector is expected to provide to support the OAuth 2.0 flow.

Define authentication type in getAuthType()

If your data source requires OAuth 2.0 authentication, make sure that getAuthType() returns OAUTH2 as the AuthType.

An example getAuthType() function for a data source that requires OAuth 2.0 authentication, :

function getAuthType() {
  var response = {
    "type": "OAUTH2"
  };
  return response;
}

Add and setup OAuth2 library

Follow the setup instructions for the OAuth2 for Apps Script library to add it to your connector project. Then follow the first step in the usage guide to create an OAuth2 service in your connector project. Your OAuth2 service can have any valid function name but make sure to use the same name while referring ot the OAuth2 service in your code.

For example, an OAuth2 service named getOAuthService:

var getOAuthService = function() {
  return OAuth2.createService('exampleService')
    .setAuthorizationBaseUrl('...')
    .setTokenUrl('...')
    .setClientId('...')
    .setClientSecret('...')
    .setPropertyStore(PropertiesService.getUserProperties())
    .setCallbackFunction('authCallback')
    .setScope('...');
};

authCallback()

This function is called to complete the OAuth 2.0 flow. The callback response from the 3rd-party auth service is provided as an argument and should be handled by this function.

Example of handling the OAuth 2.0 callback using the OAuth2 for Apps Script library:

function authCallback(request) {
  var authorized = getOAuthService().handleCallback(request);
  if (authorized) {
    return HtmlService.createHtmlOutput('Success! You can close this tab.');
  } else {
    return HtmlService.createHtmlOutput('Denied. You can close this tab');
  };
};

isAuthValid()

This function is called to determine if the authentication for the 3rd-party service is valid. If the auth is valid then it is expected that calls to getData() and getSchema() will not fail due to unauthorized access. If the auth is not valid then the user may receive a notification to start the authorization flow. See the reference for isAuthValid().

Example of checking whether auth is valid using the OAuth2 for Apps Script library:

function isAuthValid() {
  var service = getOAuthService();
  if (service == null) {
    return false;
  }
  return service.hasAccess();
}

get3PAuthorizationUrls()

The function is called to get the URL that is required to initiate the auth flow for the 3rd-party service. If isAuthValid returns false then the URL returned will be displayed to the user as a button or link so that they can authorize access to the 3rd-party service. See the reference for get3PAuthorizationUrls().

Example of returning the authorization Url using the OAuth2 for Apps Script library:

function get3PAuthorizationUrls() {
  var service = getOAuthService();
  if (service == null) {
    return '';
  }
  return service.getAuthorizationUrl();
}

resetAuth()

This function will clear any credentials stored for the user for the 3rd-party service. This may be required if there is an auth issue.

Example of resetting auth using using the OAuth2 for Apps Script library:

function resetAuth() {
  var service = getOAuthService()
  service.reset();
}