Autenticação

Existem cinco métodos de autenticação compatíveis:

  • OAuth 2.0
  • Nome de usuário/senha
  • Nome de usuário/token
  • Chave
  • None

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 USER_PASS/USER_TOKEN/KEY NONE
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

getAuthType()

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

OAUTH2

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Returns the Auth Type of this connector.
     * @return {object} The Auth type.
     */
    function getAuthType() {
      var cc = DataStudioApp.createCommunityConnector();
      return cc.newAuthTypeResponse()
        .setAuthType(cc.AuthType.OAUTH2)
        .build();
    }

USER_PASS

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Returns the Auth Type of this connector.
     * @return {object} The Auth type.
     */
    function getAuthType() {
      var 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 (em inglês) 
/**
     * Returns the Auth Type of this connector.
     * @return {object} The Auth type.
     */
    function getAuthType() {
      var 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 (em inglês) 
/**
     * Returns the Auth Type of this connector.
     * @return {object} The Auth type.
     */
    function getAuthType() {
      var 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 (em inglês) 
/**
     * Returns the Auth Type of this connector.
     * @return {object} The Auth type.
     */
    function getAuthType() {
      var cc = DataStudioApp.createCommunityConnector();
      return cc.newAuthTypeResponse()
        .setAuthType(cc.AuthType.NONE)
        .build();
    }

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 (em inglês) 
/**
     * Resets the auth service.
     */
    function resetAuth() {
      getOAuthService().reset();
    }

USER_PASS

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Resets the auth service.
     */
    function resetAuth() {
      var userProperties = PropertiesService.getUserProperties();
      userProperties.deleteProperty('dscc.username');
      userProperties.deleteProperty('dscc.password');
    }

USER_TOKEN

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Resets the auth service.
     */
    function resetAuth() {
      var user_tokenProperties = PropertiesService.getUserProperties();
      user_tokenProperties.deleteProperty('dscc.username');
      user_tokenProperties.deleteProperty('dscc.password');
    }

KEY

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Resets the auth service.
     */
    function resetAuth() {
      var userProperties = PropertiesService.getUserProperties();
      userProperties.deleteProperty('dscc.key');
    }

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 (em inglês) 
/**
     * Returns true if the auth service has access.
     * @return {boolean} True if the auth service has access.
     */
    function isAuthValid() {
      return getOAuthService().hasAccess();
    }

USER_PASS

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Returns true if the auth service has access.
     * @return {boolean} True if the auth service has access.
     */
    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);
    }

USER_TOKEN

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Returns true if the auth service has access.
     * @return {boolean} True if the auth service has access.
     */
    function isAuthValid() {
      var userProperties = PropertiesService.getUserProperties();
      var userName = userProperties.getProperty('dscc.username');
      var 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 (em inglês) 
/**
     * Returns true if the auth service has access.
     * @return {boolean} True if the auth service has access.
     */
    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

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 (em inglês) 
/**
     * 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 (em inglês) 
/**
     * 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) {
      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()

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. Veja 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 (em inglês) 
/**
     * 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();
    }
.

USER_PASS, USER_TOKEN e KEY

Os códigos a seguir são necessários somente para os fluxos de autenticação USER_PASS, USER_TOKEN e 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.

USER_PASS

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Sets the credentials.
     * @param {Request} request The set credentials request.
     * @return {object} An object with an errorCode.
     */
    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'
      };
    }

USER_TOKEN

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Sets the credentials.
     * @param {Request} request The set credentials request.
     * @return {object} An object with an errorCode.
     */
    function setCredentials(request) {
      var creds = request.userToken;
      var username = creds.username;
      var 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.
      var validCreds = checkForValidCreds(username, token);
      if (!validCreds) {
        return {
          errorCode: 'INVALID_CREDENTIALS'
        };
      }
      var userProperties = PropertiesService.getUserProperties();
      userProperties.setProperty('dscc.username', username);
      userProperties.setProperty('dscc.token', token);
      return {
        errorCode: 'NONE'
      };
    }

KEY

data-studio/auth.gs
Ver no GitHub (em inglês) 
/**
     * Sets the credentials.
     * @param {Request} request The set credentials request.
     * @return {object} An object with an errorCode.
     */
    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'
      };
    }