Authentication

Os conectores da comunidade aceitam os seguintes métodos de autenticação:

• OAuth 2.0
• Caminho/Nome de usuário/Senha
• Caminho/chave
• Nome de usuário/senha
• Nome de usuário/token
• Chave
• Nada

Dependendo do método usado, você precisa disponibilizar funções adicionais no seu conector.

A tabela a seguir indica quais funções você deve definir dependendo do tipo de autenticação do conector.

	OAUTH2	PATH_USER_PASS PATH_KEY USER_PASS USER_TOKEN KEY	NENHUMA
getAuthType()	obrigatório	obrigatório	obrigatório
resetAuth()	obrigatório	obrigatório
isAuthValid()	obrigatório	obrigatório
authCallback()	obrigatório
get3PAuthorizationUrls()	obrigatório
setCredentials()		obrigatório

Aviso: para garantir que as credenciais sejam mantidas em segredo, seu conector precisa usar um tipo de autenticação compatível e não depender dos campos de configuração do conector (por exemplo, getConfig) para obter credenciais.

getAuthType()

Esta função deve retornar o tipo de autenticação do conector.

OAUTH2

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  const cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.OAUTH2)
      .build();
}

PATH_USER_PASS

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
    .setAuthType(cc.AuthType.PATH_USER_PASS)
    .setHelpUrl('https://www.example.org/connector-auth-help')
    .build();
}

PATH_KEY

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
    .setAuthType(cc.AuthType.PATH_KEY)
    .setHelpUrl('https://www.example.org/connector-auth-help')
    .build();
}

USER_PASS

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  const cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.USER_PASS)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

USER_TOKEN

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  const cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.USER_TOKEN)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

KEY

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  const cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.KEY)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

NONE

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  const cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.NONE)
      .build();
}

Observação: consulte getAuthType() para ver a documentação completa.

resetAuth()

Esta função limpará todas as credenciais do usuário armazenadas para o serviço de terceiros.

OAUTH2

data-studio/auth.gs

Ver no GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  getOAuthService().reset();
}

PATH_USER_PASS

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.path');
  userProperties.deleteProperty('dscc.username');
  userProperties.deleteProperty('dscc.password');
}

PATH_KEY

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.path');
  userProperties.deleteProperty('dscc.key');
}

USER_PASS

data-studio/auth.gs

Ver no GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.username');
  userProperties.deleteProperty('dscc.password');
}

USER_TOKEN

data-studio/auth.gs

Ver no GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  const userTokenProperties = PropertiesService.getUserProperties();
  userTokenProperties.deleteProperty('dscc.username');
  userTokenProperties.deleteProperty('dscc.password');
}

KEY

data-studio/auth.gs

Ver no GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.key');
}

Observação: consulte resetAuth() para ver a documentação completa.

isAuthValid()

Esta função é chamada para determinar se a autenticação do serviço de terceiros é válida. Se for, espera-se que as chamadas para getData() e getSchema() não apresentem falha devido ao acesso não autorizado. Caso contrário, o usuário poderá receber uma notificação para iniciar o fluxo de autorização.

OAUTH2

data-studio/auth.gs

Ver no GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  return getOAuthService().hasAccess();
}

PATH_USER_PASS

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var path = userProperties.getProperty('dscc.path');
  var userName = userProperties.getProperty('dscc.username');
  var password = userProperties.getProperty('dscc.password');
  // This assumes you have a validateCredentials function that
  // can validate if the path, userName and password are correct.
  return validateCredentials(path, userName, password);
}

PATH_KEY

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var path = userProperties.getProperty('dscc.path');
  var key = userProperties.getProperty('dscc.key');
  // This assumes you have a validateCredentials function that
  // can validate if the path and key are correct.
  return validateCredentials(path, key);
}

USER_PASS

data-studio/auth.gs

Ver no GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  const userProperties = PropertiesService.getUserProperties();
  const userName = userProperties.getProperty('dscc.username');
  const 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);
}

USER_TOKEN

data-studio/auth.gs

Ver no GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  const userProperties = PropertiesService.getUserProperties();
  const userName = userProperties.getProperty('dscc.username');
  const token = userProperties.getProperty('dscc.token');
  // This assumes you have a validateCredentials function that
  // can validate if the userName and token are correct.
  return validateCredentials(userName, token);
}

KEY

data-studio/auth.gs

Ver no GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  const userProperties = PropertiesService.getUserProperties();
  const key = userProperties.getProperty('dscc.key');
  // This assumes you have a validateKey function that can validate
  // if the key is valid.
  return validateKey(key);
}

Observação: consulte isAuthValid() para ver a documentação completa.

OAUTH2

Adicionar e configurar o OAuth2 para a biblioteca do Apps Script

Siga as instruções de configuração da biblioteca do OAuth2 para Apps Script para adicioná-la ao seu projeto de conector. Em seguida, siga a primeira etapa no guia de uso para criar um serviço do OAuth2 no seu projeto de conector. O serviço do OAuth2 pode ter qualquer nome de função válido. No entanto, use o mesmo nome ao fazer referência ao serviço do OAuth2 no seu código.

Por exemplo, um serviço do OAuth2 chamado exampleService:

data-studio/auth.gs

Ver no GitHub

/**
 * Returns the configured OAuth Service.
 * @return {Service} The OAuth Service
 */
function getOAuthService() {
  return OAuth2.createService('exampleService')
      .setAuthorizationBaseUrl('...')
      .setTokenUrl('...')
      .setClientId('...')
      .setClientSecret('...')
      .setPropertyStore(PropertiesService.getUserProperties())
      .setCallbackFunction('authCallback')
      .setScope('...');
};

authCallback()

Esta função é chamada para concluir o fluxo do OAuth 2.0. A resposta de retorno de chamada do serviço de autenticação de terceiros é disponibilizada como um argumento e deve ser tratada por essa função.

Exemplo de tratamento do retorno de chamada do OAuth 2.0 usando a biblioteca do OAuth2 para Apps Script:

data-studio/auth.gs

Ver no GitHub

/**
 * The OAuth callback.
 * @param {object} request The request data received from the OAuth flow.
 * @return {HtmlOutput} The HTML output to show to the user.
 */
function authCallback(request) {
  const 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()

Esta função é chamada para visualizar o URL que é necessário para iniciar o fluxo de autenticação do serviço de terceiros. Se isAuthValid retornar false, o URL retornado será exibido ao usuário como um botão ou link para que ele possa autorizar o acesso ao serviço de terceiros. Consulte a referência para get3PAuthorizationUrls().

Exemplo de devolução do URL de autorização usando a biblioteca do OAuth2 para Apps Script:

data-studio/auth.gs

Ver no GitHub

/**
 * Gets the 3P authorization URL.
 * @return {string} The authorization URL.
 * @see https://developers.google.com/apps-script/reference/script/authorization-info
 */
function get3PAuthorizationUrls() {
  return getOAuthService().getAuthorizationUrl();
}

Observação: se você estiver usando os Advanced Services do Apps Script ou as APIs do Google no seu conector, talvez seja necessário verificar o conector em questão. Para ver detalhes, consulte Verificação do cliente OAuth (em inglês)

.

USER_PASS, USER_TOKEN, KEY, PATH_USER_PASS e PATH_KEY

Os códigos a seguir são necessários somente para os fluxos de autenticação USER_PASS, USER_TOKEN, KEY, PATH_USER_PASS e PATH_KEY.

setCredentials()

setCredentials é chamado depois que o usuário insere suas informações de credenciais na página de configuração do conector da comunidade. É recomendável usar o Serviço de propriedades para salvar as credenciais por usuário utilizando UserProperties.

PATH_USER_PASS

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.pathUserPass;
  var path = creds.path;
  var username = creds.username;
  var password = creds.password;

  // Optional
  // Check if the provided path, 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(path, username, password);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.path', path);
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.password', password);
  return {
    errorCode: 'NONE'
  };
}

PATH_KEY

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.pathKey;
  var path = creds.path;
  var key = creds.key;

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

USER_PASS

data-studio/auth.gs

Ver no GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  const creds = request.userPass;
  const username = creds.username;
  const 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.
  const validCreds = checkForValidCreds(username, password);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.password', password);
  return {
    errorCode: 'NONE'
  };
}

USER_TOKEN

data-studio/auth.gs

Ver no GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  const creds = request.userToken;
  const username = creds.username;
  const token = creds.token;

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

KEY

data-studio/auth.gs

Ver no GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  const 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.
  const validKey = checkForValidKey(key);
  if (!validKey) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.key', key);
  return {
    errorCode: 'NONE'
  };
}

Observação: consulte setCredentials() para ver a documentação completa.