Аутентификация в проекте Apps Script с использованием учетных записей служб.

В этом руководстве объясняется, как выполнить аутентификацию с помощью сервисной учетной записи при вызове API в Apps Script.

Служебная учетная запись — это особый тип учетной записи, используемый приложением, а не человеком. Вы можете использовать служебную учетную запись для доступа к данным или выполнения действий от имени учетной записи робота, а также для доступа к данным от имени пользователей Google Workspace или Cloud Identity. Для получения дополнительной информации см. раздел «Понимание служебных учетных записей» .

Для получения общего обзора аутентификации для API Google Workspace см. раздел «Создание учетных данных доступа» .

Когда использовать сервисные учетные записи в Apps Script

Вот несколько причин, по которым вам может быть полезно использовать аутентификацию по служебной учетной записи вместо других методов аутентификации, таких как ScriptApp.getOAuthToken() :

• Повышенная производительность при работе с API и сервисами Google Cloud : многие API Google Cloud разработаны для аутентификации по служебным учетным записям. Служебные учетные записи также могут обеспечить более интегрированный, надежный и безопасный способ взаимодействия с большинством API.
• Разделение прав доступа : у учетных записей служб есть собственные права доступа, отдельные от прав доступа любого пользователя. Метод аутентификации ScriptApp.getOAuthToken() может завершиться ошибкой при совместном использовании проекта Apps Script с другими пользователями. Используя учетные записи служб, вы можете совместно использовать скрипты и публиковать их в качестве дополнений Google Workspace .
• Автоматизированные скрипты и длительные задачи : служебные учетные записи позволяют запускать автоматизированные скрипты, пакетные процессы или фоновые задачи без участия пользователя.
• Повышенная безопасность и принцип минимальных привилегий : вы можете предоставлять учетным записям служб определенные разрешения, обеспечивая доступ только к необходимым им ресурсам. Это соответствует принципу минимальных привилегий , что снижает риски безопасности. Использование ScriptApp.getOAuthToken() часто предоставляет скрипту все права пользователя, что может быть слишком широким.
• Централизованное управление доступом : управление учетными записями служб осуществляется с помощью системы управления идентификацией и доступом (IAM) Google Cloud. IAM может помочь организациям Google Workspace управлять доступом к аутентифицированным службам в проектах Apps Script.

Предварительные требования

• Проект Google Cloud .
• В вашем облачном проекте включите все API , для аутентификации с помощью учетных данных сервисной учетной записи.
• Для назначения ролей служебным учетным записям необходимы права суперадминистратора .

Создайте учетную запись службы

В вашем облачном проекте создайте учетную запись службы:

Консоль Google Cloud

1. В консоли Google Cloud перейдите в > IAM и администрирование > Учетные записи служб .

   Перейдите в раздел «Учетные записи служб».

2. Нажмите «Создать учетную запись службы» .
3. Заполните данные учетной записи службы, затем нажмите «Создать и продолжить» .
   Примечание: По умолчанию Google создает уникальный идентификатор сервисной учетной записи. Если вы хотите изменить идентификатор, измените его в поле «Идентификатор сервисной учетной записи».
4. Необязательно: назначьте роли вашей учетной записи службы, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Для получения более подробной информации см. раздел «Предоставление, изменение и отзыв доступа к ресурсам» .
5. Нажмите «Продолжить» .
6. Необязательно: укажите пользователей или группы, которые могут управлять этой учетной записью службы и выполнять с ней действия. Дополнительные сведения см. в разделе «Управление имитацией учетной записи службы» .
7. Нажмите «Готово» . Запишите адрес электронной почты учетной записи службы.

gcloud CLI

1. Создайте учетную запись службы:

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

2. Необязательно: назначьте роли вашей учетной записи службы, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Для получения более подробной информации см. раздел «Предоставление, изменение и отзыв доступа к ресурсам» .

Назначьте роль учетной записи службы.

Для назначения учетной записи службы предварительно созданной или пользовательской роли необходимо использовать учетную запись суперадминистратора.

1. В консоли администратора Google перейдите в > Аккаунт > Роли администратора .

   Перейдите в раздел «Административные роли».

2. Укажите роль, которую хотите назначить, и нажмите «Назначить администратора» .

3. Нажмите «Назначить учетные записи служб» .

4. Введите адрес электронной почты учетной записи службы.

5. Нажмите «Добавить» > «Назначить роль» .

Создайте учетные данные для служебной учетной записи.

Вам необходимо получить учетные данные в виде пары открытого/закрытого ключей. Эти учетные данные используются вашим кодом для авторизации действий учетной записи службы внутри вашего приложения.

Чтобы получить учетные данные для вашей служебной учетной записи:

1. В консоли Google Cloud перейдите в > IAM и администрирование > Учетные записи служб .

   Перейдите в раздел «Учетные записи служб».

2. Выберите свой сервисный аккаунт.
3. Нажмите «Клавиши» > «Добавить клавишу» > «Создать новую клавишу» .
4. Выберите JSON , затем нажмите «Создать» .

   Ваша новая пара открытого/закрытого ключей будет сгенерирована и загружена на ваш компьютер в виде нового файла. Сохраните загруженный JSON-файл как credentials.json в вашей рабочей директории. Этот файл является единственной копией данного ключа. Информацию о том, как безопасно хранить ключ, см. в разделе «Управление ключами учетных записей служб» .

5. Нажмите «Закрыть» .

Скопируйте номер облачного проекта.

1. В консоли Google Cloud перейдите в > IAM и администрирование > Настройки .

   Перейдите в раздел «Настройки IAM и администрирования».

2. В поле «Номер проекта» скопируйте значение.

Настройте аутентификацию служебной учетной записи в вашем проекте Apps Script.

В этом разделе объясняется, как добавить учетные данные сервисной учетной записи из вашего облачного проекта в проект Apps Script.

Настройте свой облачный проект в Apps Script.

1. Чтобы открыть или создать проект, перейдите в Apps Script:

   
   Open Apps Script

2. В проекте Apps Script нажмите «Настройки проекта» . .

3. В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .

4. В поле "Номер проекта GCP" вставьте номер проекта Google Cloud.

5. Нажмите «Установить проект» .

Сохраните учетные данные в качестве свойства скрипта.

Надежно храните учетные данные своей сервисной учетной записи, сохранив их в качестве свойства скрипта в настройках проекта Apps Script:

1. Скопируйте содержимое JSON-файла вашей учетной записи службы ( credentials.json ), который вы создали в предыдущем разделе .
2. В проекте Apps Script перейдите в раздел « проекта» .
3. На странице «Настройки проекта» перейдите в раздел «Свойства скрипта» , нажмите «Добавить свойство скрипта» и введите следующее:
   • В поле «Свойства» введите SERVICE_ACCOUNT_KEY .
   • В поле «Значение» вставьте содержимое вашего JSON-файла с ключами.
4. Нажмите «Сохранить свойства скрипта» .

Добавьте библиотеку OAuth2.

Для обработки процесса аутентификации OAuth2 можно использовать библиотеку Apps Script apps-script-oauth2 .

Чтобы добавить библиотеку в ваш проект Apps Script:

1. В редакторе Apps Script слева, рядом с пунктом «Библиотеки» , нажмите « библиотеку» .
2. В поле «Идентификатор скрипта» введите 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF .
3. Нажмите «Поиск» .
4. Выберите последнюю версию, а затем нажмите «Добавить» .

Вызов API с использованием учетных данных сервисной учетной записи.

Для использования учетных данных сервисной учетной записи из вашего проекта Apps Script вы можете использовать следующую функцию: 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);
}

Замените SCOPE на область авторизации , необходимую для вызова API. Скрипт использует учетные данные сервисной учетной записи, которые вы сохранили в качестве свойства скрипта SERVICE_ACCOUNT_KEY на предыдущем шаге .

Затем вы можете использовать эти учетные данные для вызова API, как показано в следующем примере с сервисом 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;
}

Замените API_URL на HTTP-адрес конечной точки, к которой вы обращаетесь.

Связанные темы

• Создать учетные данные доступа
• Аутентификация как приложение Google Chat