Autenticar como um projeto do Google Apps Script usando contas de serviço

Este guia explica como autenticar com uma conta de serviço ao chamar APIs no Apps Script.

Uma conta de serviço é um tipo especial de conta usada por um aplicativo, em vez de uma pessoa. É possível usar uma conta de serviço para acessar dados ou realizar ações pela conta do robô ou para acessar dados em nome de usuários do Google Workspace ou do Cloud Identity. Para mais informações, consulte as Noções básicas sobre contas de serviço.

Para uma visão geral sobre a autenticação das APIs do Google Workspace, consulte Criar credenciais de acesso.

Quando usar contas de serviço no Apps Script

Por padrão, o Apps Script usa as credenciais do usuário do script para chamar APIs. Se você estiver chamando APIs do Google usando UrlFetchApp, poderá receber um token de acesso para o usuário do script chamando ScriptApp.getOAuthToken.

No entanto, o uso de contas de serviço oferece várias vantagens em relação a ScriptApp.getOAuthToken em alguns cenários. Considere usar a autenticação da conta de serviço por estes motivos:

• Melhor desempenho com APIs do Cloud e serviços do Google Cloud: muitas APIs do Cloud são projetadas para autenticação de contas de serviço. As contas de serviço também podem oferecer uma maneira mais integrada, confiável e segura de interagir com a maioria das APIs.
• Permissões separadas: as contas de serviço têm permissões próprias, separadas de qualquer usuário. O método de autenticação ScriptApp.getOAuthToken pode falhar quando você compartilha o projeto com outros usuários. Ao usar contas de serviço, compartilhe scripts e publique-os como complementos do Google Workspace.
• Scripts automatizados e tarefas de longa duração: as contas de serviço permitem executar scripts automatizados, processos em lote ou tarefas em segundo plano sem a entrada do usuário.
• Segurança aprimorada e princípio de privilégio mínimo: conceda permissões específicas às contas de serviço, fornecendo acesso apenas aos recursos de que elas precisam. Isso segue o princípio de privilégio mínimo, que reduz os riscos de segurança. O uso de ScriptApp.getOAuthToken geralmente concede a um script todas as permissões do usuário, o que pode ser muito amplo.
• Gerenciamento de acesso centralizado: as contas de serviço são gerenciadas usando o Gerenciamento de identidade e acesso (IAM) do Google Cloud. O IAM ajuda as organizações do Google Workspace a gerenciar o acesso a serviços autenticados em projetos do Apps Script.

Pré-requisitos

• Um projeto do Google Cloud.
• No seu projeto na nuvem, ative as APIs que você quer autenticar usando credenciais de conta de serviço.
• Para atribuir papéis a contas de serviço, você precisa ter privilégios de superadministrador.

Criar uma conta de serviço

No seu projeto na nuvem, crie uma conta de serviço:

Console do Google Cloud

1. No console do Google Cloud, acesse o menu Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Clique em Criar conta de serviço.
3. Preencha os detalhes da conta de serviço e clique em Criar e continuar.
   Observação: por padrão, o Google cria um ID de conta de serviço exclusivo. Se você quiser mudar o ID, modifique-o no campo "ID da conta de serviço".
4. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar acesso a recursos.
5. Clique em Continuar.
6. Opcional: insira usuários ou grupos que podem gerenciar e realizar ações com essa conta de serviço. Para mais detalhes, consulte Como gerenciar a identidade temporária de conta de serviço.
7. Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI gcloud

1. Crie a conta de serviço:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar acesso a recursos.

Atribuir um papel à conta de serviço

É necessário atribuir um papel predefinido ou função personalizada a uma conta de serviço por uma conta de superadministrador.

1. No Google Admin Console, acesse Menu > Conta > Funções do administrador.

   Acessar Funções do administrador

2. Aponte para a função que você quer atribuir e clique em Atribuir administrador.

3. Clique em Atribuir contas de serviço.

4. Digite o endereço de e-mail da conta de serviço.

5. Clique em Adicionar > Atribuir função.

Criar credenciais para uma conta de serviço

É necessário receber credenciais na forma de um par de chaves públicas/privadas. Essas credenciais são usadas pelo código para autorizar ações da conta de serviço no app.

Para receber credenciais da sua conta de serviço:

1. No console do Google Cloud, acesse o menu Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Selecione a conta de serviço.
3. Clique em Chaves > Adicionar chave > Criar nova chave.
4. Selecione JSON e clique em Criar.

   Seu novo par de chave pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON transferido por download como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia dessa chave. Para informações sobre como armazenar sua chave com segurança, consulte Como gerenciar chaves de contas de serviço.

5. Clique em Fechar.

Copiar o número do projeto na nuvem

1. No console do Google Cloud, acesse o menu Menu > IAM e administrador > Configurações.

   Acessar as configurações do IAM e do administrador

2. No campo Número do projeto, copie o valor.

Configurar a autenticação da conta de serviço no projeto do Apps Script

Esta seção explica como adicionar as credenciais da conta de serviço do seu projeto na nuvem a um projeto do Apps Script.

Definir o projeto na nuvem no Apps Script

1. Acesse o Apps Script para abrir ou criar um projeto:

   
   Abrir o Apps Script

2. No projeto do Apps Script, clique em Configurações do projeto .

3. Em projeto na nuvem do Google, clique em Alterar projeto.

4. Em Número do projeto do Google Cloud, cole o número do projeto na nuvem.

5. Clique em Configurar projeto.

Salvar as credenciais como uma propriedade do script

Armazene as credenciais da conta de serviço com segurança salvando as como uma propriedade do script nas configurações do projeto do Apps Script:

1. Copie o conteúdo do arquivo JSON da conta de serviço (credentials.json) que você criou na seção anterior.
2. No projeto do Apps Script, acesse Configurações do projeto .
3. Na página Configurações do projeto, acesse Propriedades do script e clique em Adicionar propriedade do script e insira o seguinte:
   • No campo Propriedade, insira SERVICE_ACCOUNT_KEY.
   • No campo Valor, cole o conteúdo do arquivo de chave JSON.
4. Clique em Salvar propriedades do script.

Adicionar a biblioteca do OAuth2

Para processar o fluxo de autenticação do OAuth2, use a biblioteca do Apps Script library apps-script-oauth2.

Para adicionar a biblioteca ao projeto do Apps Script:

1. No editor de script do Apps Script, à esquerda, ao lado de Bibliotecas, clique em Adicionar uma biblioteca .
2. No campo ID do script, insira 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Clique em Pesquisar.
4. Selecione a versão mais recente e clique em Adicionar.

Chamar uma API usando credenciais de conta de serviço

Para usar as credenciais da conta de serviço do projeto do Apps Script, use a seguinte função getServiceAccountService():

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Substitua SCOPE pelo escopo de autorização necessário para chamar a API. O script usa as credenciais da conta de serviço que você salvou como uma propriedade de script SERVICE_ACCOUNT_KEY na etapa anterior.

Em seguida, você pode usar essas credenciais para chamar uma API, conforme mostrado no exemplo a seguir com o UrlFetch serviço:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Substitua API_URL pelo endpoint HTTP que você está chamando.

Temas relacionados

• Criar credenciais de acesso
• Autenticar como um app do Google Chat