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

Este guia explica como fazer a autenticação 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, e não por uma pessoa. Você pode 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 nas APIs do Google Workspace, consulte Criar credenciais de acesso.

Quando usar contas de serviço no Apps Script

Confira alguns motivos para usar a autenticação da conta de serviço em vez de outros métodos, como ScriptApp.getOAuthToken():

• Melhor desempenho com APIs e serviços do Google Cloud: muitas APIs do Google Cloud são projetadas para autenticação de conta de serviço. Elas também oferecem uma maneira mais integrada, confiável e segura de interagir com a maioria das APIs.
• Permissões dissociadas: 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 do Apps Script com outros usuários. Ao usar contas de serviço, você pode compartilhar scripts e publicá-los 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 entrada do usuário.
• Segurança aprimorada e princípio do menor privilégio: é possível conceder permissões específicas a 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. Usar 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 Identity and Access Management (IAM) do Google Cloud. O IAM pode ajudar 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 do Cloud, 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 do Cloud, crie uma conta de serviço:

Console do Google Cloud

1. No console do Google Cloud, acesse 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 exclusivo de conta de serviço. Se quiser mudar o ID, modifique o 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 Conceder, alterar e revogar o 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 representação da conta de serviço.
7. Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI da 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 Conceder, alterar e revogar o acesso a recursos.

Atribuir um papel à conta de serviço

É necessário atribuir uma função predefinida ou personalizada a uma conta de serviço usando uma conta de superadministrador.

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

   Acesse 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

Você precisa conseguir credenciais na forma de um par de chaves públicas/privadas. Essas credenciais são usadas pelo seu 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 Menu > IAM e administrador > Contas de serviço.

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

2. Selecione sua 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 baixado como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia da chave. Para saber como armazenar sua chave com segurança, consulte Como gerenciar chaves de contas de serviço.

5. Clique em Fechar.

Copie o número do projeto do Google Cloud.

1. No console do Google Cloud, acesse 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

Nesta seção, explicamos como adicionar as credenciais da conta de serviço do seu projeto do Cloud a um projeto do Apps Script.

Definir seu projeto do Cloud 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 do Google Cloud Platform (GCP), clique em Mudar projeto.

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

5. Clique em Configurar projeto.

Salvar as credenciais como uma propriedade de script

Armazene as credenciais da conta de serviço com segurança salvando-as como uma propriedade de 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 seu projeto do Apps Script, acesse Configurações do projeto .
3. Na página Configurações do projeto, acesse Propriedades do script, 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 OAuth2

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

Para adicionar a biblioteca ao seu projeto do Apps Script:

1. No editor 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 seu 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, use essas credenciais para chamar uma API, conforme mostrado no exemplo a seguir com o serviço UrlFetch:

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