Authentication

There are currently four natively supported authentication methods: OAuth 2.0, Username/Password, Token, and None. Depending on which method you are using, you must provide additional functions in your connector.

The following table indicates which functions you must define depending on the authentication type of your connector.

OAuth 2.0 Username/Password Key None
getAuthType() required required required required
resetAuth() required required required
isAuthValid() required required required
authCallback() required
get3PAuthorizationUrls() required
setCredentials() required required

getAuthType()

This function should return the authentication type for the connector.

OAUTH2

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

USER_PASS

function getAuthType() {
  return {
    "type": "USER_PASS"
  };
}

KEY

function getAuthType() {
  return {
    "type": "KEY"
  };
}

NONE

function getAuthType() {
  return {
    "type": "NONE"
  };
}

resetAuth()

This function will clear any credentials stored for the user for the third-party service.

OAUTH2

function resetAuth() {
  getOAuthService().reset();
}

USER_PASS

function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.username');
  userProperties.deleteProperty('dscc.password');
}

KEY

function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.key');
}

isAuthValid()

This function is called to determine if the authentication for the third-party service is valid. If authentication 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.

OAUTH2

function isAuthValid() {
  return getOAuthService().hasAccess();
}

USER_PASS

function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var userName = userProperties.getProperty('dscc.username');
  var password = userProperties.getProperty('dscc.password');
  // This assumes you have a validateCredentials function that
  // can validate if the userName and password are correct.
  return validateCredentials(userName, password);
}

KEY

function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var key = userProperties.getProperty('dscc.key');
  // This assumes you have a validateKey function that can validate
  // if the key is valid.
  return validateKey(key);
}

OAUTH2

Add and setup OAuth2 for Apps Script 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 to the OAuth2 service in your code.

For example, an OAuth2 service named exampleService:

function getOAuthService() {
  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 third-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');
  };
};

get3PAuthorizationUrls()

This function is called to get the URL that is required to initiate the auth flow for the third-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 third-party service. See the reference for get3PAuthorizationUrls().

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

function get3PAuthorizationUrls() {
  return getOAuthService().getAuthorizationUrl();
}

USER_PASS and KEY

The following is only needed for the USER_PASS and KEY authentication flows.

setCredentials()

setCredentials is called after the user enters either their USER_PASS or KEY information on the community connector configuration page. You should use the Properties Service to save the credentials on a per-user basis using UserProperties.

USER_PASS

function setCredentials(request) {
  var creds = request.userPass;
  var username = creds.username;
  var password = creds.password;

  // Optional
  // Check if the provided username and password are valid through a
  // call to your service. You would have to have a `checkForValidCreds`
  // function defined for this to work.
  var validCreds = checkForValidCreds(username, password);
  if (!validCreds) {
    return {
      errorCode: "INVALID_CREDENTIALS"
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.password', password);
  return {
    errorCode: "NONE"
  };
}

KEY

function setCredentials(request) {
  var key = request.key;

  // Optional
  // Check if the provided key is valid through a call to your service.
  // You would have to have a `checkForValidKey` function defined for
  // this to work.
  var validKey = checkForValidKey(key);
  if (!validKey) {
    return {
      errorCode: "INVALID_CREDENTIALS"
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.key', key);
  return {
    errorCode: "NONE"
  };
}